fix: unify OpenDART env var name with Gitea Secrets; add missed migration header notes

tools/ingest_fundamental_raw.py read DART_API_KEY, but the Gitea Secret
is registered as OPENDART_OPENAPI_KEY, and no workflow bridges the two
(none currently invoke this script). Renamed the code side to match
the secret name directly rather than adding a mapping layer, so
whenever this gets wired into a workflow it just works. Updated the
matching README setup instructions.

Also includes the V9/V10 migration header explanations (why they were
renamed from V003/V004) that were written earlier but missed from the
previous commit's file list.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

CLAUDE.md

@@ -286,16 +286,14 @@ Pipeline) and Collection Run status/success-criteria definitions:
 
 ## OpenDART Fallback API (2026-07-30)
 
-**Credential**: Gitea Secrets에는 `OPENDART_OPENAPI_KEY`라는 이름으로 이미 등록되어 있음
-(사용자 확인, 2026-07-30). **⚠️ 이름 불일치 주의**: 실제 코드(`tools/ingest_fundamental_raw.py:55`,
-`os.environ.get("DART_API_KEY")`)는 `DART_API_KEY`라는 *다른* 환경변수명을 읽는다. `.gitea/workflows/`
-전체를 확인했지만 `OPENDART_OPENAPI_KEY` → `DART_API_KEY` 매핑이 어떤 워크플로우에도 없다 —
-즉 지금 이 스크립트를 CI에서 돌리면 Gitea Secrets에 값이 있어도 코드가 못 읽는다. 다음 중
-하나로 해소해야 함(사람 판단 필요, 여기서는 실행하지 않음):
-  (a) 워크플로우 step에 `env: DART_API_KEY: ${{ secrets.OPENDART_OPENAPI_KEY }}` 매핑 추가, 또는
-  (b) 코드가 읽는 환경변수명을 `OPENDART_OPENAPI_KEY`로 통일.
-로컬 개발 시에는 이름 불일치와 무관하게 `DART_API_KEY`로 설정해야 현재 코드가 그대로 동작한다.
-실제 키 값은 코드/문서/워크플로우 파일에 절대 하드코딩하지 않는다(KIS와 동일 원칙).
+**Credential**: `OPENDART_OPENAPI_KEY` 환경변수 — Gitea Secrets에 이미 이 이름으로 등록되어
+있음(사용자 확인, 2026-07-30). 코드(`tools/ingest_fundamental_raw.py:56`,
+`os.environ.get("OPENDART_OPENAPI_KEY")`)가 읽는 이름도 동일하게 통일했다 (원래
+`DART_API_KEY`를 읽고 있어 Gitea Secrets 이름과 어긋났던 것을 2026-07-30에 수정 — 로컬
+개발 시에도 `OPENDART_OPENAPI_KEY`로 설정할 것). 실제 키 값은 코드/문서/워크플로우 파일에
+절대 하드코딩하지 않는다(KIS와 동일 원칙). 참고: 이 스크립트를 실제로 호출하는 CI 워크플로우는
+아직 없다 — 나중에 워크플로우에 연결할 때 `env: OPENDART_OPENAPI_KEY: ${{ secrets.OPENDART_OPENAPI_KEY }}`
+만 추가하면 됨(매핑 불필요, 이름이 이미 같음).
 
 **⚠️ CRITICAL: 일일 호출 한도 40,000건** — OpenDART는 계정당 하루 40,000건으로 제한된다.
 이 한도를 넘으면 그날 나머지 호출이 전부 실패한다. DART를 호출하는 모든 코드(현재는

README.md

@@ -34,7 +34,7 @@ node core_satellite_collector.js
 OpenDART 공시까지 확인하려면:
 
 ```powershell
-$env:DART_API_KEY="발급받은키"
+$env:OPENDART_OPENAPI_KEY="발급받은키"
 node core_satellite_collector.js
 ```
 

src/dotnet/QuantEngine.Infrastructure/Migrations/V10__Normalize_Snapshots_Schema.sql

@@ -1,8 +1,18 @@
--- Migration: V004_normalize_snapshots_schema.sql
+-- Migration: V10__Normalize_Snapshots_Schema.sql (renamed from
+-- V004_normalize_snapshots_schema.sql on 2026-07-30 — see note below)
 -- Purpose: Implement 3NF normalization for kis_collection_snapshots
 -- Phase: Phase 1 (Normalization & SOLID Refactoring)
 -- Status: APPROVED for Sep 2026 implementation
 -- Safety: Parallel operation with existing schema via Adapter pattern
+--
+-- 2026-07-30: Originally named V004_normalize_snapshots_schema.sql, which alphabetically
+-- sorted BEFORE V1__Initial_Schema.sql. Its FK constraint referencing
+-- quantengine.kis_collection_runs(id) (created by V2) is not guarded — on a fresh database
+-- this would hard-fail with "relation does not exist" and abort every migration after it,
+-- meaning V1 through V8 would never run at all. Renamed to V10 (after DbMigrator.cs was given
+-- a numeric-aware script comparer, MigrationScriptNameComparer, so double-digit versions sort
+-- correctly) so it now runs after its dependency exists. Confirmed via production query that
+-- this migration had never actually applied.
 
 -- ============================================================================
 -- DIMENSION TABLES (Star Schema)

src/dotnet/QuantEngine.Infrastructure/Migrations/V9__Add_Audit_Trail_Tables.sql

@@ -1,7 +1,18 @@
--- Migration: V003_add_audit_trail_tables.sql
+-- Migration: V9__Add_Audit_Trail_Tables.sql (renamed from V003_add_audit_trail_tables.sql
+-- on 2026-07-30 — see header note below)
 -- Purpose: Add audit trail tables for tracking all data changes
 -- Date: 2026-07-24
 -- Status: APPROVED for Phase 0 implementation
+--
+-- 2026-07-30: Originally named V003_add_audit_trail_tables.sql, which alphabetically sorted
+-- BEFORE V1__Initial_Schema.sql. Its trigger-creation guards (IF EXISTS checks on
+-- kis_collection_runs / kis_collection_snapshots) would have silently no-op'd forever on a
+-- fresh database, since those tables (created by V2) wouldn't exist yet when V003 ran first.
+-- Renamed to V9 (after DbMigrator.cs was given a numeric-aware script comparer,
+-- MigrationScriptNameComparer, so "V9"/"V10" sort correctly relative to "V1".."V8" regardless
+-- of digit count) so it now runs after its dependencies exist. Also fixed a MySQL-only inline
+-- INDEX syntax that made this script fail outright on PostgreSQL (separate fix, same day).
+-- Confirmed via production query that this migration had never actually applied before either fix.
 
 -- ============================================================================
 -- kis_collection_runs_audit: Audit trail for collection runs

tools/ingest_fundamental_raw.py

@@ -52,7 +52,8 @@ DEFAULT_JSON = ROOT / "GatherTradingData.json"
 DEFAULT_OUT = TEMP = ROOT / "Temp" / "fundamental_raw_v1.json"
 
 # API Keys
-DART_API_KEY = os.environ.get("DART_API_KEY")
+# 환경변수명은 Gitea Secrets에 이미 등록된 OPENDART_OPENAPI_KEY와 통일한다 (2026-07-30).
+DART_API_KEY = os.environ.get("OPENDART_OPENAPI_KEY")
 DART_CORP_MAP_CACHE = TEMP / "dart_corp_map.json"
 
 # ETF 식별자 패턴