# Gitea Variables Setup

이 저장소는 KIS Open API와 Gitea workflow를 분리해서 사용한다.
현재 KIS 인증값은 `Settings > Actions > Variables`에 등록해서 사용한다.

## Required Variables

### Shared

- `GITHUB_TOKEN`

### KIS read-only validation

- `KIS_APP_KEY_TEST`
- `KIS_APP_SECRET_TEST`

### KIS real data collection

- `KIS_APP_KEY`
- `KIS_APP_SECRET`

## Token Cache Policy

- KIS access token은 `Temp/kis_tokens.db`에 저장한다.
- 토큰은 `TOKEN_REFRESH_SKEW_MINUTES=10` 기준으로만 재사용/갱신한다.
- 토큰 캐시는 수집 DB와 분리한다.
- 토큰 캐시 상태는 `python tools/inspect_kis_token_cache_v1.py --json`로 점검한다.
- 토큰 갱신 실패 시 appkey/appsecret 또는 API 가용성 문제로만 판단하고, 시크릿 값을 로그나 알림에 그대로 노출하지 않는다.

## Workflow Mapping

- `.gitea/workflows/kis_data_collection.yml`
  - mock validation: `KIS_APP_KEY_TEST`, `KIS_APP_SECRET_TEST`
  - real collection: `KIS_APP_KEY`, `KIS_APP_SECRET`
- `.gitea/workflows/qualitative_sell_strategy.yml`
  - mock validation: `KIS_APP_KEY_TEST`, `KIS_APP_SECRET_TEST`
  - real collection: `KIS_APP_KEY`, `KIS_APP_SECRET`
- `.gitea/workflows/ci.yml`
  - mock validation: `KIS_APP_KEY_TEST`, `KIS_APP_SECRET_TEST`

## Runtime Rule

- mock 계정은 유효성 확인용이다.
- real 계정은 실제 데이터 수집용이다.
- 둘을 같은 단계에서 혼용하지 않는다.
- 토큰 발급은 1일 1회 원칙을 따르며, 만료 전에는 캐시를 재사용한다.

## Verification

Run:

```bash
python tools/validate_gitea_secrets_contract_v1.py
```

The validator checks that the workflows reference the required variable names
with the expected separation between mock and real usage.