portfolio-hub/docs/srs/Migration/req-048_broker-credentials-daemon-id-backfill.md

REQ-048: 기존 user-scoped 인증정보 daemon_id 백필

• Status: Implemented
• 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 무효화 아님(비차단).

CHG-20260628-03

• Date: 2026-06-28
• Author: 팀장(Claude)

Change Summary

• confirm-req-implemented: Approved → Implemented. PR #17 머지(mergeCommit d4acfd4), BAT-020, QC PASS-WITH-NOTES(blocker 0), 테스트 통과.

Intent

• BAT-020 delivery(PR #17 머지)에서 백필 CLI(backfill-daemon-id) 구현 및 AC-1~7 테스트 통과가 확인되어 Implemented로 전환한다.

Acceptance Criteria Delta

• Added: 없음
• Updated: 없음
• Removed: 없음

Impacted Area Delta

• 없음 (상태 전환만)

Delivery Trace Delta

• Batches: BAT-020 (PR #17, mergeCommit d4acfd4)
• Releases: 미정

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: implemented

Validation Plan

• BAT-020 verification 문서 및 QC PASS-WITH-NOTES 결과(blocker 0)로 AC-1~7 근거 확보됨.