kjh2064/QuantEngineByItz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 9 Wiki Activity
Files
8dabffc08af7a66cad3ca2644f0b96a18e2a0300
QuantEngineByItz/docs/GATHERTRADINGDATA_XLSX_OPERATING_RUNBOOK.md
T
kjh2064 88e3d58664
Validators (Pushes and Pull Requests) / UI & Storage Validation (push) Failing after 18s
Details
Validators (Pushes and Pull Requests) / Core Validators & Database Setup (push) Failing after 26s
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) / Security & Secrets (push) Successful in 12s
Details
Validators (Pushes and Pull Requests) / CI Workflow Lint (push) Failing after 9s
Details
Validators (Pushes and Pull Requests) / Notify PR Results (push) Has been skipped
Details
Frontend CI Pipeline / ci-frontend-8-steps (push) Failing after 1m56s
Details
docs: archive superseded roadmap/WBS docs, fix broken install command, retire stale files 
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>
2026-07-30 11:50:25 +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/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 증빙을 다시 만드는 기준 명령은 다음 순서다.

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