kjh2064
88e3d58664
Validators (Pushes and Pull Requests) / UI & Storage Validation (push) Failing after 18s
Validators (Pushes and Pull Requests) / Core Validators & Database Setup (push) Failing after 26s
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) / Security & Secrets (push) Successful in 12s
Validators (Pushes and Pull Requests) / CI Workflow Lint (push) Failing after 9s
Validators (Pushes and Pull Requests) / Notify PR Results (push) Has been skipped
Frontend CI Pipeline / ci-frontend-8-steps (push) Failing after 1m56s
Archives 6 more superseded planning docs to docs/archive/ (ROADMAP_WBS.md, MODERNIZATION_ROADMAP_VISUAL.md, MODERNIZATION_STRATEGY_ROADMAP_2026-2027.md, ROADMAP_ENTERPRISE_TEMPLATES_WBS.md, EXECUTION_PLAN_PHASE0_CLOSEOUT_AND_PHASE1_KICKOFF.md, CICD_ROADMAP.md), each replaced by a current source of truth (CLAUDE.md, docs/MIGRATION_STATUS.md, or the OMS·WMS·ERP spec/playbook), and repoints 4 files that linked to the pre-archive path. Fixes README's top-of-file install instructions and package.json's "ops:dev" script, both of which pointed at core_satellite_collector.js - a file that has never existed anywhere in this repo's git history. The real, working entry point (tools/run_kis_data_collection_v1.py / npm run ops:data-collect) was already correctly documented further down the same README. Also finishes retiring pre-existing stale state that predates this session: removes the superseded deploy-prod.yml.backup, completes the already-in-progress removal of the old src/client/ Vue+AG-Grid prototype (superseded by src/frontend/), and untracks test-results/.last-run.json (Playwright's own run-metadata file, regenerated every test run - shouldn't be version controlled). 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/archive/ROADMAP_WBS.md`(2026-07-30 archive됨)의 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로 이동시키는 문서다.
|