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