portfolio-hub/docs/srs/Deployment/req-020_production-admin-bootstrap-and-operator-access-runbook.md

req-020: 실배포 admin bootstrap 및 steady-state operator access runbook

• Status: Approved
• Type: Deployment
• Priority: High
• Owner: repository-maintainers

Intent

• 실배포 환경에서 admin auth context를 확보하는 경로가 문서화되지 않으면, 운영자는 release smoke를 재현 가능하게 수행할 수 없고 bootstrap과 steady-state access를 혼동해 보안 사고가 발생할 수 있다.
• README.md Production Operator Runbook에 admin bootstrap(신규 환경/disaster recovery 전용), steady-state canonical access(운영자 개인 admin 로그인), break-glass fallback(env admin token) 3-tier 경로를 명시하고 각 경로의 사용 조건을 구분한다.

Requirement

• README.md Production Operator Runbook 섹션은 다음 3-tier 경로를 조건과 함께 구분하여 문서화해야 한다.
  1. bootstrap path: PORTFOLIOHUB_BOOTSTRAP_* 기반 초기 사용자 생성. users 테이블이 비어 있는 신규 환경 또는 disaster recovery 직후 admin 사용자 부재가 확인된 경우에만 허용.
  2. steady-state canonical path: 운영자 소유 admin 사용자 계정으로 /auth/login하여 DB-issued admin session 또는 동일 컨텍스트에서 발급한 client token 확보. 이 admin context로 POST /auth/service-tokens를 호출해 release smoke용 read/trade-write service-token을 발급.
  3. break-glass fallback: 환경 변수 기반 admin token을 /opt/portfoliohub/.env에서 꺼내는 경로. 운영자 로그인 경로가 모두 막혔을 때만 허용. 정기 smoke의 표준 경로로 사용 금지.
• 각 경로의 사용 조건, 운영 책임 역할(deployment secret custodian, production operator/release approver), secret 보관 위치(/opt/portfoliohub/.env / EnvironmentFile)를 명시한다.
• raw credential, raw token, bootstrap password는 README 또는 release 문서에 기록하지 않는다.

Acceptance Criteria

1. Given README.md Production Operator Runbook 섹션이 존재할 때, When 운영자가 섹션을 읽을 때, Then bootstrap path / steady-state canonical path / break-glass fallback이 각각 사용 조건과 함께 구분되어 기술되어 있어야 한다.
2. Given users 테이블이 비어 있지 않은 실배포 환경에서, When PORTFOLIOHUB_BOOTSTRAP_* 기반 bootstrap 로직이 실행될 때, Then 기존 사용자를 덮어쓰거나 중복 생성하지 않고 bootstrap을 건너뛰어야 한다 (idempotency 보장).
3. Given README runbook에 역할 책임이 명시되어 있을 때, When 운영자가 runbook을 참조할 때, Then deployment secret custodian과 production operator/release approver 역할이 구분되어 있고 secret 보관 위치(/opt/portfoliohub/.env)가 명시되어 있어야 한다.
4. Given 운영자가 steady-state canonical path를 따를 때, When /auth/login → POST /auth/service-tokens 순서로 실행할 때, Then admin session token 기반 service-token 발급 성공 경로가 runbook에 기술되어 있어야 한다.

Impacted Area

• Docs: README.md — Production Operator Runbook 섹션 (3-tier 경로 구분 및 역할 책임 보강)
• Modules: app/core/config.py (bootstrap 환경 변수 운영 제약 확인), app/main.py (bootstrap idempotency 동작 확인)
• Tests: bootstrap idempotency는 기존 구현 확인으로 대체 가능. 별도 신규 테스트 불필요.

Notes

• NFR-1 (raw credential 비노출): 이 REQ의 핵심 제약으로 포함됨. Release 문서, README 등 모든 운영 문서에서 raw value 기록 금지.
• NFR-3 (bootstrap idempotency): app/main.py에서 users 테이블이 비어 있을 때만 bootstrap 사용자를 생성하는 로직이 기존에 구현되어 있음. AC-2는 기존 구현 확인으로 검증한다.
• /auth/login 엔드포인트가 실제 구현되어 있어야 steady-state canonical path가 완성된다. 현재 저장소에 로그인 엔드포인트가 없으면 해당 AC는 구현 시 재검토가 필요하다.
• 이 REQ는 기능 추가보다 운영 절차 문서화가 주 목적이다. 코드 변경이 필요할 경우 최소 범위로 제한한다.
• Source Discovery: dcy-005 FR-1

Change Log

CHG-20260512-02

• Date: 2026-05-12
• Author: repository-maintainers

Change Summary

• Status: Proposed → Approved (confirm-req 게이트 통과)

Intent

• 필수 필드, AC, Notes blocker 없음 확인 후 승인 전환

Acceptance Criteria Delta

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

Impacted Area Delta

• Docs: 없음
• Modules: 없음
• Tests: 없음

Delivery Trace Delta

• Batches: none
• Releases: none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: none

Validation Plan

• 승인 전환만 수행, 추가 검증 불필요

CHG-20260512-01

• Date: 2026-05-12
• Author: repository-maintainers

Change Summary

• REQ 초안 생성 (dcy-005 FR-1 기반)

Intent

• 실배포 admin bootstrap 및 steady-state access 경로 운영 문서화 요구사항 정의

Acceptance Criteria Delta

• Added:
  • AC-1~4 초안 생성

Impacted Area Delta

• Docs:
  • README.md Production Operator Runbook 섹션
• Modules:
  • app/core/config.py, app/main.py (확인 범위)
• Tests:
  • 없음 (기존 구현 확인으로 대체)

Delivery Trace Delta

• Batches:
  • none (미배정)
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: none

Validation Plan

• README.md Production Operator Runbook 섹션의 3-tier 경로 구분 확인
• app/main.py bootstrap idempotency 코드 리뷰로 AC-2 검증