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로 이동한다.

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

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

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

열린 편집기 안에서 secrets/kis.live.sops.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다.

입력 확인 명령

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"
'

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

모의:

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"
'

실전:

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 명령

모의:

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

실전:

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 명령

모의:

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

실전:

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에는 아래 요약만 남긴다.

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를 사용한다.

unavailable
auth
quota
malformed
provider

Agent에게 전달할 내용

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

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