ANTOOZA-BACKEND/Domain/Entities/Stocks/MacroIndicator.cs

using System.ComponentModel.DataAnnotations;

namespace Domain.Entities.Stocks;

/// <summary>
/// 거시경제지표 시계열 (KOSIS 국가통계포털 OpenAPI 수집) — (Code, Period) UNIQUE. 개미투자 거시 대시보드용.
/// 여러 지표(고용률/실업률/취업자수/CPI/환율/수출액/수입액 등)를 한 테이블에 담고 Code(내부 지표코드)로 구분한다.
/// KOSIS statisticsData.do 응답 필드 매핑:
///  - PRD_DE(수록시점) → Period. 주기(Cycle)에 따라 형식이 다르다: 월=YYYYMM(202401), 분기=YYYYQ(20241), 연=YYYY(2024).
///  - DT(수치) → Value. 빈값("")·"-" 등은 수집 시 skip (미고시 시점은 적재하지 않음).
///  - UNIT_NM(단위) → Unit. 지표별 config Name 은 Code 와 함께 표시용으로 별도 보관한다.
/// KOSIS 통계표는 하나의 tblId 안에 여러 분류(C1 시도별/지수별 등)가 섞여 오므로, 수집 배치가 config 의 분류 필터(C1)로
/// 원하는 한 계열(예: CPI 전국 총지수, 실업률 전국(계), 수출액 국가 총계)만 골라 upsert 한다.
/// </summary>
public class MacroIndicator
{
    [Key]
    public long ID { get; private set; }

    /// <summary>지표 내부코드 (config Code) — 예: EMPLOYMENT_RATE, UNEMPLOYMENT_RATE, EMPLOYED_PERSONS, CPI, FX_USD, EXPORT_AMT, IMPORT_AMT</summary>
    public string Code { get; private set; } = default!;

    /// <summary>지표 표시명 (config Name) — 예: 소비자물가지수</summary>
    public string Name { get; private set; } = default!;

    /// <summary>수록 시점 (PRD_DE) — 월=YYYYMM, 분기=YYYYQ(예 20241), 연=YYYY</summary>
    public string Period { get; private set; } = default!;

    /// <summary>수치 (DT)</summary>
    public decimal Value { get; private set; }

    /// <summary>단위 (UNIT_NM) — 예: "2020=100", "%", "천명". 미제공 시 null</summary>
    public string? Unit { get; private set; }

    public DateTime UpdatedAt { get; private set; } = DateTime.UtcNow;

    public DateTime CreatedAt { get; private set; } = DateTime.UtcNow;

    private MacroIndicator() { }

    public static MacroIndicator Create(string code, string name, string period, decimal value, string? unit)
    {
        if (string.IsNullOrWhiteSpace(code))
        {
            throw new ArgumentException("code required", nameof(code));
        }

        if (string.IsNullOrWhiteSpace(period))
        {
            throw new ArgumentException("period required", nameof(period));
        }

        return new MacroIndicator
        {
            Code = code.Trim(),
            Name = (name ?? string.Empty).Trim(),
            Period = period.Trim(),
            Value = value,
            Unit = string.IsNullOrWhiteSpace(unit) ? null : unit.Trim()
        };
    }

    /// <summary>동일 (Code, Period) 재수집 시 값·단위·표시명 갱신 (upsert)</summary>
    public void Update(string name, decimal value, string? unit)
    {
        Name = (name ?? string.Empty).Trim();
        Value = value;
        Unit = string.IsNullOrWhiteSpace(unit) ? null : unit.Trim();
        UpdatedAt = DateTime.UtcNow;
    }
}