alt/README.md

# 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이다. 현재 NomadCode와 같은 top titlebar, 우측 activity rail, 우측 Agent dock 패턴의 workbench scaffold를 포함하며 Agent dock은 공통 `agent_shell` package를 사용한다.
- `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 --web-port 13030
```

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

```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 --web-port 13030` | 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. Workbench shell, 우측 Agent dock, Riverpod/go_router app boundary를 포함한다. |
| `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 구조를 사용한다.
- `apps/client`의 workbench shell은 UI skeleton 수준이며, 실제 quant 운영 기능은 API/worker/domain headless 경계가 안정화된 뒤 중앙 section에 mount한다.

## 개발 흐름

- 전체 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 단계에서만 필요하며, agent runtime secrets는 SOPS + age를 단일 원본으로 둔다.
- 현재 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. 기본값 `18030`. | 아니오 |
| `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: `postgres://alt:alt@localhost:15430/alt?sslmode=disable`. | 아니오 |
| `REDIS_URL` | worker에서 사용할 Redis URL. local fallback: `redis://localhost:16330/0`. | 아니오 |

## 워크스페이스 포트 슬롯

| 용도 | 포트 |
|------|------|
| Flutter/web preview | `13030` |
| API socket server | `18030` |
| worker socket | `18031` |
| optional wire/evidence relay | `19030` |
| PostgreSQL host publish | `15430` |
| Redis host publish | `16330` |

PostgreSQL(`5432`)과 Redis(`6379`)의 container 내부 포트는 service DNS/container internal 통신에만 사용하며, host publish 기본값은 위 슬롯으로 통일한다.
이 표는 로컬 checkout과 원격 테스트 runner에서 외부로 노출하는 ALT 포트의 tracked 기준이다. 원격 runner의 실제 host/user/path, artifact/bootstrap endpoint, OpenAI-compatible endpoint, 개인 wire/metrics endpoint는 tracked 문서에 원문을 남기지 않고 local/private rule 또는 secret-only profile에서만 다룬다. ALT에 직접 할당된 public/dev 슬롯이 없으면 tracked 문서에서는 `미할당`으로 둔다.

기존 smoke 문서나 field/remote 메모가 다른 포트를 가리키면 먼저 위 슬롯과 `deployments/local/docker-compose.yml`, `bin/dev`, `bin/infra-check`, API/worker config 기본값을 대조한 뒤 같은 변경에서 갱신한다. 호환성 확인 전에는 legacy 포트를 새 기본값으로 다시 확정하지 않는다.

## Secret 관리

ALT의 KIS provider credential은 실제 provider 호출 단계에서 SOPS + age를 agent runtime secret의 단일 원본으로 둔다. 현재 mock/fixture 테스트 단계에서는 KIS credential이 필요하지 않다. 실제 KIS smoke가 필요해지면 `bin/kis-sops-env <command>` 또는 배포 환경의 SOPS 복호화 주입 경로로 필요한 process에만 값을 주입한다.

Tracked 문서와 fixture에는 실제 key, token, account number, secret reference를 남기지 않는다. 환경별 운영 메모가 필요하면 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`