trex/portfolio-hub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9f4a88bef8412672c45c301631bcd6c44a2dd9ab
portfolio-hub/docs/discovery/dcy-001_20260430_real-db-migration-validation-and-operations-readiness.md
T
genichin 9f4a88bef8 docs(dcy/srs): add DCY-001 discovery and REQ-001/002/003 requirements 
Introduces discovery for real DB migration validation and operations readiness:
- dcy-001_20260430_real-db-migration-validation-and-operations-readiness.md
- REQ-001: Local DB validation scenarios (Testing)
- REQ-002: Alembic runtime schema ownership (Migration)
- REQ-003: Local DB operations runbook and baseline updates (Documentation)

Updates discovery and SRS indexes to include new documents.
2026-04-30 14:20:11 +00:00

18 KiB
Raw Blame History

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 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.

  • 범위(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에서 확정한다.
  • 모든 오픈 질문(OQ) Open 상태 없음 확인
    • 기준: OQ 목록에 Open 상태 항목이 0개이거나, 잔여 항목 전부 Deferred 처리 완료
  • 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 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.

섹션 참조

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는 문서 하단에 반드시 유지한다.
Reference in New Issue View Git Blame Copy Permalink