portfolio-hub/docs/releases/rel-003_20260512_cli-user-scoping-and-db-ops-runbook.md

REL-003: CLI user scoping and local DB ops runbook

• Status: released
• Profile: tooling
• Included Batch: BAT-003, BAT-004, BAT-007

Scope

• Included:

  • BAT-003 (REQ-013) — pfhub portfolio list --user <username> 필수화; owner_user_id 기반 포트폴리오 필터링
  • BAT-004 (REQ-014) — pfhub portfolio create --user <username> 필수화; 생성 시 owner_user_id 설정
  • BAT-007 (REQ-001, REQ-002, REQ-003) — 로컬 DB 운영 runbook 및 baseline 문서 갱신
    • README.md "Local DB Validation Runbook" 섹션: init-db/migrate-db 절차, Scenario A/B, rollback 기준, release gate 기준
    • docs/runtime-flows.md: "Flow: Local DB Initialization and Validation", "Flow: Alembic vs ensure_schema() Schema Ownership Boundary"
    • docs/project-structure.md: "Schema Ownership Boundary" 섹션

• Excluded:

  • BAT-006 (REQ-016~019) — portfolios UUID migration 및 HTTP API/CLI UUID 전환 (app-service, 별도 릴리즈)
  • HTTP API 변경 없음 (서버 재기동 불필요)
  • DB 스키마 migration 없음

Breaking Changes

• pfhub portfolio list에서 --user <username> 이 필수가 됨. --user 없이 실행 시 오류 메시지와 exit code 1 반환.
• pfhub portfolio create에서 --user <username> 이 필수가 됨. --user 없이 실행 시 오류 메시지와 exit code 1 반환.
• 기존 스크립트 또는 자동화에서 portfolio list / portfolio create를 --user 없이 호출하고 있다면 수정 필요.

Rollout Plan

1. 패키지 또는 소스를 최신 커밋으로 업데이트한다.
2. pfhub --help 실행 → portfolio 커맨드 그룹이 정상 로드되는지 확인한다.
3. pfhub portfolio list (--user 없이) 실행 → exit code 1과 오류 메시지가 출력되는지 확인한다.
4. pfhub portfolio list --user <valid_username> 실행 → 해당 사용자의 포트폴리오만 출력되는지 확인한다.
5. pfhub portfolio create <name> --symbol X --force (--user 없이) 실행 → exit code 1과 오류 메시지가 출력되는지 확인한다.
6. README.md "Local DB Validation Runbook" 섹션이 정상 렌더링되는지 확인한다.
7. 서버 재기동 불필요.

Rollback Plan

• 이 릴리즈는 CLI 동작 변경과 문서 추가만 포함한다. DB 상태 변경 없음.
• 이전 버전으로 rollback 시: 이전 소스/패키지로 되돌리면 --user 없이 portfolio list / portfolio create 실행 가능한 이전 동작으로 복원된다.
• 문서 rollback은 git revert로 처리한다.

Verification Checklist

배포 전 확인

• BAT-003 verification.md Status: verified, Blocking Issues: 없음 확인
• BAT-004 verification.md Status: verified, Blocking Issues: 없음 확인
• BAT-007 verification.md Status: passed, Blocking Issues: 없음 확인
• pytest tests/test_cli.py -v 전체 통과 확인 — 49 passed in 1.44s
• README.md "Local DB Validation Runbook" 섹션 존재 확인
• docs/runtime-flows.md "Flow: Local DB Initialization and Validation" 섹션 존재 확인
• docs/project-structure.md "Schema Ownership Boundary" 섹션 존재 확인

배포 후 확인

• pfhub portfolio list 실행 → --user 미입력 시 exit code 1 반환 확인 — test evidence: test_cli_portfolio_list_without_user_exits_error PASS
• pfhub portfolio list --user <valid> 실행 → 해당 사용자 포트폴리오만 반환 확인 — test evidence: test_cli_portfolio_list_with_valid_user_filters_by_owner PASS
• pfhub portfolio create <name> --symbol X --force 실행 → --user 미입력 시 exit code 1 반환 확인 — test evidence: test_cli_portfolio_create_without_user_exits_error PASS
• pfhub portfolio create <name> --symbol X --user <valid> --force 실행 → 정상 생성 확인 — test evidence: test_cli_portfolio_create_with_valid_user_sets_owner PASS

Release Execution Evidence

• Release Status Transition Target: released

Deployment Facts

• Executed At:
  • 2026-05-12
• Completed At:
  • 2026-05-12
• Environment:
  • local workspace (tooling profile — 서버 배포 불필요)
• Operator:
  • repository-maintainers
• Revision or Artifact:
  • 2e1298a978
• Commands or Procedure:
  • tooling profile — 별도 패키지 설치 단계 없음
  • CLI regression 확인: .venv/bin/pytest tests/test_cli.py -v → 49 passed in 1.44s
  • portfolio list CLI evidence: BAT-003 verification — test_cli_portfolio_list_without_user_exits_error, test_cli_portfolio_list_with_valid_user_filters_by_owner, test_cli_portfolio_list_with_unknown_user_exits_error, test_cli_portfolio_list_in_memory_mode_filters_owner 모두 PASS
  • portfolio create CLI evidence: BAT-004 verification — test_cli_portfolio_create_without_user_exits_error, test_cli_portfolio_create_with_valid_user_sets_owner, test_cli_portfolio_create_with_unknown_user_exits_error 모두 PASS
  • DB runbook 문서 확인: BAT-007 verification — REQ-001/002/003 AC 전체 PASS

Profile-Specific Checks

• tooling:
  • Install or Upgrade Smoke:
    • Source checkout 기준 tooling release로 별도 패키지 설치 단계는 없음. 현재 workspace revision에서 CLI regression evidence 확인: .venv/bin/pytest tests/test_cli.py -v → 49 passed in 1.44s.
  • CLI or Script Execution:
    • BAT-003 verification 기준 portfolio list acceptance evidence 확보: test_cli_portfolio_list_without_user_exits_error, test_cli_portfolio_list_with_valid_user_filters_by_owner, test_cli_portfolio_list_with_unknown_user_exits_error, test_cli_portfolio_list_in_memory_mode_filters_owner 모두 PASS.
    • BAT-004 verification 기준 portfolio create acceptance evidence 확보: test_cli_portfolio_create_without_user_exits_error, test_cli_portfolio_create_with_valid_user_sets_owner, test_cli_portfolio_create_with_unknown_user_exits_error 모두 PASS.
    • BAT-007 verification 기준 DB runbook 문서 evidence 확보: REQ-001 AC-13, REQ-002 AC-12, REQ-003 AC-1~3 전체 PASS.
  • Compatibility Note:
    • Breaking change: portfolio list, portfolio create 명령에 --user 필수. 기존 스크립트 점검 필요.

Rollback Outcome

• Rollback Required:
  • no
• Rollback Trigger:
  • none
• Rollback Action:
  • none

Release Decision Evidence

• Released Decision:
  • released
• Rationale:
  • BAT-003/004/007 모두 release-candidate. REQ-001/002/003/013/014 모두 Implemented. tooling profile이므로 서버 재기동 불필요. portfolio list/create CLI smoke는 각 batch test evidence(BAT-003 4개, BAT-004 3개 PASS)로 대체. DB runbook 문서 3종 BAT-007 완료로 확인. pytest tests/test_cli.py -v → 49 passed in 1.44s 전체 회귀 통과.
• Recorded By:
  • repository-maintainers
• Recorded At:
  • 2026-05-12

Feedback Handoff

• Observation Summary:
  • tooling profile release 전 항목 모두 test evidence로 확인 완료. 실환경 CLI smoke는 수행하지 않고 batch verification evidence로 대체함.
• Discovery Input:
  • none
• REQ Input:
  • none
• Change Request Input:
  • none