meta:
  title: "settings 탭 계약서 — 사용자 입력 파라미터"
  parent_file: "RetirementAssetPortfolio.yaml"
  version: "2026-05-17-initial"
  language: "ko-KR"
  timezone: "Asia/Seoul"
  role: "canonical"
  purpose: >
    Google Sheets 'settings' 탭의 구조를 정의한다.
    GAS 함수 readSettingsTab_()이 이 탭을 읽어 파라미터를 공급한다.
    계좌·자산 정보처럼 자동 수집이 불가한 값들을 사용자가 수동 입력하는 창구.

sheet:
  name: "settings"
  header_row: 2   # row1=updated 메타, row2=헤더
  data_start_row: 3
  columns:
    - name: "key"
      type: "string"
      note: "파라미터 식별자. GAS에서 settings['key'] 형태로 참조."
    - name: "value"
      type: "any"
      note: "파라미터 값. 숫자는 숫자로, 문자는 문자로 입력."
    - name: "note"
      type: "string"
      note: "설명 (선택). GAS가 읽지 않음."

# ─────────────────────────────────────────────────────────────────────────────
# 필수 파라미터 (설정하지 않으면 해당 기능 비활성화)
# ─────────────────────────────────────────────────────────────────────────────
required_keys:
  total_asset_krw:
    type: "number"
    unit: "KRW"
    example: 150000000
    note: >
      전체 투자 가능 자산 합계 (원화).
      사용처: Pos_Size_Qty 계산, TOTAL_HEAT_V1 퍼센트 변환, FC_BUDGET 월별 손실 비율.
      매월 말 또는 계좌 잔고 크게 변동 시 수동 갱신.
    affects:
      - "data_feed Pos_Size_Qty"
      - "macro TOTAL_HEAT 행 heat_pct"
      - "macro FC_BUDGET 행 used_pct"
    update_frequency: "월 1회 또는 자산 규모 ±5% 이상 변동 시"

# ─────────────────────────────────────────────────────────────────────────────
# 선택 파라미터
# ─────────────────────────────────────────────────────────────────────────────
optional_keys:
  risk_budget_override:
    type: "number"
    unit: "decimal (0~0.02)"
    default: 0.007
    note: >
      POSITION_SIZE_V1의 기본 risk_budget 오버라이드.
      performance_brake 발동 시 0.0035로 수동 입력.
      비워두면 GAS가 0.007 기본값 사용.
    affects:
      - "data_feed Pos_Size_Qty (atr_qty 계산)"

  fc_budget_pct_override:
    type: "number"
    unit: "percent"
    default: 2.5
    note: >
      explore_loss_budget 월별 한도 오버라이드(%).
      비워두면 GAS가 2.5% 기본값 사용.
    affects:
      - "macro FC_BUDGET 행"

  market_exchange:
    type: "string"
    default: "KRX"
    note: "현재 미사용. 향후 해외 계좌 대응 시 사용."

  settlement_cash_d2_krw:
    type: "number"
    unit: "KRW"
    note: >
      계좌 캡처에서 확인한 D+2 추정현금성자산.
      일반계좌의 D+2 정산현금과 즉시현금(immediate_cash)을 합산하여 유동성 방어선(cash_floor)으로 인정한다.
      ISA/연금저축의 현금성 자산은 일반계좌 매수재원 합산에서 제외한다.
      account_snapshot.settlement_cash_d2가 있으면 그 값을 우선 사용하고,
      settings 값은 수동 백업 입력으로 사용한다.
    affects:
      - "data_feed Rebalance_Need_KRW"
      - "data_feed Override_Sell_Qty"

  weekly_target_cash_pct:
    type: "number"
    unit: "percent"
    example: 14
    note: >
      주간 리밸런싱용 D+2 현금 목표 비중.
      입력된 경우에만 GAS가 Rebalance_Need_KRW와 Override_Sell_Qty를 계산한다.
      즉시현금 cash_floor와 혼동하지 않도록 보고서에는 D+2 기준임을 명시한다.
    affects:
      - "data_feed Rebalance_Target_Cash_Pct"
      - "data_feed Rebalance_Need_KRW"
      - "data_feed Override_Sell_Qty"

  orbit_start_asset_krw:
    type: "number"
    unit: "KRW"
    example: 355000000
    note: >
      orbit_gap 계산 기준 시작 자산 (원).
      spec/01_objective_profile.yaml 참조: 각 연도 1월 기준 총자산.
      orbit_gap = 목표누적수익률(기하평균) - 실제누적수익률 계산에 사용.
    affects:
      - "macro ORBIT_GAP 행 orbit_gap_pct"
      - "macro ORBIT_STATE 행 orbit_state"
    update_frequency: "연 1회 (1월 초) 또는 재설정 시"

  orbit_target_asset_krw:
    type: "number"
    unit: "KRW"
    example: 500000000
    note: >
      orbit_gap 계산 목표 자산 (원).
      spec/01_objective_profile.yaml: 목표 5억.
    affects:
      - "macro ORBIT_GAP 행 orbit_gap_pct"

  orbit_start_yyyymm:
    type: "string"
    format: "YYYY-MM"
    example: "2026-01"
    note: >
      orbit 추적 시작 연월. orbit_end_yyyymm까지의 총 기간으로 목표 분산.
      elapsed_months = 현재연월 - orbit_start_yyyymm (완성 월 수).
    affects:
      - "macro ORBIT_GAP/ORBIT_STATE 행 elapsed_months 계산"

  orbit_end_yyyymm:
    type: "string"
    format: "YYYY-MM"
    example: "2028-12"
    note: >
      orbit 추적 종료 연월 (목표 달성 기한).
      total_months = orbit_end_yyyymm - orbit_start_yyyymm.
    affects:
      - "macro ORBIT_GAP/ORBIT_STATE 행 total_months 계산"

# ─────────────────────────────────────────────────────────────────────────────
# 탭 초기 설정 예시 (Google Sheets에 수동 입력)
# ─────────────────────────────────────────────────────────────────────────────
initial_setup_example:
  - [key, value, note]
  - [total_asset_krw, 150000000, "총 투자 가능 자산 (원). 분기마다 갱신."]
  - [risk_budget_override, "", "비워두면 기본 0.007 사용. performance_brake 시 0.0035 입력."]
  - [fc_budget_pct_override, "", "비워두면 기본 2.5% 사용."]
  - [orbit_start_asset_krw, 355000000, "orbit 시작 자산 (1월 기준). 연 1회 갱신."]
  - [orbit_target_asset_krw, 500000000, "목표 자산. 변경 시 갱신."]
  - [orbit_start_yyyymm, "2026-01", "orbit 추적 시작 연월 (YYYY-MM)."]
  - [orbit_end_yyyymm, "2028-12", "orbit 추적 종료 연월 (목표 달성 기한)."]

# ─────────────────────────────────────────────────────────────────────────────
# GAS 자동 기록 키 (사용자가 직접 입력하지 않음 — GAS 월간 배치가 자동 갱신)
# ─────────────────────────────────────────────────────────────────────────────
gas_written_cache_keys:
  trade_quality_json:
    written_by: "calcTradeQualityScorer_()  ← F1 월간 배치"
    formula_id: "TRADE_QUALITY_SCORER_V1"
    format: "JSON 문자열"
    schema: >
      { status, scored_count, total_records,
        trade_quality: [{ ticker, action, score, grade, feedback_tag }],
        last_computed, formula_id }
    read_by:
      - "gas_harness_rows.gs buildHarnessRows_() → trade_quality_json 일간 출력"
      - "render_operational_report.py render_trade_quality_report()"
    update_frequency: "월 1회 (calcTradeQualityScorer_ 트리거 실행 시)"
    note: "사용자가 수동 편집 금지. T+5/T+20 채점 결과. 미실행 시 MONTHLY_BATCH_PENDING."

  pattern_blacklist_json:
    written_by: "calcPatternBlacklistAuto_()  ← F2 (F1 파이프라인 직후 자동 실행)"
    formula_id: "PATTERN_BLACKLIST_AUTO_V1"
    format: "JSON 문자열"
    schema: >
      { status, triggered_count, total_tickers,
        patterns: [{ ticker, pattern_blacklist_status, accumulated_poor_count,
                     total_records, release_condition_met,
                     saqg_override, alpha_score_cap, formula_id }],
        pattern_count, computed_at, formula_id }
    read_by:
      - "gas_data_feed.gs applyAlegGate4And5_() → GATE_5 블랙리스트 차단"
      - "gas_harness_rows.gs buildHarnessRows_() → pattern_blacklist_json 일간 출력"
      - "render_operational_report.py render_pattern_blacklist_report()"
    update_frequency: "월 1회 (calcTradeQualityScorer_ 배치 완료 후 자동 연결)"
    note: "TRIGGERED 종목은 ALEG GATE_5에서 BUY 자동 차단됨. 사용자 수동 편집 금지."

  alpha_feedback_json:
    written_by: "calcAlphaFeedbackLoop_()  ← AFL 월간 배치"
    formula_id: "ALPHA_FEEDBACK_LOOP_V1"
    format: "JSON 문자열"
    schema: >
      { formula_id, as_of, analysis_period, status, cases_analyzed,
        grade_count, eligible_t20_fail_rate, eligible_t60_fail_rate,
        recommended_filter_adjustments: [{ filter_id, current, recommended, action, rationale }],
        grade_summary: [{ grade, t20_total, t20_pass, t20_pass_rate, t20_fail_rate,
                          t60_total, t60_pass, t60_pass_rate, t60_fail_rate, status }] }
    read_by:
      - "gas_harness_rows.gs buildHarnessRows_() → alpha_feedback_json 일간 출력"
      - "render_operational_report.py render_alpha_feedback_loop()"
    update_frequency: "월 1회 (calcAlphaFeedbackLoop_ 트리거 실행 시)"
    note: >
      cases_analyzed < 10 이면 DATA_INSUFFICIENT — 권고 없음.
      임계값 자동 변경 금지(Direction AFL). 사용자 수동 편집 금지.

operational_rules:
  - "total_asset_krw는 입금·출금 또는 총자산 ±5% 이상 변동 시 갱신한다."
  - "performance_brake 발동 시 risk_budget_override=0.0035 입력 → 자동 반영."
  - "performance_brake 해제(reset_condition 충족) 시 risk_budget_override를 공백으로 되돌린다."
  - "gas_written_cache_keys 섹션의 키는 GAS 배치가 자동 갱신. 사용자 직접 편집 금지."