# 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

### 배포 전 확인

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

### 배포 후 확인

- [x] `pfhub portfolio list` 실행 → `--user` 미입력 시 exit code 1 반환 확인 — test evidence: `test_cli_portfolio_list_without_user_exits_error` PASS
- [x] `pfhub portfolio list --user <valid>` 실행 → 해당 사용자 포트폴리오만 반환 확인 — test evidence: `test_cli_portfolio_list_with_valid_user_filters_by_owner` PASS
- [x] `pfhub portfolio create <name> --symbol X --force` 실행 → `--user` 미입력 시 exit code 1 반환 확인 — test evidence: `test_cli_portfolio_create_without_user_exits_error` PASS
- [x] `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:
  - 2e1298a978d789bae8bc6b31d9e94027fc63dc66
- 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-1~3, REQ-002 AC-1~2, 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