alt/docs/kis-live-secret-handoff.md

# KIS Live Secret Handoff

## 현재 기준

- KIS agent runtime secret의 단일 원본은 SOPS + age다.
- 모의테스트도 필요하므로 `secrets/kis.live.sops.yaml`에 실전/모의 값을 분리해 저장한다.
- `bin/kis-sops-env`는 명령 실행 동안만 SOPS 값을 환경변수로 주입한다.

## 사용자 수행 순서

원격 host의 ALT repo로 이동한다.

```bash
cd /Users/toki/docker/services/code-server/data/volume/workspace/alt
```

SOPS 편집기로 `secrets/kis.live.sops.yaml`을 연다.

```bash
SOPS_AGE_KEY_FILE="$HOME/.config/sops/age/keys.txt" \
EDITOR="${EDITOR:-nano}" \
sops secrets/kis.live.sops.yaml
```

열린 편집기 안에서 `secrets/kis.live.sops.yaml`의 전체 내용을 아래 템플릿 형태로 맞춘다. 각 값 설명만 실제 값으로 바꾼 뒤 저장하고 종료한다.

```yaml
KIS_REAL_APP_KEY: "<한국투자증권 실전 Open API 앱키>"
KIS_REAL_APP_SECRET: "<한국투자증권 실전 Open API 앱시크릿>"
KIS_REAL_CANO: "<실전 증권계좌번호 8자리>"
KIS_REAL_ACNT_PRDT_CD: "01"
KIS_PAPER_APP_KEY: "<한국투자증권 모의투자 Open API 앱키>"
KIS_PAPER_APP_SECRET: "<한국투자증권 모의투자 Open API 앱시크릿>"
KIS_PAPER_CANO: "<모의투자 증권계좌번호 8자리>"
KIS_PAPER_ACNT_PRDT_CD: "01"
```

국내주식 종합계좌 기준 `ACNT_PRDT_CD`는 `01`로 둔다. 한국투자증권 공식 샘플도 증권계좌 8자리와 `my_prod: "01"`을 분리해서 사용한다.

`nano` 기준 저장은 `Ctrl+O`, `Enter`, 종료는 `Ctrl+X`다.

## 입력 확인 명령

```bash
SOPS_AGE_KEY_FILE="$HOME/.config/sops/age/keys.txt" \
bin/kis-sops-env bash -lc '
for key in \
  KIS_REAL_APP_KEY KIS_REAL_APP_SECRET KIS_REAL_CANO KIS_REAL_ACNT_PRDT_CD \
  KIS_PAPER_APP_KEY KIS_PAPER_APP_SECRET KIS_PAPER_CANO KIS_PAPER_ACNT_PRDT_CD
do
  test -n "${!key}" || exit 1
done
echo "KIS SOPS secrets are ready"
'
```

## 모의/실전 테스트 준비 확인 명령

모의:

```bash
KIS_ACTIVE_ENV=paper \
SOPS_AGE_KEY_FILE="$HOME/.config/sops/age/keys.txt" \
bin/kis-sops-env bash -lc '
test "$KIS_ACTIVE_ENV" = "paper"
test -n "$KIS_PAPER_APP_KEY"
test -n "$KIS_PAPER_APP_SECRET"
test -n "$KIS_PAPER_CANO"
test -n "$KIS_PAPER_ACNT_PRDT_CD"
echo "paper smoke env is ready"
'
```

실전:

```bash
KIS_ACTIVE_ENV=real \
SOPS_AGE_KEY_FILE="$HOME/.config/sops/age/keys.txt" \
bin/kis-sops-env bash -lc '
test "$KIS_ACTIVE_ENV" = "real"
test -n "$KIS_REAL_APP_KEY"
test -n "$KIS_REAL_APP_SECRET"
test -n "$KIS_REAL_CANO"
test -n "$KIS_REAL_ACNT_PRDT_CD"
echo "real smoke env is ready"
'
```

## 일봉 smoke 명령

모의:

```bash
KIS_ACTIVE_ENV=paper \
SOPS_AGE_KEY_FILE="$HOME/.config/sops/age/keys.txt" \
bin/kis-sops-env bin/kis-paper-daily-smoke \
  --symbol 005930 \
  --start 20240527 \
  --end 20240528
```

실전:

```bash
KIS_ACTIVE_ENV=real \
SOPS_AGE_KEY_FILE="$HOME/.config/sops/age/keys.txt" \
bin/kis-sops-env bin/kis-paper-daily-smoke \
  --symbol 005930 \
  --start 20240527 \
  --end 20240528
```

## Go live-provider smoke 명령

모의:

```bash
KIS_ACTIVE_ENV=paper \
KIS_LIVE_SMOKE=1 \
SOPS_AGE_KEY_FILE="$HOME/.config/sops/age/keys.txt" \
bin/kis-sops-env /opt/homebrew/bin/go test ./services/worker/internal/providers/kis \
  -run TestLiveProviderPaperSmoke \
  -count=1 \
  -v
```

실전:

```bash
KIS_ACTIVE_ENV=real \
KIS_REAL_LIVE_SMOKE=1 \
SOPS_AGE_KEY_FILE="$HOME/.config/sops/age/keys.txt" \
bin/kis-sops-env /opt/homebrew/bin/go test ./services/worker/internal/providers/kis \
  -run TestLiveProviderRealSmoke \
  -count=1 \
  -v
```

## Sanitized evidence 기준

이 기준은 데이터 적재 정책이 아니라 테스트 evidence 기준이다. Raw KIS payload, request/response header, token, key, 계좌번호는 저장하지 않는다.

Tracked 문서나 handoff에는 아래 요약만 남긴다.

```text
env=paper|real
provider=kis
endpoint=inquire-daily-itemchartprice
symbol=005930
date_range=20240527~20240528
bar_count=2
first_date=20240527
last_date=20240528
msg_cd=MCA00000
result=ok
```

Provider 상태 분류는 아래 key를 사용한다.

```text
unavailable
auth
quota
malformed
provider
```

## Agent에게 전달할 내용

SOPS 입력과 확인 명령이 끝난 뒤 agent에게는 아래만 전달한다.

```text
SOPS KIS real/paper runtime secrets are filled.
Paper smoke env readiness check passed.
Real smoke env readiness check passed.
Go KIS paper live-provider smoke passed.
Go KIS real live-provider smoke passed.
First daily smoke target:
- market: KR
- symbol: 005930
- date range: 20240527~20240528
```