# ALT

ALT는 개인용 quant system workspace다. 주식형 instrument의 venue-agnostic 일봉 데이터 기반에서 시작해, 장기적으로 여러 주식시장, 백테스트, 데이터 정규화, 페이퍼 트레이딩, 포트폴리오/리스크 관리, Flutter 클라이언트까지 확장할 수 있는 운영형 구조를 목표로 한다.

Go 서비스와 도구는 루트 `go.work`로 묶고, Flutter가 web/mobile/desktop 클라이언트 표면을 담당한다. 실시간 통신은 sibling workspace의 `../proto-socket/go`를 transport로 사용하며, ALT 애플리케이션 계약은 `packages/contracts/proto`의 protobuf schema를 원천으로 둔다.

## 현재 상태

현재 저장소는 초기 scaffold 단계다.

- `services/api`는 proto-socket WebSocket endpoint scaffold를 제공한다.
- `services/worker`는 데이터 수집, 정규화, 백테스트, scheduled job을 위한 worker surface다.
- `apps/client`는 Riverpod과 `go_router`를 사용하는 Flutter client shell이다.
- `packages/contracts`에는 `alt.v1` protobuf 계약 초안이 있다.
- `packages/domain`에는 market/backtest vocabulary와 value object skeleton이 있다.
- PostgreSQL 17과 Redis 7 local stack은 `deployments/local/docker-compose.yml`에 있다.
- 로드맵 진입점은 `agent-roadmap/current.md`다. 일반 작업에서는 전체 `ROADMAP.md`를 매번 읽지 않고, 활성 Milestone 문서를 선택해 읽는다.
- market data의 현재 core 범위는 주식/ETF/지수처럼 주식시장 개념을 공유하는 instrument다. Crypto는 거래 구조가 달라 core 주식 모델에 넣지 않고, 향후 별도 asset-class domain에서 공유 가능한 일부 파이프라인만 재사용할지 검토한다.

## 빠른 시작

```bash
# 사용 가능한 entrypoint 확인
bin/dev

# 로컬 PostgreSQL/Redis 실행
docker compose -f deployments/local/docker-compose.yml up -d

# API socket server 실행
cd services/api
go run ./cmd/alt-api
```

Flutter client는 별도 터미널에서 실행한다.

```bash
cd apps/client
flutter run -d chrome
```

전체 검증은 루트에서 실행한다.

```bash
bin/test
bin/lint
bin/build
```

## 주요 명령

| 목적 | 명령 | 비고 |
|------|------|------|
| 개발 entrypoint 확인 | `bin/dev` | infra, API, worker, CLI, client 실행 명령을 출력한다. |
| 전체 테스트 | `bin/test` | Go module test와 Flutter test를 실행한다. |
| 전체 lint/analyze | `bin/lint` | Go `vet`와 Flutter analyze를 실행한다. |
| 전체 build | `bin/build` | Go binary와 Flutter web build를 생성한다. |
| 로컬 infra 실행 | `docker compose -f deployments/local/docker-compose.yml up -d` | PostgreSQL과 Redis를 실행한다. |
| API 실행 | `cd services/api && go run ./cmd/alt-api` | 기본 socket path는 `/socket`이다. |
| Worker 실행 | `cd services/worker && go run ./cmd/alt-worker` | 현재는 worker scaffold 상태다. |
| CLI 실행 | `cd apps/cli && go run ./cmd/alt` | 운영자 CLI scaffold다. |
| Client 실행 | `cd apps/client && flutter run -d chrome` | Flutter web target 기준 개발 실행이다. |

## 구조

| 경로 | 역할 |
|------|------|
| `services/api/` | 클라이언트-facing proto-socket API endpoint. |
| `services/worker/` | import, normalization, backtest, scheduled job worker surface. |
| `apps/cli/` | 로컬/운영자 작업용 Go CLI. |
| `apps/client/` | Flutter client for web/mobile/desktop. |
| `packages/contracts/` | ALT protobuf contracts and compatibility notes. |
| `packages/domain/` | market/backtest shared Go domain model. |
| `deployments/local/` | local PostgreSQL and Redis development environment. |
| `bin/` | workspace-level helper entrypoints. |
| `agent-ops/` | AI agent rules, domain rules, common skills, roadmap templates. |

## 작업 맥락

AI agent는 작업 전에 루트 지침과 관련 domain rule을 먼저 확인한다.

- `AGENTS.md`
- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/project/domain/*/rules.md`
- README 작업은 `agent-ops/skills/common/create-readme/SKILL.md`를 따른다.
- 로드맵 작업은 `agent-roadmap/current.md`와 활성 milestone 문서를 기준으로 한다.

중요한 경계는 다음과 같다.

- `proto-socket`은 transport layer다. ALT application message는 `packages/contracts/proto`에 둔다.
- `packages/domain`은 transport나 persistence detail에 의존하지 않는다.
- market domain은 한국장/KIS 필드에 직접 종속되지 않는 global equity venue-agnostic vocabulary를 우선한다.
- 장별 특수값은 canonical column으로 끌어올리기보다 provider adapter, venue metadata, raw payload, 또는 별도 확장 metadata에 격리한다.
- `services/api`는 socket/session boundary를 담당한다.
- `services/worker`는 오래 걸리거나 비동기적인 데이터/백테스트 작업을 담당한다.
- `apps/client`는 Flutter feature-first 구조를 사용한다.

## 개발 흐름

- 전체 workspace 검증은 가능한 한 루트 `bin/test`, `bin/lint`, `bin/build`를 우선 사용한다.
- API, worker, client, contracts가 함께 움직이는 변경은 같은 작업 흐름에서 닫는다.
- protobuf generated output은 source schema에서 생성하고 손으로 편집하지 않는다.
- 새 Go module을 추가하면 `go.work`에 등록한다.
- 로컬 secret이나 개인 설정 파일은 커밋하지 않는다.
- KIS 같은 provider credential은 실제 KIS smoke/live 단계에서만 필요하며, 그때도 `.env` 파일에 저장하지 않고 1Password CLI 또는 service account를 통해 실행 시점에 주입한다.
- 현재 KIS adapter mapping 참조는 로컬 cache의 공식 API 샘플 repo를 우선한다. Credential 없는 mock 검증용 샘플은 `services/worker/testdata/providers/kis/` 아래에 secret-free JSON fixture로 둔다.

## 환경 변수

| 이름 | 설명 | 필수 |
|------|------|------|
| `ALT_API_HOST` | API socket server host. 기본값 `127.0.0.1`. | 아니오 |
| `ALT_API_PORT` | API socket server port. 기본값 `8080`. | 아니오 |
| `ALT_API_SOCKET_PATH` | API WebSocket path. 기본값 `/socket`. | 아니오 |
| `ALT_SOCKET_HEARTBEAT_INTERVAL_SEC` | proto-socket heartbeat interval. 기본값 `30`. | 아니오 |
| `ALT_SOCKET_HEARTBEAT_WAIT_SEC` | proto-socket heartbeat wait. 기본값 `10`. | 아니오 |
| `DATABASE_URL` | worker에서 사용할 PostgreSQL URL. local fallback 있음. | 아니오 |
| `REDIS_URL` | worker에서 사용할 Redis URL. local fallback 있음. | 아니오 |

## Secret 관리

ALT의 provider credential은 실제 provider 호출 단계에서 1Password를 기본 secret source로 둔다. 현재 mock/fixture 테스트 단계에서는 KIS credential이 필요하지 않다. 실제 KIS smoke가 필요해지면 로컬 개발에서는 `op run -- <command>` 형태로 필요한 process에만 값을 주입하고, 자동화 환경에서는 개인 계정이 아닌 1Password service account를 사용한다.

Tracked 문서와 fixture에는 실제 key, token, account number, secret reference를 남기지 않는다. 환경별 secret item 이름, vault 이름, 계정별 운영 메모가 필요하면 git 추적 대상이 아닌 `agent-ops/rules/private/`에 둔다.

## Provider Reference and Fixture

KIS API 참조는 공식 샘플 repo의 로컬 cache를 우선한다. cache 위치와 갱신 방법은 git 추적 제외 private rule인 `agent-ops/rules/private/kis-api-local-cache.md`에 둔다.

Mock 테스트와 adapter mapping에 필요한 샘플은 `services/worker/testdata/providers/kis/` 아래에 secret-free JSON fixture로 둔다. 현재는 Postman export를 필수 입력으로 보지 않는다.

SQLite 보관은 샘플 수가 많아져 검색, 인덱싱, 비교 쿼리가 실제로 필요해진 뒤 검토한다. 초기 adapter mapping과 테스트 fixture에는 diff 가능한 JSON이 기본이다.

## 참고 문서

- `apps/client/README.md`
- `packages/contracts/README.md`
- `services/worker/README.md`
- `services/worker/testdata/providers/kis/README.md`
- `agent-ops/rules/project/rules.md`
- `agent-roadmap/current.md`
- `agent-ops/skills/common/create-roadmap/SKILL.md`
- `agent-ops/skills/common/update-roadmap/SKILL.md`