kjh2064
0a2f0eb4a1
Validators (Pushes and Pull Requests) / UI & Storage Validation (push) Failing after 15s
Validators (Pushes and Pull Requests) / Core Validators & Database Setup (push) Failing after 25s
Validators (Pushes and Pull Requests) / WBS & Audit Validations (push) Has been skipped
Validators (Pushes and Pull Requests) / .NET Contracts (push) Has been skipped
Validators (Pushes and Pull Requests) / Calibration & Performance (push) Has been skipped
Validators (Pushes and Pull Requests) / Operational Report & Decision Packet (push) Has been skipped
Validators (Pushes and Pull Requests) / Database & Schema Validation (push) Successful in 12s
Validators (Pushes and Pull Requests) / CI Workflow Lint (push) Failing after 11s
Validators (Pushes and Pull Requests) / Security & Secrets (push) Successful in 12s
Workflow Lint & Validation / Lint All Workflow Files (push) Failing after 13s
Workflow Lint & Validation / Validate Secrets Contract (push) Successful in 6s
Frontend CI Pipeline / ci-frontend-8-steps (push) Failing after 2m5s
Validators (Pushes and Pull Requests) / Notify PR Results (push) Has been skipped
Workflow Lint & Validation / Notify Lint Results (push) Failing after 1s
Qualitative Sell Strategy Pipeline / Validate Qualitative Sell Strategy (push) Failing after 7s
Qualitative Sell Strategy Pipeline / Notify Strategy Validation Status (push) Failing after 1s
docs/ROADMAP_WBS.md and docs/ROADMAP_ENTERPRISE_TEMPLATES_WBS.md were archived in an earlier commit today as "superseded planning docs," but that judgment only checked CLAUDE.md/README/other docs for references - not the actual validator scripts, spec YAMLs, and unit tests that drive the release gate. Both paths turn out to be load-bearing: - docs/ROADMAP_WBS.md is read directly by tools/validate_quant_engine_wbs_v1.py, tools/validate_platform_transition_wbs_v1.py, tests/unit/test_validate_quant_engine_wbs_v1.py, and referenced by spec/60_quant_engine_wbs.yaml and others. - docs/ROADMAP_ENTERPRISE_TEMPLATES_WBS.md is read by tools/validate_enterprise_crud_specification_v1.py, which runs as the "Enterprise Contract Parity Test" step in .gitea/workflows/ci-frontend.yml. Moved both back to their original path, replaced the stale "ARCHIVED" banner with a note explaining why they can't be archived without first updating the validators, and fixed the 4 doc cross-references that had been repointed at docs/archive/. Verified all three affected validators now exit 0 by actually running them locally. The other 9 docs archived earlier today (5 CI/CD docs + CICD_ROADMAP.md, EXECUTION_PLAN_PHASE0_CLOSEOUT_AND_PHASE1_KICKOFF.md, MODERNIZATION_ROADMAP_VISUAL.md, MODERNIZATION_STRATEGY_ROADMAP_2026-2027.md) were checked against the same grep sweep (*.py/*.yaml/*.yml/*.js/*.ts/*.cs/*.json, whole repo) and have zero references outside markdown - those archivals stand. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
90 lines
3.9 KiB
Markdown
90 lines
3.9 KiB
Markdown
# GatherTradingData.xlsx Operating Runbook
|
|
|
|
## 목적
|
|
|
|
이 문서는 `GatherTradingData.xlsx`를 운영 경로가 아닌 **보조 자산**으로 취급하는 절차를 정의한다.
|
|
|
|
## 원칙
|
|
|
|
- 1차 seed snapshot은 `GatherTradingData.json`이다.
|
|
- `GatherTradingData.xlsx`는 직접 입력이 아니다.
|
|
- workbook이 필요한 작업은 별도 seed-prep에서만 수행한다.
|
|
- KIS 수집, snapshot admin, platform transition 검증은 JSON/SQLite 우선을 따른다.
|
|
- KIS Open API access token은 `Temp/kis_tokens.db`에 저장하고, `TOKEN_REFRESH_SKEW_MINUTES=10` 기준으로 만료 전 재사용한다.
|
|
- 토큰 캐시 경로는 `KIS_TOKEN_DB_PATH` 환경변수로 오버라이드할 수 있다.
|
|
|
|
## 보관 정책
|
|
|
|
`GatherTradingData.xlsx`는 다음 두 경우에만 보관한다.
|
|
|
|
1. seed-prep 복구
|
|
2. 이관/검증 보조
|
|
|
|
즉, 이 파일은 삭제 대상이 아니라 **아카이브 가능한 보조 자산**이다.
|
|
|
|
## 허용 사용
|
|
|
|
`GatherTradingData.xlsx`는 다음 상황에서만 사용한다.
|
|
|
|
1. seed-prep 복구
|
|
2. workbook to JSON 이관
|
|
3. 운영 장애 후 seed 재구성
|
|
4. 회귀 검증용 보조 입력
|
|
|
|
## 금지 사용
|
|
|
|
- KIS 수집 workflow의 직접 1차 입력
|
|
- JSON이 있는 상태에서 workbook을 다시 1차 권위로 간주하는 행위
|
|
- xlsx를 이유 없이 다운로드/재생성하는 자동화
|
|
|
|
## 절차
|
|
|
|
1. `GatherTradingData.json`이 있으면 그 파일을 우선 사용한다.
|
|
2. JSON이 없고 workbook 변환이 필요하면 `tools/convert_xlsx_to_json.py`를 별도 seed-prep 단계에서 실행한다.
|
|
3. `docs/ROADMAP_WBS.md`의 WBS-8.2를 따른다.
|
|
4. `tools/validate_platform_transition_wbs_v1.py`와 `tools/validate_snapshot_admin_web_v1.py`를 확인한다.
|
|
5. KIS 토큰은 `src/quant_engine/kis_api_client_v1.py`가 SQLite 캐시로 관리하므로, 수집 재실행 시에도 토큰을 매번 새로 발급하지 않는다.
|
|
6. 토큰 상태는 `python tools/inspect_kis_token_cache_v1.py`로 확인한다.
|
|
|
|
## 재생성 명령
|
|
|
|
`Temp` 증빙을 다시 만드는 기준 명령은 다음 순서다.
|
|
|
|
```powershell
|
|
python tools/run_kis_data_collection_v1.py --input-json GatherTradingData.json --sqlite-db Temp/test_kis_data_collection.db --output-json Temp/test_kis_data_collection.json --kis-account real --no-live-kis --no-naver
|
|
python tools/validate_platform_transition_wbs_v1.py
|
|
python tools/validate_snapshot_admin_web_v1.py
|
|
```
|
|
|
|
## 재생성 판정
|
|
|
|
- `Temp/test_kis_data_collection.json`의 `status=PASS`
|
|
- `Temp/test_kis_data_collection.json`의 `row_count>0`
|
|
- `Temp/test_kis_data_collection.json`의 `source_counts.gathertradingdata_json>0`
|
|
- `Temp/test_kis_data_collection.db`의 `collection_runs>0`
|
|
- `Temp/test_kis_data_collection.db`의 `collection_snapshots>0`
|
|
- `Temp/test_kis_data_collection.db`의 `collection_source_errors=0`
|
|
- `Temp/snapshot_admin_web_validation.db`의 `account_snapshot`, `settings`, `workspace_approval_v2`, `workspace_change_log`, `workspace_lock` 존재
|
|
- `python tools/validate_platform_transition_wbs_v1.py` PASS
|
|
- `python tools/validate_snapshot_admin_web_v1.py` PASS
|
|
|
|
## 파일별 해석
|
|
|
|
`GatherTradingData.json` seed, `Temp/test_kis_data_collection.json` summary, `Temp/test_kis_data_collection.db` collector DB, `Temp/snapshot_admin_web_validation.db` snapshot DB, `Temp/snapshot_admin_approval_packet_v1.json` approval packet.
|
|
|
|
## 완료 판정
|
|
|
|
이 runbook이 유효하려면 다음이 충족되어야 한다.
|
|
|
|
- JSON 우선 workflow가 xlsx를 직접 재생성하지 않는다.
|
|
- xlsx는 보조 자산으로만 남는다.
|
|
- SQLite 우선 실행 경로가 1차 권위다.
|
|
- KIS 토큰 캐시는 수집 DB와 분리되어야 하며, 기본 경로는 `Temp/kis_tokens.db`다.
|
|
- 토큰 갱신은 `TOKEN_REFRESH_SKEW_MINUTES` 기준으로만 다시 호출한다.
|
|
- 토큰 캐시 진단은 `python tools/inspect_kis_token_cache_v1.py --json`를 사용한다.
|
|
|
|
## 비고
|
|
|
|
이 문서는 xlsx를 폐기하지 않는다.
|
|
운영 권위만 JSON/SQLite로 이동시키는 문서다.
|