genichin
e6b6a8715b
Core Implementation (BAT-010):
- Add daemon registry schema and CRUD operations (req-023)
- Implement single-daemon asset assignment constraint (one asset per daemon)
- Add daemon_id field to service_token for daemon identification
- Add daemon.py CLI module for daemon management commands
- Add 20260513_0016_daemon_model.py migration for daemon tables
API Changes:
- GET /v1/assets: include daemon_id in AssetResponse
- POST /v1/assets/{asset_id}/ledger/trades: require daemon token binding
- GET /v1/user_info: include daemon metadata
- Enhanced service-token rotate to preserve daemon bindings
CLI Commands:
- pfhub daemon register --name <name> --runtime-id <runtime-id>
- pfhub daemon list
- pfhub daemon get <daemon-id>
- pfhub daemon revoke <daemon-id>
Requirements (REQ-023, REQ-028):
- REQ-023: Daemon Registry and Service Token Daemon Binding (Interface, Approved)
* AC-1: daemon CRUD operations
* AC-2: service token daemon binding for POST /v1/assets/{asset_id}/ledger/trades
* AC-3: single daemon per asset (exact-one assignment model)
- REQ-028: README.md Daemon Provisioning Runbook update (Documentation, Approved)
Documentation:
- Add dcy-006 Discovery for daemon-id and single-daemon asset assignment
- Update README.md with Daemon Provisioning Runbook section
- Add BAT-010 batch documentation with planning, implementation, verification
- Update rel-006 release document (daemon model implementation)
- Update data-model.md with daemon and daemon_asset_assignment tables
- Update interface-contract.md with daemon registry APIs
- Update runtime-flows.md with daemon lifecycle flows
Breaking Changes:
- REQ-005~009, REQ-011~012 status reverted to Approved due to revised contract
* daemon_id field addition and exact-one asset assignment requirement
* Existing Implemented evidence invalidated by contract revision
* BAT-001/002/008 re-verification required
Testing:
- Add test_daemon_registry.py for daemon CRUD operations
- Add test_daemon_assignment.py for single-asset assignment constraints
- Update test_auth.py, test_cli.py, test_v1.py for daemon support
- Verify daemon token binding in trade endpoint authorization
Impact:
- Database: 2 new tables (daemons, daemon_asset_assignments)
- Migration: 20260513_0016 creates daemon model schema
- CLI: 4 new daemon subcommands
- API: daemon_id propagation through v1 endpoints
- Verification: BAT-001/002/008 re-verification gates next release
63 lines
4.3 KiB
Markdown
63 lines
4.3 KiB
Markdown
# BAT-010 Planning
|
|
|
|
- Status: confirmed
|
|
- Batch: BAT-010
|
|
- Profile: standard
|
|
|
|
## Included REQ
|
|
- REQ-009: v1 API DB 스키마 migration (daemon schema 포함)
|
|
- REQ-023: Daemon Registry 관리 경로
|
|
- REQ-005: service-token 발급 daemon binding
|
|
- REQ-012: service-token rotate daemon_id 불변식
|
|
- REQ-006: GET /v1/assets daemon-scoped
|
|
- REQ-007: GET /v1/user_info daemon_id 필드
|
|
- REQ-008: POST /v1/assets/{asset_id}/ledger/trades daemon assignment authorization
|
|
- REQ-011: baseline docs daemon-aware 갱신
|
|
- REQ-028: README.md daemon provisioning runbook
|
|
|
|
## Delivery Plan
|
|
|
|
의존 순서에 따라 아래 순서로 구현한다.
|
|
|
|
1. **REQ-009** — Alembic migration: `daemons` 테이블 신규 생성, `auth_tokens.daemon_id` FK 컬럼 추가, `portfolios.managed_by_daemon_id` FK 컬럼 추가, 기존 레코드 NULL backfill. 기존 revision chain 및 `IF NOT EXISTS` 정책 준수.
|
|
2. **REQ-023** — Daemon registry CRUD: domain model(`Daemon` entity), repository(`create_daemon`, `get_daemon_by_slug`, `list_daemons_for_user`, `update_daemon`), management route 또는 CLI subcommand. daemon_slug owner-unique validation.
|
|
3. **REQ-005** — service-token issuance daemon binding: `POST /auth/service-tokens`와 `pfhub service-token issue`가 existing daemon registry entry에 1:1 binding. unknown daemon 입력 명시적 거부.
|
|
4. **REQ-012** — service-token rotate daemon_id 불변식: rotate 시 `token_hash`, `token_prefix`, `runtime_id`만 갱신, `daemon_id` 유지. CLI rotate 출력에 `daemon_id` 포함.
|
|
5. **REQ-006** — GET /v1/assets daemon-scoped: `managed_by_daemon_id = token.daemon_id` 필터 적용. NULL token 403 fail-closed.
|
|
6. **REQ-007** — GET /v1/user_info daemon_id 필드: 응답 스키마에 `daemon_id` 추가. NULL backfill token은 `daemon_id: null` 진단 노출.
|
|
7. **REQ-008** — POST /v1/assets/{asset_id}/ledger/trades daemon assignment authorization: `managed_by_daemon_id = token.daemon_id` 검증. mismatch/미배정/NULL token 403 fail-closed.
|
|
8. **REQ-011** — baseline docs 갱신: `docs/interface-contract.md`, `docs/data-model.md`, `docs/runtime-flows.md`에 daemon binding/assignment/403 policy/rotate invariant 반영.
|
|
9. **REQ-028** — README.md 갱신: daemon provisioning 절차, enforcement enablement gate 4종 evidence, runtime_id/daemon_id 역할 구분 반영.
|
|
|
|
## Dependencies
|
|
|
|
- Internal:
|
|
- REQ-009 migration은 REQ-023~028 구현 전에 schema가 존재해야 한다.
|
|
- REQ-023 daemon registry가 구축된 후 REQ-005/012 binding 구현이 가능하다.
|
|
- REQ-005/012가 daemon binding을 제공한 후 REQ-006/007/008 daemon-scoped authorization이 가능하다.
|
|
- REQ-011/028 문서화는 구현 단계 마지막 또는 구현 완료 직후 수행한다.
|
|
- External:
|
|
- 기존 Alembic revision chain (최신 head revision과 연결 필요)
|
|
- 기존 service-token bearer auth 모델 유지 (read/trade-write/admin permission 불변)
|
|
|
|
## Design Gate
|
|
|
|
- Design Required Before Implementation: yes
|
|
- Reason: 신규 `Daemon` 엔티티의 API transport 형태(HTTP endpoint vs CLI subcommand vs 혼합), daemon_slug owner-unique constraint 설계, enforcement enablement gate 활성화 방식, NULL backfill 기간 동안의 fail-closed boundary 정의 등 구현 착수 전 확정이 필요한 설계 결정이 있다.
|
|
|
|
## Milestones
|
|
|
|
1. Design confirmed — daemon registry interface 형태, enforcement gate 활성화 방식 확정
|
|
2. REQ-009 migration 적용 + pytest 통과
|
|
3. REQ-023 daemon registry CRUD 구현 + targeted test 통과
|
|
4. REQ-005/012 daemon binding/rotate 구현 + targeted test 통과
|
|
5. REQ-006/007/008 daemon-scoped API 구현 + daemon A/B 분리 시나리오 테스트 통과
|
|
6. REQ-011/028 문서 갱신 완료 + 전체 pytest 통과
|
|
7. Verification — 전체 AC evidence 매핑 완료, ready for release
|
|
|
|
## Risks
|
|
|
|
- R-1 (High): NULL backfill 상태에서 daemon-scoped enforcement를 켜면 기존 service-token/asset이 연쇄 403에 직면해 운영 중단 발생 가능. 완화: enforcement는 inventory 완료 + dry-run zero-active-NULL/zero-mismatch + release approver 승인 이후에만 활성화.
|
|
- R-2 (Medium): daemon registry interface 형태 결정이 늦어지면 REQ-005/023 구현이 지연됨. 완화: design 단계에서 먼저 확정.
|
|
- R-3 (Medium): 기존 Alembic chain과 migration 충돌. 완화: 신규 revision을 기존 head에 선형으로 연결, `alembic history` 정상 여부 migration test에서 확인.
|