kjh2064/QuantEngineByItz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity
Files
fa0da0b159136a232bc4c50825a3f47646d21272
QuantEngineByItz/docs/GATHERTRADINGDATA_XLSX_OPERATING_RUNBOOK.md
T
kjh2064 0a2f0eb4a1
Validators (Pushes and Pull Requests) / UI & Storage Validation (push) Failing after 15s
Details
Validators (Pushes and Pull Requests) / Core Validators & Database Setup (push) Failing after 25s
Details
Validators (Pushes and Pull Requests) / WBS & Audit Validations (push) Has been skipped
Details
Validators (Pushes and Pull Requests) / .NET Contracts (push) Has been skipped
Details
Validators (Pushes and Pull Requests) / Calibration & Performance (push) Has been skipped
Details
Validators (Pushes and Pull Requests) / Operational Report & Decision Packet (push) Has been skipped
Details
Validators (Pushes and Pull Requests) / Database & Schema Validation (push) Successful in 12s
Details
Validators (Pushes and Pull Requests) / CI Workflow Lint (push) Failing after 11s
Details
Validators (Pushes and Pull Requests) / Security & Secrets (push) Successful in 12s
Details
Workflow Lint & Validation / Lint All Workflow Files (push) Failing after 13s
Details
Workflow Lint & Validation / Validate Secrets Contract (push) Successful in 6s
Details
Frontend CI Pipeline / ci-frontend-8-steps (push) Failing after 2m5s
Details
Validators (Pushes and Pull Requests) / Notify PR Results (push) Has been skipped
Details
Workflow Lint & Validation / Notify Lint Results (push) Failing after 1s
Details
Qualitative Sell Strategy Pipeline / Validate Qualitative Sell Strategy (push) Failing after 7s
Details
Qualitative Sell Strategy Pipeline / Notify Strategy Validation Status (push) Failing after 1s
Details
fix: un-archive two docs that CI/release-gate validators depend on 
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>
2026-07-30 12:36:20 +09:00

3.9 KiB
Raw Blame History

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 증빙을 다시 만드는 기준 명령은 다음 순서다.

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로 이동시키는 문서다.

Reference in New Issue View Git Blame Copy Permalink