# 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에서 확인.