// =============================================================================
// QuantEngine Database Schema (DBML)
// DbUp 마이그레이션(V1~V5)과 1:1 동기화 — 마이그레이션 추가 시 이 파일도 반드시 갱신
// (CLAUDE.md 규칙: schema 변경 → DBML + 문서 동기화)
//
// 참고: Hangfire 스키마는 Hangfire.PostgreSql 라이브러리가 자동 생성
// (DbUp 마이그레이션으로 관리하지 않음, 여기서도 제외)
// =============================================================================

Project quantengine {
  database_type: 'PostgreSQL'
  Note: '''
    QuantEngine v0.1 데이터베이스 스키마.
    세 개 스키마로 구성:
    - quantengine: 핵심 KIS API 토큰, 사용자 계정, 수집 파이프라인 데이터
    - engine_history: 팩터 계산 이력, 시장 데이터 이력, 의사결정 이력
    - (생략) hangfire: Hangfire 백그라운드 잡 관리 (auto-created)
  '''
}

// =============================================================================
// Schema: quantengine (V1 + V2)
// =============================================================================

TableGroup "quantengine" {
  kis_tokens
  workspace_account
  workspace_session
  collection_runs
  collection_snapshots
  collection_source_errors
  settings
  account_snapshot
  workspace_meta
  workspace_change_log
  workspace_approval_v2
  workspace_lock
  kis_collection_runs
  kis_collection_snapshots
  kis_collection_errors
}

Table quantengine.kis_tokens {
  account TEXT [pk, note: "KIS 계정 모드 (real/mock)"]
  access_token TEXT [not null, note: "KIS 토큰"]
  expires_at TEXT [not null, note: "만료 시각 (ISO 8601)"]
  updated_at TEXT [not null, note: "마지막 갱신 시각 (ISO 8601)"]

  Note: "KIS Open API 인증 토큰 캐시"
}

Table quantengine.workspace_account {
  ordinal INT [not null, note: "순서 인덱스"]
  username TEXT [pk, note: "로그인 ID"]
  password_hash TEXT [not null, note: "BCrypt 또는 SHA-256 해시 (자동 마이그레이션 가능)"]
  role TEXT [not null, default: "'Admin'", note: "역할 (Admin)"]
  is_active TEXT [not null, default: "'true'", note: "활성 상태 (true/false)"]
  created_at TEXT [not null, note: "생성 시각 (ISO 8601)"]
  updated_at TEXT [not null, note: "갱신 시각 (ISO 8601)"]

  indexes {
    (is_active, username) [name: "idx_workspace_account_active"]
  }

  Note: "Admin UI 사용자 계정"
}

Table quantengine.workspace_session {
  session_token_hash TEXT [pk, note: "세션 토큰 해시"]
  username TEXT [not null, note: "사용자명"]
  role TEXT [not null, default: "'Admin'", note: "역할"]
  created_at TEXT [not null, note: "세션 생성 시각 (ISO 8601)"]
  expires_at TEXT [not null, note: "만료 시각 (ISO 8601)"]
  revoked_at TEXT [note: "취소 시각 (ISO 8601), NULL이면 활성"]

  indexes {
    (username, expires_at) [name: "idx_workspace_session_username"]
  }

  Note: "세션 관리 (쿠키 기반 인증)"
}

Table quantengine.collection_runs {
  run_id TEXT [pk, note: "수집 실행 ID (예: api-20260712-120000)"]
  collector_name TEXT [not null, note: "수집기 이름"]
  started_at TEXT [not null, note: "시작 시각 (ISO 8601)"]
  finished_at TEXT [note: "종료 시각 (ISO 8601)"]
  status TEXT [not null, note: "상태 (RUNNING/COMPLETED/FAILED)"]
  input_source TEXT [note: "입력 소스 경로"]
  output_json_path TEXT [note: "출력 JSON 파일 경로"]
  output_db_path TEXT [note: "출력 DB 경로"]
  notes TEXT [note: "메모"]
  created_at TIMESTAMP [default: "CURRENT_TIMESTAMP", note: "DB 기록 시각"]

  Note: "데이터 수집 실행 기록 (레거시, V2의 kis_collection_runs 참조)"
}

Table quantengine.collection_snapshots {
  run_id TEXT [not null, note: "수집 실행 ID"]
  dataset_name TEXT [not null, note: "데이터셋명"]
  ticker TEXT [not null, note: "종목코드 (예: 005930)"]
  name TEXT [note: "종목명"]
  sector TEXT [note: "업종"]
  as_of_date TEXT [note: "기준 일자"]
  source_priority TEXT [note: "소스 우선순위"]
  source_status TEXT [note: "소스 상태"]
  payload_json TEXT [not null, note: "정규화된 데이터 (JSON)"]
  provenance_json TEXT [not null, note: "출처 정보 (JSON)"]
  created_at TIMESTAMP [default: "CURRENT_TIMESTAMP", note: "DB 기록 시각"]

  indexes {
    (run_id, dataset_name, ticker) [pk]
    (ticker, created_at) [name: "idx_collection_snapshots_ticker_time"]
  }

  Note: "수집 스냅샷 (레거시, V2의 kis_collection_snapshots 참조)"
}

Table quantengine.collection_source_errors {
  run_id TEXT [not null, note: "수집 실행 ID"]
  ticker TEXT [note: "종목코드"]
  source_name TEXT [not null, note: "소스명"]
  error_kind TEXT [not null, note: "에러 타입"]
  error_message TEXT [not null, note: "에러 메시지"]
  payload_json TEXT [note: "에러 상세 (JSON)"]
  created_at TIMESTAMP [default: "CURRENT_TIMESTAMP", note: "DB 기록 시각"]

  indexes {
    (run_id, source_name) [name: "idx_collection_source_errors_run"]
  }

  Note: "수집 중 발생한 에러 기록 (레거시)"
}

Table quantengine.settings {
  ordinal INT [not null, note: "순서 인덱스"]
  key TEXT [pk, note: "설정 키"]
  value_json TEXT [not null, note: "값 (JSON)"]
  note TEXT [not null, default: "''", note: "설명"]
  updated_at TEXT [not null, note: "갱신 시각 (ISO 8601)"]

  Note: "애플리케이션 설정 저장소"
}

Table quantengine.account_snapshot {
  ordinal INT [not null, note: "순서 인덱스"]
  row_json TEXT [not null, note: "계정 데이터 (JSON)"]
  captured_at TEXT [not null, default: "''", note: "캡처 시각 (ISO 8601)"]
  account TEXT [not null, default: "''", note: "계정"]
  account_type TEXT [not null, default: "''", note: "계정 타입"]
  ticker TEXT [not null, default: "''", note: "종목코드"]
  name TEXT [not null, default: "''", note: "이름"]
  parse_status TEXT [not null, default: "''", note: "파싱 상태"]
  user_confirmed TEXT [not null, default: "''", note: "사용자 확인 여부"]
  updated_at TEXT [not null, note: "갱신 시각 (ISO 8601)"]

  indexes {
    (captured_at) [name: "idx_account_snapshot_captured_at"]
    (ticker) [name: "idx_account_snapshot_ticker"]
  }

  Note: "계정 스냅샷 저장소"
}

Table quantengine.workspace_meta {
  key TEXT [pk, note: "메타 키"]
  value_json TEXT [not null, note: "값 (JSON)"]

  Note: "워크스페이스 메타데이터"
}

Table quantengine.workspace_change_log {
  id SERIAL [pk, note: "자동 증가 ID"]
  domain TEXT [not null, note: "도메인"]
  action TEXT [not null, note: "액션 (create/update/delete)"]
  target_ref TEXT [not null, default: "''", note: "대상 참조"]
  actor TEXT [not null, default: "'system'", note: "액터 (사용자/시스템)"]
  note TEXT [not null, default: "''", note: "메모"]
  before_json TEXT [not null, default: "'null'", note: "변경 전 값 (JSON)"]
  after_json TEXT [not null, default: "'null'", note: "변경 후 값 (JSON)"]
  created_at TEXT [not null, note: "기록 시각 (ISO 8601)"]

  Note: "변경 로그"
}

Table quantengine.workspace_approval_v2 {
  domain TEXT [not null, note: "도메인"]
  target_ref TEXT [not null, default: "'*'", note: "대상 참조"]
  status TEXT [not null, note: "승인 상태"]
  approved_by TEXT [not null, default: "''", note: "승인자"]
  approved_at TEXT [not null, default: "''", note: "승인 시각 (ISO 8601)"]
  note TEXT [not null, default: "''", note: "메모"]
  updated_at TEXT [not null, note: "갱신 시각 (ISO 8601)"]

  indexes {
    (domain, target_ref) [pk]
  }

  Note: "승인 워크플로우"
}

Table quantengine.workspace_lock {
  domain TEXT [not null, note: "도메인"]
  target_ref TEXT [not null, default: "''", note: "대상 참조"]
  locked_by TEXT [not null, default: "''", note: "잠금 사용자"]
  reason TEXT [not null, default: "''", note: "잠금 사유"]
  locked_at TEXT [not null, note: "잠금 시각 (ISO 8601)"]

  indexes {
    (domain, target_ref) [pk]
  }

  Note: "동시성 제어용 잠금"
}

// =============================================================================
// V2: KIS 수집 파이프라인 (kis_collection_*)
// =============================================================================

Table quantengine.kis_collection_runs {
  run_id TEXT [pk, note: "수집 실행 ID"]
  status TEXT [not null, note: "상태: RUNNING / COMPLETED / COMPLETED_WITH_ERRORS / FAILED"]
  started_at TEXT [not null, note: "시작 시각 (ISO 8601 KST)"]
  finished_at TEXT [note: "종료 시각 (ISO 8601 KST)"]
  total_snapshots INTEGER [note: "성공한 스냅샷 수"]
  total_errors INTEGER [note: "발생한 에러 수"]
  updated_at TEXT [not null, note: "마지막 갱신 시각 (ISO 8601)"]

  indexes {
    (started_at) [name: "idx_kis_runs_started_at"]
  }

  Note: "KIS API 수집 실행 기록"
}

Table quantengine.kis_collection_snapshots {
  run_id TEXT [not null, note: "수집 실행 ID"]
  dataset_name TEXT [note: "데이터셋명 (예: data_feed)"]
  ticker TEXT [not null, note: "종목코드 (예: 005930)"]
  source_name TEXT [not null, note: "데이터 소스 (kis_open_api 등)"]
  payload_json TEXT [not null, note: "정규화된 수집 데이터 (JSON)"]
  captured_at TEXT [not null, note: "캡처 시각 (ISO 8601 KST)"]
  created_at TEXT [not null, note: "DB 기록 시각 (ISO 8601)"]

  indexes {
    (run_id, ticker, source_name) [pk]
    (ticker) [name: "idx_kis_snapshots_ticker"]
    (captured_at) [name: "idx_kis_snapshots_captured_at"]
  }

  Note: "KIS API 수집 스냅샷 (시계열 데이터)"
}

Table quantengine.kis_collection_errors {
  id SERIAL [pk, note: "자동 증가 ID"]
  run_id TEXT [not null, note: "수집 실행 ID"]
  source_name TEXT [not null, note: "데이터 소스"]
  error_kind TEXT [not null, note: "에러 타입 (예: HttpRequestException)"]
  error_message TEXT [note: "에러 메시지"]
  ticker TEXT [note: "종목코드 (해당하면)"]
  created_at TEXT [not null, note: "DB 기록 시각 (ISO 8601)"]

  indexes {
    (run_id) [name: "idx_kis_errors_run_id"]
  }

  Note: "KIS API 수집 중 발생한 에러"
}

// =============================================================================
// Schema: engine_history (V3)
// =============================================================================

TableGroup "engine_history" {
  market_raw_history
  factor_version_history
  factor_output_history
  decision_result_history
  market_vs_engine_gap_history
  source_observation
  factor_definition
  factor_observation
  decision_event
  decision_factor_evidence
  outcome_evaluation
}

Table engine_history.market_raw_history {
  id BIGSERIAL [pk, note: "자동 증가 ID"]
  source_id TEXT [not null, note: "소스 ID"]
  observed_at TEXT [not null, note: "관측 시각 (ISO 8601)"]
  source_name TEXT [not null, note: "소스명 (kis_open_api 등)"]
  instrument_id TEXT [not null, note: "상품 ID (종목코드 등)"]
  field_name TEXT [not null, note: "필드명 (현재가, 종가 등)"]
  field_value TEXT [not null, note: "필드값 (문자열)"]
  unit TEXT [not null, note: "단위 (원, % 등)"]
  provenance JSONB [not null, default: "'{}'::jsonb", note: "출처 메타데이터 (JSON)"]
  created_at TIMESTAMPTZ [not null, default: "NOW()", note: "DB 기록 시각 (UTC)"]

  indexes {
    (created_at) [name: "idx_market_raw_history_created_at"]
  }

  Note: "시장 데이터 원본 이력 (정규화 전)"
}

Table engine_history.factor_version_history {
  id BIGSERIAL [pk, note: "자동 증가 ID"]
  factor_id TEXT [not null, note: "팩터 ID (예: momentum_ss001)"]
  factor_version TEXT [not null, note: "팩터 버전 (예: v1.0.0)"]
  effective_from TEXT [not null, note: "유효 시작 일자 (YYYYMMDD)"]
  effective_to TEXT [not null, note: "유효 종료 일자 (YYYYMMDD)"]
  formula_id TEXT [not null, note: "계산식 ID"]
  source_version TEXT [not null, note: "소스 버전"]
  provenance JSONB [not null, default: "'{}'::jsonb", note: "출처 메타데이터 (JSON)"]
  created_at TIMESTAMPTZ [not null, default: "NOW()", note: "DB 기록 시각 (UTC)"]

  indexes {
    (created_at) [name: "idx_factor_version_history_created_at"]
  }

  Note: "팩터 버전 관리 이력"
}

Table engine_history.factor_output_history {
  id BIGSERIAL [pk, note: "자동 증가 ID"]
  factor_output_id TEXT [not null, note: "팩터 출력 ID"]
  observed_at TEXT [not null, note: "관측 일자 (YYYYMMDD)"]
  factor_id TEXT [not null, note: "팩터 ID"]
  factor_version TEXT [not null, note: "팩터 버전"]
  output_value TEXT [not null, note: "출력값 (문자열)"]
  output_gate TEXT [not null, note: "게이트 (PASS/FAIL/WARN)"]
  source_version TEXT [not null, note: "소스 버전"]
  provenance JSONB [not null, default: "'{}'::jsonb", note: "출처 메타데이터 (JSON)"]
  created_at TIMESTAMPTZ [not null, default: "NOW()", note: "DB 기록 시각 (UTC)"]

  indexes {
    (created_at) [name: "idx_factor_output_history_created_at"]
  }

  Note: "팩터 계산 결과 이력"
}

Table engine_history.decision_result_history {
  id BIGSERIAL [pk, note: "자동 증가 ID"]
  decision_id TEXT [not null, note: "의사결정 ID"]
  decided_at TEXT [not null, note: "의사결정 일자 (YYYYMMDD)"]
  instrument_id TEXT [not null, note: "상품 ID (종목코드 등)"]
  action TEXT [not null, note: "액션 (BUY/SELL/HOLD)"]
  gate TEXT [not null, note: "게이트 (PASS/FAIL)"]
  score TEXT [not null, note: "스코어 (문자열)"]
  source_version TEXT [not null, note: "소스 버전"]
  provenance JSONB [not null, default: "'{}'::jsonb", note: "출처 메타데이터 (JSON)"]
  created_at TIMESTAMPTZ [not null, default: "NOW()", note: "DB 기록 시각 (UTC)"]

  indexes {
    (created_at) [name: "idx_decision_result_history_created_at"]
  }

  Note: "의사결정 결과 이력"
}

Table engine_history.market_vs_engine_gap_history {
  id BIGSERIAL [pk, note: "자동 증가 ID"]
  gap_id TEXT [not null, note: "갭 ID"]
  observed_at TEXT [not null, note: "관측 일자 (YYYYMMDD)"]
  instrument_id TEXT [not null, note: "상품 ID"]
  metric_name TEXT [not null, note: "지표명"]
  market_value TEXT [not null, note: "시장값"]
  engine_value TEXT [not null, note: "엔진값"]
  gap_value TEXT [not null, note: "갭값 (절대값)"]
  gap_pct TEXT [not null, note: "갭 백분율 (%)"]
  source_version TEXT [not null, note: "소스 버전"]
  provenance JSONB [not null, default: "'{}'::jsonb", note: "출처 메타데이터 (JSON)"]
  created_at TIMESTAMPTZ [not null, default: "NOW()", note: "DB 기록 시각 (UTC)"]

  indexes {
    (created_at) [name: "idx_market_vs_engine_gap_history_created_at"]
  }

  Note: "시장 데이터 vs 엔진 계산 갭 분석 이력"
}

// =============================================================================
// Schema: engine_history (V5 normalized learning history)
// =============================================================================

Table engine_history.source_observation {
  observation_id UUID [pk]
  observed_at TIMESTAMPTZ [not null]
  instrument_id TEXT [not null]
  source_name TEXT [not null]
  source_version TEXT [not null]
  payload JSONB [not null]
  provenance JSONB [not null, default: "'{}'::jsonb"]
  created_at TIMESTAMPTZ [not null, default: "NOW()"]
}

Table engine_history.factor_definition {
  factor_id TEXT [not null]
  factor_version TEXT [not null]
  formula_id TEXT [not null]
  effective_from TIMESTAMPTZ [not null]
  effective_to TIMESTAMPTZ
  definition JSONB [not null, default: "'{}'::jsonb"]
  provenance JSONB [not null, default: "'{}'::jsonb"]

  indexes {
    (factor_id, factor_version) [pk]
  }
}

Table engine_history.factor_observation {
  factor_observation_id UUID [pk]
  observation_id UUID [not null]
  factor_id TEXT [not null]
  factor_version TEXT [not null]
  observed_at TIMESTAMPTZ [not null]
  numeric_value NUMERIC
  text_value TEXT
  gate TEXT [not null]
  provenance JSONB [not null, default: "'{}'::jsonb"]
}

Table engine_history.decision_event {
  decision_id UUID [pk]
  decision_key TEXT [not null, unique]
  decided_at TIMESTAMPTZ [not null]
  instrument_id TEXT [not null]
  action TEXT [not null]
  gate TEXT [not null]
  score NUMERIC
  source_version TEXT [not null]
  trace JSONB [not null, default: "'{}'::jsonb"]
  provenance JSONB [not null, default: "'{}'::jsonb"]
  created_at TIMESTAMPTZ [not null, default: "NOW()"]
}

Table engine_history.decision_factor_evidence {
  decision_id UUID [not null]
  factor_observation_id UUID [not null]
  role TEXT [not null]

  indexes {
    (decision_id, factor_observation_id) [pk]
  }
}

Table engine_history.outcome_evaluation {
  evaluation_id UUID [pk]
  decision_id UUID [not null]
  horizon_days INT [not null]
  evaluated_at TIMESTAMPTZ [not null]
  realized_return NUMERIC
  benchmark_return NUMERIC
  excess_return NUMERIC
  outcome_class TEXT [not null]
  evaluation_gate TEXT [not null]
  provenance JSONB [not null, default: "'{}'::jsonb"]

  indexes {
    (decision_id, horizon_days) [unique]
  }
}

// =============================================================================
// Relationships (Logical, not enforced as FKs in DDL)
// =============================================================================

Ref: quantengine.kis_collection_snapshots.run_id > quantengine.kis_collection_runs.run_id {
  // logical relationship: snapshots belong to a run
}

Ref: quantengine.kis_collection_errors.run_id > quantengine.kis_collection_runs.run_id {
  // logical relationship: errors belong to a run
}

Ref: quantengine.workspace_session.username > quantengine.workspace_account.username {
  // logical relationship: session belongs to a user
}

Ref: engine_history.factor_observation.observation_id > engine_history.source_observation.observation_id
Ref: engine_history.factor_observation.(factor_id, factor_version) > engine_history.factor_definition.(factor_id, factor_version)
Ref: engine_history.decision_factor_evidence.decision_id > engine_history.decision_event.decision_id
Ref: engine_history.decision_factor_evidence.factor_observation_id > engine_history.factor_observation.factor_observation_id
Ref: engine_history.outcome_evaluation.decision_id > engine_history.decision_event.decision_id