# req-016: KIS 인증 토큰 Redis 캐시

- Status: Implemented
- Type: Integration
- Priority: Medium
- Owner: project maintainers

## Intent
- KIS 접속 토큰을 Redis 에 캐시해 데몬 재기동·다중 프로세스에서도 토큰을 공유/생존시켜, KIS 토큰 발급 rate-limit(약 1회/분, EGW00133)을 피한다. trex-orbit 의 Redis 토큰 캐시 패턴을 trex-core 로 이식한다.

## Requirement
- KISBroker 에 선택적 토큰 캐시(`TokenCache`)를 주입한다. `_ensure_token` 은 ① 인메모리(L1) → ② Redis 캐시(L2, 키 `trex:broker:kis:{account_ref}:token`, 토큰+만료+app_key suffix JSON, `ex=ttl`) → ③ 신규 발급 순으로 해석한다. Redis 미설정/미설치/오류 시 기존 인메모리 동작으로 graceful fallback 한다. config 는 `TREX_KIS_REDIS_URL` 로 캐시를 활성화한다.

## Acceptance Criteria
1. Given Redis 캐시에 유효 토큰이 있음, When `_ensure_token`, Then HTTP 발급 없이 캐시 토큰을 사용한다.
2. Given 두 KISBroker 가 같은 캐시를 공유, When 하나가 발급·저장 후 다른 하나가 호출, Then 재발급 없이 캐시 토큰을 재사용한다(재기동/다중 프로세스 생존).
3. Given Redis 미설정/미설치/오류, When `_ensure_token`, Then 기존 인메모리 발급 동작으로 동작한다(회귀 없음).
4. Given 캐시된 토큰의 app_key suffix 가 현재와 불일치, When load, Then 캐시를 무시하고 재발급한다(자격증명 교체 안전).

## Impacted Area
- Docs: docs/interface-contract.md(KIS 어댑터 노트) — 필요 시
- Modules: trex_core/adapters/broker/token_cache.py(신규), kis.py(token_cache 주입), runtime/config.py(TREX_KIS_REDIS_URL), runtime/daemon.py(캐시 wiring), pyproject(redis 의존)
- Tests: tests/adapters/broker/test_token_cache.py (캐시 히트/공유/폴백/suffix)

## Notes
- minor-change: 기존 BrokerPort 뒤 토큰 캐시 계층 추가(외부 인터페이스/슬롯 흐름 변경 없음). batch-lite, design 불요.
- dcy-003 가 단일 인스턴스를 가정해 슬라이스에서 분산 캐시를 미포팅했던 갭의 후속 보완. 실 Redis 없을 때도 폴백으로 안전.
- 맥락: REQ-012(KIS 어댑터) 운영 견고성 개선.

## Change Log

### CHG-20260604-01
- Date: 2026-06-04
- Author: Justin Ko

#### Change Summary
- 최초 생성(Proposed) — KIS 토큰 Redis 캐시(재기동/다중프로세스 생존) Integration 요구사항.

#### Intent
- orbit Redis 토큰 캐시 패턴 이식으로 토큰 rate-limit·재발급 위험 완화.

#### Acceptance Criteria Delta
- Added:
  - 캐시 히트, 공유 재사용, graceful fallback, app_key suffix 안전 4개 기준
- Updated:
  - 없음
- Removed:
  - 없음

#### Impacted Area Delta
- Docs:
  - docs/interface-contract.md(필요 시)
- Modules:
  - adapters/broker/token_cache.py, kis.py, runtime/config.py, runtime/daemon.py, pyproject
- Tests:
  - tests/adapters/broker/test_token_cache.py

#### Delivery Trace Delta
- Batches:
  - none
- Releases:
  - none

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: keep-current
- Follow-up Action: batch-lite 편성

#### Validation Plan
- 캐시 히트/공유/폴백/suffix 단위테스트(인메모리 캐시 더블)로 검증.

### CHG-20260604-02
- Date: 2026-06-04
- Author: Justin Ko

#### Change Summary
- Status Proposed → Approved (minor-change 저위험 단일 REQ, 외부 인터페이스/런타임 흐름 변경 없음).

#### Intent
- 승인 게이트 충족. batch-lite 로 즉시 delivery.

#### Acceptance Criteria Delta
- Added:
  - 없음
- Updated:
  - 없음
- Removed:
  - 없음

#### Impacted Area Delta
- Docs:
  - docs/srs/index.md (Register Approved)
- Modules:
  - 없음
- Tests:
  - 없음

#### Delivery Trace Delta
- Batches:
  - none (batch-lite 편성 예정)
- Releases:
  - none

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: keep-current
- Follow-up Action: draft-batch 로 batch-lite 생성

#### Validation Plan
- batch-lite verification 에서 AC 검증.

### CHG-20260604-03
- Date: 2026-06-04
- Author: Justin Ko

#### Change Summary
- Status Approved → Implemented (confirm-req-implemented, 근거 batch BAT-005 release-candidate).

#### Intent
- BAT-005 verification 의 AC↔evidence(캐시 히트/공유/폴백/suffix, 96 pass)로 모든 AC 충족.

#### Acceptance Criteria Delta
- Added:
  - 없음
- Updated:
  - 없음
- Removed:
  - 없음

#### Impacted Area Delta
- Docs:
  - docs/srs/index.md (Register Implemented)
- Modules:
  - 없음
- Tests:
  - 없음

#### Delivery Trace Delta
- Batches:
  - BAT-005 (release-candidate)
- Releases:
  - none

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: keep-current
- Follow-up Action: draft-release 로 release 편성

#### Validation Plan
- BAT-005 verification evidence 재참조로 충분.