docs(dcy-010): draft-req + confirm-req — REQ-046~051 Approved (daemon-scoped broker credential provisioning)

Adds SRS specification documents for daemon-scoped broker credential management: - REQ-046: Broker credential daemon_id field - REQ-047: Migration PKv1→PKv2 with daemon_id - REQ-048: Backfill existing broker credentials with daemon_id - REQ-049: User info endpoint including daemon-scoped credentials - REQ-050: Credential CLI --daemon-id option - REQ-051: Security isolation per daemon boundary Updates dcy-010 discovery document with generated REQ references and register. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VHtM5Ws1HKCKQ4JGi6GRb5
2026-06-28 00:22:02 +09:00
parent b0dfc42966
commit fc99f507a5
8 changed files with 564 additions and 3 deletions
@@ -0,0 +1,91 @@
+# REQ-048: 기존 user-scoped 인증정보 daemon_id 백필
+
+- Status: Approved
+- Type: Migration
+- Priority: High
+- Owner: Justin Ko
+
+## Intent
+- REQ-047 Step 1 적용 이후 `broker_credentials.daemon_id`가 NULL인 기존 행들을 운영자가 지정하는 daemon_id로 백필하여, REQ-047 Step 2(PK 전환)가 적용 가능한 상태로 만든다.
+- dcy-010 FR-4(기존 user-scoped 인증정보를 손실 없이 daemon-scoped로 이전)의 데이터 이전 경로를 제공한다. 백필은 CLI 명령 또는 one-shot 마이그레이션 스크립트로 수행한다.
+
+## Requirement
+- `pfhub credential backfill-daemon-id` CLI 명령(또는 동등한 alembic data migration revision)을 제공한다. 이 명령은 다음을 수행한다:
+  - `broker_credentials`에서 `daemon_id IS NULL`인 행을 조회한다.
+  - 각 행의 `user_id`에 대해 운영자가 제공한 매핑(`--user <username> --daemon-id <daemon_id>`)으로 `daemon_id`를 UPDATE한다.
+  - 백필 대상 행이 없으면 "이미 완료됨" 메시지를 출력하고 정상 종료한다.
+  - `--dry-run` 옵션을 제공하여 실제 UPDATE 없이 대상 행과 매핑 결과를 출력한다.
+- 백필 완료 후 `daemon_id IS NULL`인 행이 0건임을 검증하는 단계를 명령 결과 또는 별도 verify 서브커맨드로 제공한다.
+- 기존 행의 암호화된 인증정보(`encrypted_payload`, `account_ref`, `credential_version`, `last_rotated_at`)는 백필 과정에서 변경되지 않는다.
+- `--force` 옵션으로 확인 프롬프트를 생략할 수 있다.
+
+## Acceptance Criteria
+1. Given `broker_credentials`에 `daemon_id=NULL`인 행이 있고 `--user u1 --daemon-id d1` 매핑을 제공하면, When `backfill-daemon-id` 명령 실행, Then 해당 `user_id=u1(user.id)`에 해당하는 행의 `daemon_id`가 `d1`로 UPDATE된다.
+2. Given AC-1 실행 후, When `broker_credentials`에서 `daemon_id IS NULL` 행 조회, Then 0건이 반환된다.
+3. Given `--dry-run` 옵션으로 실행, When 백필 대상 행이 있으면, Then DB UPDATE 없이 대상 행과 예상 매핑이 출력되고 실제 데이터는 변경되지 않는다.
+4. Given 백필 실행 중, When `encrypted_payload`, `account_ref`, `credential_version`, `last_rotated_at` 컬럼 확인, Then 백필 전후 값이 동일하다(데이터 손실 없음).
+5. Given `daemon_id IS NULL`인 행이 없을 때, When `backfill-daemon-id` 명령 실행, Then "이미 완료됨" 메시지와 함께 정상 종료(exit 0)된다.
+6. Given 존재하지 않는 user를 `--user` 옵션으로 지정, When 명령 실행, Then 오류 메시지와 함께 비정상 종료(exit 1)된다.
+7. Given 백필 완료 후 REQ-047 Step 2(PK 전환) revision 적용, When `\d broker_credentials` 확인, Then PK `(daemon_id, broker)` 제약이 적용되고 NOT NULL 위반 없이 성공한다.
+
+## Impacted Area
+- Docs:
+  - `docs/data-model.md` — `BrokerCredential` 데이터 이전 절차(백필 단계) 명시.
+- Modules:
+  - `app/cli/commands/credential.py` — `backfill-daemon-id` 서브커맨드 추가.
+  - `app/repositories/postgres.py` — `update_broker_credential_daemon_id(user_id, daemon_id)` 또는 동등한 메서드 추가(또는 CLI에서 직접 쿼리).
+- Tests:
+  - `backfill-daemon-id` 명령 단위 테스트(mock repo 기반): 정상 백필, dry-run, 이미 완료, 사용자 미존재 케이스.
+  - 백필 전후 `encrypted_payload` 동등성 검증(AC-4).
+
+## Notes
+- 이 REQ는 **1회성 운영 작업**이다. 개발 환경에서는 테스트 목적으로 반복 실행 가능하도록 설계한다.
+- 백필 매핑은 운영자가 직접 제공한다. "어떤 user가 어떤 daemon_id에 매핑되는가"는 인프라/운영 도메인 지식이 필요하며 자동화할 수 없다.
+- CLI 구현 방식(subcommand 추가 vs alembic data migration revision)은 batch design 단계에서 확정한다. 어느 쪽이든 AC-1~7을 만족해야 한다.
+- `--user` 옵션은 username으로 받고 내부에서 `get_user_by_username()`으로 user_id를 해석한다(기존 CLI 패턴과 동일).
+- Source: dcy-010 FR-4, §4 C1(마이그레이션 단계적 경로).
+
+## Change Log
+
+### CHG-20260628-01
+- Date: 2026-06-28
+- Author: Justin Ko
+
+#### Change Summary
+- 신규 생성 (Proposed) — dcy-010 FR-4 산출물.
+
+#### Intent
+- dcy-010 FR-4(기존 user-scoped 인증정보 손실 없는 daemon-scoped 이전)를 독립 REQ로 정규화한다. REQ-047 Step 1과 Step 2 사이의 데이터 이전 경로를 담당한다.
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1 ~ AC-7 전체 (신규 초안)
+- Updated: 없음
+- Removed: 없음
+
+#### Impacted Area Delta
+- Docs:
+  - `docs/srs/Migration/req-048_broker-credentials-daemon-id-backfill.md` 신규 생성
+  - `docs/data-model.md` 갱신 예고
+- Modules:
+  - `app/cli/commands/credential.py` (backfill subcommand), `app/repositories/postgres.py` (업데이트 메서드)
+- Tests:
+  - backfill CLI 단위 테스트 신규
+
+#### Delivery Trace Delta
+- Batches: 미정 (suggest-batch-reqs 대기)
+- Releases: 미정
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: confirm-req 후 batch 배정. REQ-047 Step 1 이후, Step 2 이전 순서 의존 관계 준수.
+
+#### Validation Plan
+- pytest mock repo 기반 단위 테스트 AC-1~6. 개발 DB 통합: backfill → REQ-047 Step 2 순서 검증(AC-7).
+
+### CHG-20260628-02
+- Date: 2026-06-28
+- Author: 팀장(Claude)
+- confirm-req: `Proposed` → `Approved`. dcy-010 FR-4 추적. dry-run/verify·암호화 payload 불변(AC-4) 적절. 구현방식(CLI subcommand vs alembic data revision)은 batch design 위임 — AC 무효화 아님(비차단).