QuantEngineByItz/README.md

# Core/Satellite Collector v4

은퇴자산용 코어/위성 후보 데이터 수집기입니다.

## v4 기본 정책

- 파라미터 없이 실행
- 1차 유니버스: KOSPI 160개 + KOSDAQ 40개
- 최종 후보: 100개
- 최종 후보 내 KOSDAQ: 최대 20개
- 1차 탐색 총량은 v3와 동일한 200개로 유지하여 호출 수 증가를 막습니다.

## KIS 사용 가이드

이 저장소의 데이터 팩터 수집 기본 코어는 KIS Open API입니다.

- 실제계좌: `KIS_APP_Key`, `KIS_APP_Secret`
- 모의계좌: `KIS_APP_Key_TEST`, `KIS_APP_Secret_TEST`
- API 유효성 확인은 모의계좌 환경변수로 수행하고, 데이터 수집은 실제계좌 환경변수로 수행
- 사용 범위: 조회형 `quotations` / `ranking` 계열만 사용
- 금지 범위: 주문, 정정, 취소, 잔고조회는 사용하지 않음
- 폴백 순서: `KIS -> Naver Finance -> Yahoo Finance -> OpenDART -> Investing.com(best-effort)`

CI 스케줄러는 `GatherTradingData.json`을 seed snapshot으로 사용하고, read-only API로 보강한 뒤 SQLite에 누적 저장합니다.
코드는 저장 백엔드를 `backend contract`로 분리해 두었고, 지금은 SQLite만 실행하지만 향후 PostgreSQL로 옮겨도 수집기 호출부를 크게 바꾸지 않도록 해 둔 상태입니다.

## 설치

```powershell
npm install
```

**⚠️ 2026-07-30 정정**: 이 섹션은 예전에 `node core_satellite_collector.js`를 실행 커맨드로
안내했지만, 그 파일은 git 히스토리에 한 번도 존재한 적이 없다 (`package.json`의 `ops:dev`
스크립트도 같은 phantom 파일을 가리키고 있어 같은 날 함께 정리함). 실제 수집기는
Python으로 구현되어 있다 — 아래 커맨드를 사용할 것.

SQLite 기반 데이터 수집을 실행하려면:

```powershell
$env:KIS_APP_Key="실제계좌키"
$env:KIS_APP_Secret="실제계좌시크릿"
python tools/run_kis_data_collection_v1.py --input-json GatherTradingData.json --sqlite-db src/quant_engine/kis_data_collection.db --output-json Temp/kis_data_collection_v1.json --kis-account real
# 또는: npm run ops:data-collect
```

OpenDART 공시까지 확인하려면 (2026-07-30 기준 `_dart_fundamentals()`는 아직 스텁 — 실제
호출은 미구현, `tools/ingest_fundamental_raw.py` 참고):

```powershell
$env:OPENDART_OPENAPI_KEY="발급받은키"
python tools/ingest_fundamental_raw.py
```

### Snapshot admin web UI

엑셀처럼 `settings`와 `account_snapshot`를 편집하려면 웹 UI를 실행한다.

```bash
python tools/run_snapshot_admin_server_v1.py --host 127.0.0.1 --port 8787 --db src/quant_engine/snapshot_admin.db --seed GatherTradingData.json
```

핫 리로드로 띄우려면 `python tools/run_snapshot_admin_server_v1.py --reload --host 127.0.0.1 --port 8787 --db src/quant_engine/snapshot_admin.db --seed GatherTradingData.json` 또는 `npm run ops:snapshot-web-watch`를 사용한다.

기본 흐름은 다음과 같다.

1. `GatherTradingData.json` 또는 기존 SQLite DB를 seed로 적재
2. 웹 화면에서 `settings`와 `account_snapshot`을 검토/편집
3. 저장 시 SQLite에 반영
4. 필요하면 `/api/export`로 JSON을 내려받아 CI 또는 검증에 사용
5. 변경 이력, 승인, 잠금, undo는 웹 화면의 `Approval & Locks` 영역에서 관리
6. 변경 검토용 승인 패킷은 `Export approval packet` 버튼으로 `Temp/snapshot_admin_approval_packet_v1.json`에 저장한다.

웹 UI 스모크 검증은 아래 명령으로 실행한다.

```bash
python tools/validate_snapshot_admin_web_v1.py
```
```

### Calibration backlog

보정 백로그와 change ledger를 다시 만들려면 아래 명령을 사용한다.

```powershell
python tools/build_calibration_priority_v1.py
python tools/build_calibration_change_ledger_v4.py
python tools/build_calibration_review_report_v1.py
python tools/build_calibration_approval_list_v1.py
python tools/validate_calibration_change_ledger_v1.py
```

Gitea 스케줄러에서는 `.gitea/workflows/calibration_backlog.yml`이 weekday 자동 갱신을 수행한다.

## 운영 표준

릴리즈와 패키징의 기준 진입점은 아래를 사용합니다.

```powershell
npm run ops:release
```

릴리즈 DAG의 엄격 판정이 필요하면 아래를 사용합니다.

```powershell
npm run full-gate
```

패키지 생성은 아래를 사용합니다.

```powershell
npm run prepare-upload-zip
```

`ops:release`는 릴리즈 DAG 전체를 실행하고, 일부 `warn_only` 검증은 `PASS_WITH_WARNINGS`로 기록합니다.
`full-gate`와 `validate-engine-strict`는 엄격 모드로 동일한 릴리즈 DAG를 재검증합니다.

추가 스크립트:

- `npm run ops:package`
- `npm run ops:validate`
- `npm run ops:build`
- `npm run ops:snapshot-web-validate`
- `npm run render-report-json`
- `npm run validate-proposal-reference`
- `npm run validate-gas-call-arity`

## GAS 반영 체크리스트

`proposal_reference_json`을 실제 하네스 출력으로 승격하려면 아래 순서를 따릅니다.

1. Apps Script에 최신 [gas_harness_rows.gs](/C:/Temp/data_feed/gas_harness_rows.gs:73) 반영
2. Apps Script에서 `runHarnessRefresh_()` 실행
3. Google Sheets `harness_context` 시트에 아래 키 생성 확인
   - `proposal_reference_json`
   - `proposal_reference_lock`
4. 로컬에서 `npm run ops:prepare` 실행
5. `npm run ops:release` 실행
6. `npm run full-gate` 실행
7. 최종 운영 전환 시 `npm run prepare-upload-zip`로 패키지 생성 여부를 확인

## CI 전환 체크리스트

1. `python tools/run_kis_data_collection_v1.py` 또는 `npm run ops:data-collect`로 SQLite 수집을 먼저 검증
2. `src/quant_engine/kis_data_collection.db`에 `collection_runs` / `collection_snapshots`가 생성되는지 확인
3. Gitea 스케줄러가 `GatherTradingData.json`을 seed로 읽는지 확인
4. `GatherTradingData.xlsx` 의존성을 제거한 후에도 수집이 유지되는지 확인
5. 이후 PostgreSQL 업그레이드 시 동일 row contract를 유지

## CI / 배포 분리

- `.gitea/workflows/ci.yml`은 검증 전용이다.
- `.gitea/workflows/deploy-prod.yml`은 실배포 전용이다.
- 공개 URL `http://178.104.200.7/quant/` 갱신은 deploy workflow 성공 여부로 판단한다.

## 운영 리포트 계약

운영 리포트는 .NET canonical renderer가 사람이 읽는 `Temp/operational_report.md`와 기계 검증용 `Temp/operational_report.json`을 함께 생성합니다.
운영 상태와 legacy 분리는 [DOTNET_RENDERER_OPERATING_STATUS.md](/C:/Temp/data_feed/docs/DOTNET_RENDERER_OPERATING_STATUS.md)에서 확인합니다.

- `src/dotnet/QuantEngine.Tools/Program.cs`가 canonical 생성 경로입니다.
- `npm run render-report-json`도 같은 .NET 경로를 호출합니다.
- `operational_report.json`이 canonical 계약입니다.
- `operational_report.md`는 표시용 렌더입니다.
- `Temp/missing_data_inventory_v1.json`은 `DATA_MISSING` 섹션 분리 인벤토리입니다.
- JSON 스키마는 `schemas/operational_report.schema.json`을 사용합니다.
- 계약 드리프트 검사는 `npm run validate-operational-report-contract`로 수행합니다.
- 전체 게이트에는 `render-report-json -> validate-report-json -> validate-report-quality -> validate-report-sync` 순서가 포함됩니다.

전환 기준:
- `validate-proposal-reference` 결과와 `ops:release` 결과를 함께 봅니다.
- `prepare-upload-zip`가 `PASS_WITH_WARNINGS`를 출력하면 warn_only 검증 이슈가 남아 있는 상태입니다.