portfolio-hub/docs/releases/rel-006_20260513_daemon-model-implementation.md

# REL-006: Daemon Model Implementation

- Status: draft
- Profile: app-service
- Included Batch: BAT-010

## Scope
- Included:
  - BAT-010 (REQ-009/023/005/012/006/007/008/011/028): 데몬 모델 전체 구현
    - Alembic migration 20260513_0016: daemons 테이블, auth_tokens.daemon_id, portfolios.managed_by_daemon_id 추가
    - Daemon registry CRUD: `pfhub daemon create/list/update`
    - Service-token 발급 시 daemon_id binding (`--daemon-id` 옵션)
    - Service-token rotate daemon_id 불변식 (runtime_id만 갱신, daemon_id 유지)
    - GET /v1/assets daemon-scoped 필터 + NULL daemon_id token → 403 fail-closed
    - GET /v1/user_info daemon_id 필드 추가 + NULL → 200+null diagnostic
    - POST /v1/assets/{asset_id}/ledger/trades daemon assignment authorization (3단계 fail-closed)
    - docs/interface-contract.md, docs/data-model.md, docs/runtime-flows.md daemon-aware 갱신
    - README.md daemon provisioning runbook + enforcement enablement gate + runtime_id/daemon_id 역할 구분
- Excluded:
  - CLI `pfhub portfolio update --daemon-id` (portfolio에 daemon 직접 할당 CLI 경로 — 향후 배치)
  - pre-existing test_cli.py 7개 실패 수정 (별도 배치)
  - 실제 TimescaleDB 인스턴스 integration test (환경 미구성 — 배포 시 수행)

## Rollout Plan

1. **사전 준비**: 아래 enforcement gate 4종 evidence 확보
   - NULL daemon_id 서비스 토큰 inventory 쿼리 실행 및 zero-active-NULL 확인
   - Dry-run: daemon mismatch 쿼리 실행 및 zero-mismatch 확인
   - Release approver 사전 승인
2. **DB migration 적용**: `PORTFOLIOHUB_DB_ENABLED=true pfhub migrate-db` 실행 (migration 20260513_0016 → daemons table, daemon_id 컬럼 추가)
3. **Service 배포**: portfoliohub 서비스 재시작 (새 바이너리/코드 배포)
   - 주의: NULL daemon_id token은 GET /v1/assets + POST ledger/trades에서 즉시 403 반환 시작
   - 기존 service-token이 있다면 배포 전 daemon 등록 + token rotate 또는 신규 발급 완료 후 배포
4. **Health 확인**: `GET /health` → `{"status": "ok"}` 확인
5. **Daemon provisioning smoke**: `pfhub daemon create` → `pfhub service-token issue --daemon-id` → GET /v1/assets 정상 응답 확인

## Rollback Plan

- **Migration rollback**: `alembic downgrade 20260511_0015`
  - 조건: migrate-db 실패 또는 daemons 테이블 생성 오류
  - 영향: daemons 테이블 제거, auth_tokens.daemon_id + portfolios.managed_by_daemon_id 컬럼 제거
  - 주의: daemon_id 컬럼은 nullable이므로 downgrade 전 기존 데이터 손실 여부 확인
- **Service rollback**: 이전 커밋으로 서비스 롤백
  - 조건: 배포 후 health endpoint 실패 또는 v1 API 연쇄 403 발생 (non-NULL token 포함)
  - 이전 서비스는 daemon_id 컬럼을 무시하므로 DB 롤백 없이 서비스만 롤백 가능
- **데이터 롤백 불필요 조건**: NULL backfill 상태 유지 중(daemon 미등록)이면 컬럼만 제거하면 됨

## Verification Checklist

> Local validation snapshot (KST 2026-05-14 08:31): `docker-compose.local-test.yml` 기반 TimescaleDB와 로컬 app process smoke로 확인했다. 아래 체크는 actual deploy evidence가 아니라 local pre-release validation 결과다.
>
> 참고: migration 20260513_0016은 local test DB에 online apply로 검증했다. offline `alembic --sql` dry-run은 migration 내부의 `inspect(op.get_bind())` 사용 때문에 현재 그대로는 성립하지 않는다.

### 배포 전
- [x] migration 20260513_0016이 local test DB(target DB 대체 검증)에 online 적용 가능한지 확인 (`pfhub migrate-db` → head, `alembic history` 정상)
- [x] NULL daemon_id service-token inventory 확인 (`SELECT COUNT(*) FROM auth_tokens WHERE daemon_id IS NULL AND token_type='service' AND revoked_at IS NULL` → `0`)
- [x] daemon mismatch dry-run 확인 (`SELECT COUNT(*) FROM portfolios WHERE managed_by_daemon_id IS NOT NULL` → `0`)
- [x] `pytest tests/` 결과 확인 (`128 passed / 7 failed`, pre-existing CLI 실패와 일치)
- [ ] release approver 승인 확보

### 배포 후
- [x] `GET /health` → HTTP 200, `{"status": "ok", "service": "portfolio-hub"}`
  - local app process smoke 결과: `status=ok`, `service=portfolio-hub`, `version=0.1.0`
- [x] `pfhub_DB_ENABLED=true pfhub health-check` → exit code 0
- [x] `pfhub daemon create alpha-bot --user <admin_user>` → daemon_id 반환 확인
  - local CLI plain output에서 `Daemon(id=...)` 확인. 단, `--format json`은 datetime serialization bug로 실패한다.
- [x] `pfhub service-token issue test-daemon-token --user <user> --daemon-id <daemon_id> --no-expiry` → token 발급 확인
  - local CLI JSON output에서 `token_id`, `runtime_id`, `daemon_id` 반환 확인. raw token은 의도적으로 마스킹된다.
- [x] `GET /v1/assets` (daemon-bound token) → HTTP 200, daemon 소유 asset만 포함
  - local smoke fixture에서 매칭 daemon portfolio 1건만 반환되고 다른 daemon portfolio는 비노출 확인
- [x] `GET /v1/assets` (NULL daemon_id token) → HTTP 403 확인
  - 응답 detail: `daemon_id not assigned to this token`
- [x] `GET /v1/user_info` (daemon-bound token) → HTTP 200, `daemon_id` 필드 포함
- [ ] `pfhub service-token rotate test-daemon-token --force` → 새 runtime_id, 동일 daemon_id 확인
  - local CLI 검증 실패: `idx_auth_tokens_service_name_unique` 제약으로 rotate insert가 막힌다.
- [ ] journalctl/Caddy access log에 ERROR 없음 확인

## Release Execution Evidence
- Release Status Transition Target: released

### Deployment Facts
- Executed At:
  - <배포 시작 시각>
- Completed At:
  - <배포 완료 시각>
- Environment:
  - <배포 대상 환경>
- Operator:
  - <배포 수행자>
- Revision or Artifact:
  - <커밋 SHA 또는 배포 artifact 식별자>
- Commands or Procedure:
  - <실행 명령 또는 배포 절차 요약>

### Profile-Specific Checks
- app-service:
  - Health Endpoint:
    - <호출 결과와 확인 시각>
  - Startup Log Fields:
    - <app, event, command, run_id 확인 결과>
  - Request Log Fields:
    - <request_id 포함 여부와 확인 결과>
  - Smoke or Manual Verification:
    - <배포 후 재실행한 검증과 결과>

### Rollback Outcome
- Rollback Required:
  - <yes 또는 no>
- Rollback Trigger:
  - <발생 시 원인, 없으면 none>
- Rollback Action:
  - <수행한 조치, 없으면 none>

### Release Decision Evidence
- Released Decision:
  - <released 전환 여부>
- Rationale:
  - <released 전환 판단 근거>
- Recorded By:
  - <기록자>
- Recorded At:
  - <기록 시각>

## Feedback Handoff
- Observation Summary:
  - <운영 관찰 사실 요약 또는 없음>
- Discovery Input:
  - NULL daemon_id token을 보유한 기존 service-token의 마이그레이션 경로 (rotate + daemon-id rebinding 자동화 후보)
  - CLI `pfhub portfolio update --daemon-id` 추가 검토 (현재 DB 직접 수정 필요)
- REQ Input:
  - portfolio에 daemon을 CLI로 할당/해제하는 명령 (managed_by_daemon_id 업데이트)
  - daemon deactivation 시 bound token 자동 revoke 정책
- Change Request Input:
  - pre-existing test_cli.py 7개 실패 수정 (별도 CHG 또는 신규 REQ)