toki
c4a457c5c4
API domain에 workerclient proxy와 handler responsibility를 추가하고, worker domain에 backtest engine, storage, provider, socket surface를 명시한다. Client domain에 socket integration과 push integration 경계를 보강한다. Operations domain에 agent-test/local과 bin 명령어를 포함하며, operations domain table에 agent-test/local 경계를 추가한다. 로드맵에 Operator Runtime Reliability Refactor Milestone를 추가하고 현재 활성 Milestone으로 설정하여 Flutter Operator Console 전에 선행할 작업으로 변경한다.
85 lines
5.8 KiB
Markdown
85 lines
5.8 KiB
Markdown
# ALT 프로젝트 규칙
|
|
|
|
## 응답 언어
|
|
|
|
- 기본 응답은 한국어로 작성한다.
|
|
- 코드 식별자, 명령어, 경로, 에러 메시지는 원문 영어를 유지한다.
|
|
- 설계 선택을 설명할 때는 ALT의 quant workspace 맥락과 연결해서 짧게 근거를 남긴다.
|
|
|
|
## 프로젝트 개요
|
|
|
|
ALT는 개인 quant system workspace다. Go 서비스와 도구는 루트 `go.work`로 묶고, Flutter가 web/mobile/desktop 클라이언트 표면을 담당한다. 실시간 전송은 sibling workspace인 `../proto-socket/go`의 proto-socket 모듈을 사용하며, ALT 애플리케이션 계약은 `packages/contracts/proto`의 protobuf schema가 원천이다.
|
|
|
|
## 주요 구조
|
|
|
|
| 경로 | 역할 |
|
|
|------|------|
|
|
| `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/` | shared Go domain model for market and backtest concepts |
|
|
| `deployments/local/` | local PostgreSQL and Redis development environment |
|
|
| `bin/` | workspace-level helper entrypoints |
|
|
|
|
## 기술 스택
|
|
|
|
- Go 1.22 multi-module workspace via `go.work`.
|
|
- `git.toki-labs.com/toki/proto-socket/go` is consumed through a local replace to `../proto-socket/go`.
|
|
- `services/api` uses `nhooyr.io/websocket` through proto-socket server/client wrappers.
|
|
- Contracts are protobuf schemas under `packages/contracts/proto/alt/v1`.
|
|
- Flutter client uses Material 3, Riverpod, and `go_router`.
|
|
- Local infrastructure uses Docker Compose with PostgreSQL 17 and Redis 7.
|
|
|
|
## 통신 규칙
|
|
|
|
- ALT가 소유한 runtime boundary 사이의 application message 통신은 proto-socket과 `packages/contracts/proto`의 ALT protobuf payload로 통일한다.
|
|
- 기본 runtime topology는 `client -> services/api -> services/worker`다. client는 worker를 직접 제어하지 않고 `services/api`를 단일 operator-facing control plane으로 사용한다.
|
|
- client-api, api-worker, worker-sidecar처럼 별도 process나 service 사이에서 ALT domain request/response, event, command를 주고받으면 기본값은 proto-socket이다.
|
|
- 같은 process 안의 함수 호출, Go interface, Dart provider 호출은 runtime 통신부로 보지 않는다.
|
|
- PostgreSQL SQL, Redis command/queue/cache, filesystem, process/stdout, local migration/codegen/dev tooling은 해당 목적의 native protocol을 사용한다.
|
|
- KIS, Mattermost, Firebase, Nexo plugin, OS platform channel처럼 ALT 외부 시스템이나 platform integration과 통신할 때는 해당 외부 protocol을 adapter 경계 안에서 사용한다.
|
|
- proto-socket이 아닌 ALT-owned runtime protocol을 새로 도입하려면 구현 전에 프로젝트 규칙 또는 명시적 architecture 문서를 갱신하고 예외 사유를 남긴다.
|
|
|
|
## 프로젝트 컨벤션
|
|
|
|
- 루트 작업은 `bin/dev`, `bin/test`, `bin/lint`, `bin/build`를 우선 사용한다.
|
|
- Go 모듈 경계를 넘는 import는 `go.work`에 등록된 모듈 기준으로 유지한다.
|
|
- protobuf generated client/server 코드는 schema에서 생성하고 손으로 편집하지 않는다.
|
|
- `packages/domain`은 business vocabulary와 value object를 담고, transport나 persistence detail에 의존하지 않는다.
|
|
- `services/api`는 socket/session boundary를 담당하고, domain 계산이나 worker job 실행을 직접 떠안지 않는다.
|
|
- `services/api`는 얇은 control plane으로서 client-facing 요청을 받고 worker 실행/조회 경계로 중계한다.
|
|
- `services/worker`는 데이터 수집, 정규화, backtest 실행, scheduled job처럼 오래 걸리거나 비동기적인 일을 담당한다.
|
|
- Flutter client는 `lib/src/app`에 앱 shell/router를 두고, 기능 화면은 `lib/src/features/feature-name/presentation` 패턴 아래에 둔다.
|
|
- runtime configuration은 환경변수를 우선하고 로컬 개발 fallback을 둔다.
|
|
|
|
## 운영 UI 구현 게이트
|
|
|
|
- ALT 운영 기능은 먼저 화면 없이 CLI, terminal output, YAML scenario, log, test fixture처럼 headless 경로로 구성과 결과를 검증한다.
|
|
- Flutter 실화면 구현은 해당 기능의 API/worker/domain 경계와 headless 검증 경로가 먼저 안정화된 뒤에 시작한다.
|
|
- 운영 화면 구현 Milestone은 화면 wireframe 또는 동등한 화면 정의 산출물이 준비되고 사용자 승인 기준이 문서화되어야 `구현 잠금`을 해제할 수 있다.
|
|
- wireframe 없이 agent가 임의로 dashboard depth, navigation, card layout, chart, form 흐름을 확정하지 않는다.
|
|
- Flutter 작업 중 화면 구현이 아닌 app shell, provider boundary, generated contract 연결, headless smoke support는 위 게이트를 깨는 실화면 구현으로 보지 않는다.
|
|
|
|
## 도메인 매핑
|
|
|
|
| 경로 패턴 | 도메인 | rules.md |
|
|
|----------|--------|----------|
|
|
| `packages/domain/**` | domain-model | `agent-ops/rules/project/domain/domain-model/rules.md` |
|
|
| `packages/contracts/**` | contracts | `agent-ops/rules/project/domain/contracts/rules.md` |
|
|
| `services/api/**` | api | `agent-ops/rules/project/domain/api/rules.md` |
|
|
| `services/worker/**` | worker | `agent-ops/rules/project/domain/worker/rules.md` |
|
|
| `apps/client/**` | client | `agent-ops/rules/project/domain/client/rules.md` |
|
|
| `apps/cli/**`, `bin/**`, `deployments/local/**`, `agent-test/local/**`, `go.work`, `go.work.sum`, `.gitignore` | operations | `agent-ops/rules/project/domain/operations/rules.md` |
|
|
|
|
## 검증 명령
|
|
|
|
- 전체 테스트: `bin/test`
|
|
- 전체 lint/analyze: `bin/lint`
|
|
- 전체 build: `bin/build`
|
|
- 로컬 실행 안내: `bin/dev`
|
|
|
|
## 스킬 라우팅
|
|
|
|
현재 프로젝트 전용 skill은 만들지 않는다. 반복 작업이 안정되면 `agent-ops/skills/project/` 아래에 추가한다.
|