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는 다음 두 경우에만 보관한다.

seed-prep 복구
이관/검증 보조

즉, 이 파일은 삭제 대상이 아니라 아카이브 가능한 보조 자산이다.

허용 사용

GatherTradingData.xlsx는 다음 상황에서만 사용한다.

seed-prep 복구
workbook to JSON 이관
운영 장애 후 seed 재구성
회귀 검증용 보조 입력

금지 사용

KIS 수집 workflow의 직접 1차 입력
JSON이 있는 상태에서 workbook을 다시 1차 권위로 간주하는 행위
xlsx를 이유 없이 다운로드/재생성하는 자동화

절차

GatherTradingData.json이 있으면 그 파일을 우선 사용한다.
JSON이 없고 workbook 변환이 필요하면 tools/convert_xlsx_to_json.py를 별도 seed-prep 단계에서 실행한다.
docs/ROADMAP_WBS.md의 WBS-8.2를 따른다.
tools/validate_platform_transition_wbs_v1.py와 tools/validate_snapshot_admin_web_v1.py를 확인한다.
KIS 토큰은 src/quant_engine/kis_api_client_v1.py가 SQLite 캐시로 관리하므로, 수집 재실행 시에도 토큰을 매번 새로 발급하지 않는다.
토큰 상태는 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로 이동시키는 문서다.

3.9 KiB Raw Blame History