portfolio-hub/docs/discovery/dcy-001_20260430_real-db-migration-validation-and-operations-readiness.md

# 0. 문서 상태
이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.

- 상태: confirmed
- 문서 ID: dcy-001_20260430_real-db-migration-validation-and-operations-readiness
- 이슈명: 실DB 마이그레이션 검증 및 운영 준비
- 작성 시각(KST): 2026-04-30 22:27
- 마지막 갱신 시각(KST): 2026-04-30 23:01
- 대체됨: 없음
- 후속 Discovery 참조: 없음
- 생성된 REQ 참조: docs/srs/Testing/req-001_local-db-validation-scenarios.md, docs/srs/Migration/req-002_alembic-runtime-schema-ownership.md, docs/srs/Documentation/req-003_local-db-operations-runbook-and-baseline-updates.md

# 1. 계획 상태 요약
현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다.

- 연계 문서 현황:
	- 관련 점수 파일: 미생성
	- 관련 TODO/메모: temp/plan.md
- 해석:
	- bootstrap-baseline 완료 이후 active Discovery, REQ, Batch, Release가 없는 no-history 상태이므로 첫 real Discovery를 새로 생성한다.
	- 현재 저장소에는 init-db, migrate-db, Alembic migration 경로가 구현돼 있지만 로컬 docker compose 기반 DB 검증 기준과 legacy DB 비지원 범위는 아직 REQ 수준으로 정리되지 않았다.

# 2. 요구사항 판정 결과
이번 요청이 기존 요구사항과 비교해 신규인지, 유사한지, 중복인지 판단하고 그 근거를 남긴다.

- 판정: 신규
- 근거
	- docs/discovery/ 아래에는 전역 index만 있고 실DB 마이그레이션 검증 또는 운영 준비를 다루는 기존 Discovery 문서가 없다.
	- baseline 문서와 README는 실DB 검증이 남은 과제라고만 적고 있어, 이번 주제는 후속 Delivery 산출물로 연결될 독립 Discovery로 추적하는 편이 명확하다.

# 3. 문제점의 요약
문제의 현재 상태, 기대 상태, 관련 이해관계자, 제약사항을 정리한다. Discovery의 핵심 맥락을 가장 먼저 이해할 수 있어야 한다.

- 현재 상태
	- app/cli/commands/health.py 에는 init-db, migrate-db, health-check 명령이 구현돼 있고, app/db/migrations.py 는 Alembic upgrade head 와 legacy schema stamp 분기를 제공한다.
	- app/repositories/postgres.py 는 다수의 DB 호출 전에 ensure_schema() 를 실행해 런타임 중 테이블을 선제 생성하며, migrations/versions/20260410_0009_portfolio_comments_table.py 는 이 경로와 충돌하지 않도록 IF NOT EXISTS 기반으로 작성돼 있다.
	- docs/runtime-flows.md 와 docs/data-model.md 는 실DB 검증, 운영 절차, schema ownership 경계가 아직 확정되지 않았다고 기록한다.
- 기대 상태
	- 로컬 docker compose 로 기동한 PostgreSQL 또는 TimescaleDB 환경을 기준으로 init-db 와 migrate-db 의 기대 동작, 실패 조건, 검증 증거가 정의돼 있어야 한다.
	- Alembic migration 책임과 runtime ensure_schema() 책임 경계가 명확해지고, 운영자가 어떤 절차로 DB를 준비하고 실패 시 어떻게 복구할지 문서로 추적 가능해야 한다.
- 이해관계자
	- 백엔드 유지보수 담당자
	- DB 운영 또는 배포 담당자
	- REQ 승인자 및 release 검토자
- 제약사항
	- 기존 Alembic revision chain 을 깨거나 임의 schema reset 을 전제로 한 해결책은 허용하지 않는다.
	- 검증 대상은 현재 코드와 migration 이 지원하는 PostgreSQL 또는 TimescaleDB 경로여야 하며, Redis 와 Loki 운영 확장은 이번 Discovery의 직접 범위가 아니다.

## 주요 사용자 시나리오
사용자 또는 운영자가 실제로 어떤 상황에서 이 변경을 필요로 하는지 대표 시나리오를 적는다.

- 운영자가 새 PostgreSQL 또는 TimescaleDB 인스턴스를 준비한 뒤 pfhub init-db 와 health-check 로 서비스 기동 가능 상태를 검증하고 싶다.
- 유지보수 담당자가 기존 schema 를 가진 환경에서 pfhub migrate-db 를 실행할 때 어떤 migration 이 안전한지와 어떤 사전 점검이 필요한지 알고 싶다.
- release 검토자가 DB migration 실패 시 롤백 또는 재시도 판단 기준을 문서와 검증 로그로 확인하고 싶다.

# 4. 이번에 정의할 변경
이번 Discovery에서 다루는 핵심 변경 항목을 목록으로 적는다. 기능, 구조, 규칙 변경을 함께 포함해도 된다.

- 로컬 docker compose 기반 실DB 기준 init-db, migrate-db, health-check 검증 시나리오와 pass or fail 판단 기준을 정의한다.
- Alembic migration 과 PostgresPortfolioRepository.ensure_schema() 사이의 schema ownership 경계를 정리하고, 로컬 runtime bootstrap 흔적과 충돌할 수 있는 revision 및 운영 리스크를 식별한다.
- 검증 결과를 README, docs/runtime-flows.md, docs/project-structure.md 에 반영할 수 있도록 운영 준비 산출물과 문서 갱신 요구를 정의한다.

## 영향 범위
변경이 미칠 코드/문서/운영 범위를 명시해 REQ 정제와 batch planning에서 추정 누락을 줄인다.

- 코드 영향:
	- app/cli/commands/health.py 의 init-db, migrate-db, health-check 명령
	- app/db/migrations.py 의 bootstrap_or_upgrade_to_head 와 legacy schema 판정 로직
	- app/repositories/postgres.py 및 migrations/versions/*.py 의 schema 생성과 migration 충돌 지점
- 문서 영향:
	- docs/runtime-flows.md 의 DB 준비 및 migration 실행 흐름
	- docs/project-structure.md 의 migration ownership 및 runtime bootstrap 책임 경계
	- README.md 의 운영 절차, 사전 조건, 검증 예시
- 운영 영향:
	- fresh DB 초기화 절차, 기존 DB 업그레이드 절차, 실패 시 복구 기준
	- release 전 DB 점검 체크리스트와 검증 로그 수집 방식

# 5. 요구사항 목록
실제로 구현과 검증으로 이어질 요구사항을 기능/비기능으로 나누어 정리하고, 범위 경계를 명확히 적는다.

## 기능 요구사항
- FR-1: 로컬 docker compose 로 기동한 PostgreSQL 또는 TimescaleDB 환경에서 init-db, migrate-db, health-check, 핵심 인증 또는 portfolio smoke flow 까지 이어지는 최소 검증 시나리오를 정의해야 한다.
- FR-2: 로컬 docker compose 환경에서 fresh DB 또는 app runtime 이 일부 schema 를 먼저 만든 상태를 기준으로 Alembic upgrade 와 runtime ensure_schema() 가 충돌할 수 있는 지점을 식별하고, 사전 점검 또는 보정 규칙을 정의해야 한다.
- FR-3: 검증 결과에 따라 app/repositories/postgres.py, app/db/migrations.py, migrations/versions/ 의 책임 경계를 문서화하고 docs/project-structure.md 와 docs/runtime-flows.md 갱신 요구를 명시해야 한다.
- FR-4: 운영자가 DB 준비, migration 실행, 실패 대응, 재시도 여부를 판단할 수 있는 최소 runbook 초안을 정의해야 한다.

## 비기능 요구사항
성능, 운영성, 일관성, 자동화 안정성 등 기능 외 요구사항을 적는다.

- NFR-1: 검증 절차는 로컬 docker compose 검증 환경에서 반복 실행 가능하고, 명령 순서와 기대 결과가 자동화 가능 수준으로 명확해야 한다.
- NFR-2: migration 실패 시 원인 파악에 필요한 revision, 선행 조건, 보정 필요 사항이 로그 또는 문서 증거로 남아야 한다.
- NFR-3: 운영 준비 요구사항은 현재 release 전 검토 체크리스트로 이어질 수 있도록 rollback 또는 재시도 기준을 포함해야 한다.

## 범위 경계
이번 반복에서 반드시 포함할 범위와 명시적으로 제외할 범위를 구분한다.

- In Scope
	- 로컬 docker compose 로 기동한 DB를 기준으로 init-db, migrate-db, health-check, bootstrap admin 생성, 로그인 또는 토큰 발급, portfolio 기본 조회 수준의 DB smoke validation 정의
	- Alembic revision chain 과 ensure_schema() 의 책임 경계 정리 및 관련 문서 갱신 요구 정의
- Out of Scope
	- 공유 dev DB, staging, production-like 환경을 대상으로 한 검증 범위 확장
	- legacy DB schema support, legacy stamp 경로 검증, 과거 운영 DB 보정 절차 정의
	- Redis, Loki, 캐시, 로그 수집 파이프라인의 production hardening
	- ownership 기반 권한 모델 재설계나 외부 API versioning 정책 확정

# 6. 리스크/가정 목록
불확실성과 전제 조건을 분리해서 적는다. 리스크는 영향과 완화 방안을, 가정은 현재 판단의 전제를 기록한다.

## 리스크
- R-1 (High): runtime ensure_schema() 와 Alembic migration 이 동일 객체를 다른 순서로 다루면 실환경에서 migration 재실행 실패 또는 drift 가 발생할 수 있다.
	- 완화 방안: 충돌 가능 revision 을 식별하고, fresh/legacy 시나리오별 허용 순서와 금지 순서를 명시한다.
- R-2 (Medium): 현재 코드에 남아 있는 legacy schema stamp 분기가 이번 범위에서도 지원되는 경로처럼 오해되면 범위 밖 검증이나 운영 판단이 섞일 수 있다.
	- 완화 방안: 이번 Discovery 와 후속 REQ 에서 legacy DB 는 비지원 범위임을 명시하고, 필요 시 별도 Discovery 로 분리한다.
- R-3 (Medium): 운영 준비 범위가 너무 넓어지면 DB migration 검증 Discovery 가 Redis, Loki, 배포 자동화까지 확장되어 첫 반복 집중도가 떨어질 수 있다.
	- 완화 방안: DB 준비와 migration 실행 경로만 이번 Discovery의 핵심 대상으로 고정하고 주변 운영 항목은 후속 Discovery 후보로 분리한다.

## 가정
아직 확정되지 않았지만 현재 문서 작성의 기반이 되는 전제를 적는다.

- A-1: 주 검증 대상 DB 는 PostgreSQL 호환 TimescaleDB 또는 PostgreSQL 이며, 현행 psycopg 연결 방식과 Alembic 환경 설정을 그대로 사용한다.
- A-2: init-db 와 migrate-db 는 운영자가 직접 실행하거나 automation 에서 호출하는 공식 DB 준비 진입점으로 유지한다.
- A-3: legacy DB support 는 이번 반복의 성공 기준에 포함하지 않으며, 실DB 검증 결과가 현재 baseline 문서의 runtime 또는 structure 설명과 다르면 후속 Delivery 에서 해당 baseline 문서를 함께 갱신한다.

## 오픈 질문
답을 아직 모르는 항목을 적는다. 추정으로 덮지 말고 REQ 초안 작성 이전에 확인할 질문으로 남긴다.

- OQ-1: 첫 검증 반복에서 대상으로 삼을 환경 범위는 어디까지인가
	- 상태: Answered
	- 처리 방안: 사용자 결정에 따라 첫 검증 반복의 대상 환경은 로컬 docker compose 기반 DB로 고정한다.
	- 종료 조건: 완료. 이후 REQ 와 batch planning 에서는 shared dev DB, staging, production-like 환경을 기본 범위에서 제외한다.
- OQ-2: legacy schema support 의 허용 범위를 어디까지 문서화해야 하는가
	- 상태: Answered
	- 처리 방안: 사용자 결정에 따라 legacy DB 는 이번 Discovery 와 후속 REQ 범위에서 지원하지 않는다.
	- 종료 조건: 완료. legacy DB 지원이 필요해지면 별도 Discovery 또는 change-req 로 분리한다.

### 오픈 질문 처리 기준
- `Open`: 아직 답이 없고 다음 단계 진행에 영향이 있는 상태다. 문서에 유지한다.
- `Answered`: 답이 확정된 상태다. 관련 본문/요구사항에 반영한 뒤 오픈 질문 목록에서는 제거하거나 resolved 기록으로 이동한다.
- `Deferred`: 지금 단계에서 결정하지 않고 다음 단계 또는 후속 이슈로 넘기는 상태다. 넘길 대상과 이유를 반드시 적는다.
- `Dropped`: 더 이상 유효하지 않은 질문이다. 삭제 사유를 짧게 남기고 목록에서 제거한다.
- 처리 원칙 1: 질문만 남기지 말고 반드시 `상태`, `처리 방안`, `종료 조건`을 함께 적는다.
- 처리 원칙 2: 답이 나온 질문은 본문 반영 없이 단순 삭제하지 않는다. 반영 위치를 먼저 갱신한다.
- 처리 원칙 3: High 영향 질문은 `Deferred` 처리 후 처리 방안에 REQ 인계 추적 방식을 명시한다.

# 7. 초기 성공 기준
이 변경이 성공했다고 판단할 기준을 측정 가능하게 정의한다. 가능하면 데이터 출처까지 연결한다.

- S-1: 로컬 docker compose 환경에서 fresh DB 와 app runtime 이 일부 schema 를 먼저 만든 DB 시나리오별로 실행 명령, 기대 결과, 실패 조건이 포함된 검증 시나리오 매트릭스가 완성된다.
- S-2: Alembic 과 ensure_schema() 의 책임 경계, 위험 revision, 사전 점검 규칙이 REQ 로 인계 가능한 수준으로 정리된다.
- S-3: 운영자가 release 전 참고할 수 있는 DB 준비 또는 rollback 판단 기준이 문서 초안으로 정의된다.

## 측정 방식 및 데이터 출처
각 성공 기준을 어떻게 측정할지와 어떤 데이터나 문서를 근거로 쓸지 적는다.

- S-1 측정 방식: 시나리오별 명령 순서와 기대 산출물 표 작성 여부 확인 / 데이터 출처: README.md, app/cli/commands/health.py, app/db/migrations.py
- S-2 측정 방식: 충돌 지점과 ownership 경계가 파일 단위로 추적 가능한지 검토 / 데이터 출처: app/repositories/postgres.py, migrations/versions/*.py, docs/project-structure.md, docs/runtime-flows.md
- S-3 측정 방식: 운영 준비 체크리스트와 rollback 판단 기준의 초안 존재 여부 확인 / 데이터 출처: Discovery 본문, README.md, 후속 batch planning 입력

# 8. REQ로 넘기기 전 확인 체크
REQ 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.

- [x] 범위(In Scope/Out of Scope) 확정
	- 기준: 실DB 검증 대상 환경 범위는 로컬 docker compose 기반 DB로 확정되고, legacy support 는 제외 범위로 확정되어야 한다.
- [ ] 성공 지표의 측정 방식/데이터 출처 확정
	- 기준: 시나리오 매트릭스, command log, baseline 문서, README 중 어떤 문서가 근거가 되는지 합의돼야 한다.
	- REQ handoff 판정: 차단 사항 아님. 현재 문서의 `# 7. 초기 성공 기준`에 측정 방식과 데이터 출처 초안이 정리돼 있어 REQ 초안 작성은 가능하고, 세부 artifact 형식은 REQ와 batch planning에서 확정한다.
- [ ] High 영향 리스크 우선순위 및 해소 책임자 지정
	- 기준: R-1, R-2 의 해소 주체와 REQ 또는 batch 에서 검증할 방법이 지정돼야 한다.
	- REQ handoff 판정: 차단 사항 아님. 리스크 자체와 완화 방향은 확정돼 있으므로 REQ 초안 작성은 가능하고, 구체 owner 지정은 REQ 승인 또는 batch planning에서 확정한다.
- [x] 모든 오픈 질문(OQ) `Open` 상태 없음 확인
	- 기준: OQ 목록에 `Open` 상태 항목이 0개이거나, 잔여 항목 전부 `Deferred` 처리 완료
- [x] Freeze 확정 담당자(CONFIRMED_BY) 지정
	- 기준: Discovery 승인 또는 REQ handoff 를 확인할 담당자로 Justin 이 식별돼야 한다.

# 9. 파일 처리 결과
이 Discovery 문서 생성/갱신 결과와 참조 문서를 기록한다. 이후 추적과 리뷰 시 근거로 사용한다.

- 처리 결과: 생성
- 생성 경로: docs/discovery/dcy-001_20260430_real-db-migration-validation-and-operations-readiness.md
- 참조 문서:
	- README.md
	- app/cli/commands/health.py
	- app/db/migrations.py
	- docs/project-structure.md
	- docs/runtime-flows.md

# 10. 사용자 결정 필요 항목 요약
사용자나 승인자가 결정해야 하는 항목만 모아 정리한다. 결정, 확인, 데이터 요청을 구분해서 적는다.

## DECIDE
- 없음

## CONFIRM
- 로컬 docker compose 기반 DB에서 init-db, migrate-db, health-check, 최소 인증 또는 portfolio smoke flow 성공과 검증 로그 기록을 이번 Discovery의 release gate로 확정한다.

## DATA
- 없음

# 11. Discovery Freeze
REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.

## 섹션 참조
- 범위: [# 5. 요구사항 목록 > 범위 경계](#5-요구사항-목록)
- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)
- 인계 전 확인: [# 8. REQ로 넘기기 전 확인 체크](#8-req로-넘기기-전-확인-체크)
- 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약)

## Freeze 플래그
- Handoff Decision: 승인
- Handoff Rationale: 실DB 검증 범위, legacy DB 제외 범위, 승인자 Justin, release gate 기준이 정리되었고 Open 질문과 사용자 결정 항목이 해소됐다. 남은 체크 항목은 REQ drafting을 막지 않는 후속 확정 사항으로 분리했다.
- Ready for REQ Drafting: true
- Confirmed By: Justin
- Confirmed At (KST): 2026-04-30 22:56

# 12. 작성 가이드
템플릿 사용 시의 기본 규칙을 적는다. 실제 문서를 만들 때는 이 가이드를 기준으로 플레이스홀더를 치환한다.

- 이 파일은 템플릿이 아니라 실제 초안 문서다. 남은 플레이스홀더는 사용자 또는 승인자 확인이 필요한 항목만 유지한다.
- 필요 없는 항목은 삭제하고, 부족한 항목은 같은 형식으로 추가한다.
- Open Questions는 가정으로 대체하지 말고 그대로 유지한다.
- `대체됨`은 현재 Discovery가 더 이상 기준 문서가 아닐 때 대체 Discovery 경로를 기록하고, 해당 사항이 없으면 `없음`으로 둔다.
- `후속 Discovery 참조`는 범위를 이어받는 별도 Discovery가 생성된 경우 그 Discovery 경로를 기록하고, 없으면 `없음`으로 둔다.
- Discovery Freeze는 문서 하단에 반드시 유지한다.