XRLib/Assets/Scripts/UVC/Data/DataMask.cs

#nullable enable

using Newtonsoft.Json.Linq;
using System.Collections.Generic;

namespace UVC.Data
{
    /// <summary>
    /// JSON 데이터의 구조와 변환 규칙을 정의하는 마스크 클래스입니다.
    /// Newtonsoft.Json.Linq.JObject를 상속하여 JSON 데이터 구조를 표현하고,
    /// 데이터 매핑, 필드 이름 변환, 그리고 타입 변환을 위한 메타데이터를 제공합니다.
    /// </summary>
    /// <remarks>
    /// DataMask는 주로 DataMapper 클래스와 함께 사용되어 서로 다른 JSON 형식 간의
    /// 데이터 변환 및 매핑 규칙을 정의합니다. 기본 JSON 구조 외에도 추가 속성들을
    /// 통해 매핑 과정에서 필요한 메타데이터를 제공합니다.
    /// </remarks>
    /// <example>
    /// 기본 사용 예시:
    /// <code>
    /// // 마스크 객체 생성 및 설정
    /// var mask = new DataMask();
    /// mask["name"] = "";              // 문자열 타입 지정
    /// mask["age"] = 0;                // 정수 타입 지정
    /// mask["isActive"] = false;       // 불리언 타입 지정
    /// mask["height"] = 0.0;           // 실수 타입 지정
    /// 
    /// // 메타 속성 설정
    /// mask.ObjectIdKey = "name";      // DataObject의 ID로 사용할 필드 지정
    /// mask.ObjectName = "employees";  // 데이터 객체의 이름 지정
    /// 
    /// // 필드 이름 변환 규칙 설정
    /// mask.NamesForReplace = new Dictionary&lt;string, string&gt;
    /// {
    ///     { "full_name", "name" },    // JSON의 full_name을 name으로 변환
    ///     { "employee_age", "age" }   // JSON의 employee_age를 age로 변환
    /// };
    /// 
    /// // 매핑 예시 (DataMapper 클래스와 함께 사용)
    /// var sourceJson = JObject.Parse(@"{
    ///     ""full_name"": ""김철수"",
    ///     ""employee_age"": 30,
    ///     ""isActive"": true,
    ///     ""height"": 175.5
    /// }");
    /// 
    /// var mapper = new DataMapper(mask);
    /// DataObject result = mapper.Mapping(sourceJson);
    /// // result는 변환된 필드 이름과 타입을 가진 DataObject 객체
    /// </code>
    /// </example>
    public class DataMask : JObject
    {
        /// <summary>
        /// DataObject의 Id에 해당하는 key 문자열입니다.
        /// 이 속성은 매핑된 DataObject에서 고유 식별자로 사용될 필드를 지정합니다.
        /// null인 경우 DataObject의 기본 동작을 따릅니다.
        /// </summary>
        /// <example>
        /// <code>
        /// var mask = new DataMask();
        /// mask.ObjectIdKey = "userId";  // DataObject에서 "userId" 필드가 Id로 사용됨
        /// </code>
        /// </example>
        public string? ObjectIdKey { get; set; } = null;

        /// <summary>
        /// DataObject의 이름을 나타내는 속성입니다. DataRepository에서 사용됩니다.
        /// 이 이름은 매핑된 DataObject를 분류하거나 식별하는 데 사용될 수 있습니다.
        /// </summary>
        /// <example>
        /// <code>
        /// var mask = new DataMask();
        /// mask.ObjectName = "users";  // 매핑된 DataObject는 "users"라는 이름을 가짐
        /// </code>
        /// </example>
        public string ObjectName { get; set; } = string.Empty;

        /// <summary>
        /// 원본 JSON에서 매핑된 DataObject로 필드 이름을 변환하는 규칙을 정의하는 딕셔너리입니다.
        /// 키는 원본 JSON의 필드 이름이고, 값은 변환될 대상 필드 이름입니다.
        /// </summary>
        /// <remarks>
        /// 이 속성을 통해 서로 다른 명명 규칙을 사용하는 JSON 구조 간의 매핑을 용이하게 할 수 있습니다.
        /// 예를 들어, snake_case를 사용하는 API 응답을 camelCase로 변환하는 데 사용할 수 있습니다.
        /// </remarks>
        /// <example>
        /// <code>
        /// var mask = new DataMask();
        /// mask.NamesForReplace = new Dictionary&lt;string, string&gt;
        /// {
        ///     { "first_name", "firstName" },
        ///     { "last_name", "lastName" },
        ///     { "birth_date", "birthDate" }
        /// };
        /// </code>
        /// </example>
        public Dictionary<string, string>? NamesForReplace { get; set; }

    }
}