From 9f4a88bef8412672c45c301631bcd6c44a2dd9ab Mon Sep 17 00:00:00 2001 From: Justin Ko Date: Thu, 30 Apr 2026 14:20:11 +0000 Subject: [PATCH] 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. --- ...ion-validation-and-operations-readiness.md | 224 ++++++++++++++++++ docs/discovery/index.md | 3 +- ...operations-runbook-and-baseline-updates.md | 119 ++++++++++ ...eq-002_alembic-runtime-schema-ownership.md | 118 +++++++++ .../req-001_local-db-validation-scenarios.md | 118 +++++++++ docs/srs/index.md | 11 +- 6 files changed, 590 insertions(+), 3 deletions(-) create mode 100644 docs/discovery/dcy-001_20260430_real-db-migration-validation-and-operations-readiness.md create mode 100644 docs/srs/Documentation/req-003_local-db-operations-runbook-and-baseline-updates.md create mode 100644 docs/srs/Migration/req-002_alembic-runtime-schema-ownership.md create mode 100644 docs/srs/Testing/req-001_local-db-validation-scenarios.md diff --git a/docs/discovery/dcy-001_20260430_real-db-migration-validation-and-operations-readiness.md b/docs/discovery/dcy-001_20260430_real-db-migration-validation-and-operations-readiness.md new file mode 100644 index 0000000..90c31f4 --- /dev/null +++ b/docs/discovery/dcy-001_20260430_real-db-migration-validation-and-operations-readiness.md @@ -0,0 +1,224 @@ +# 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는 문서 하단에 반드시 유지한다. \ No newline at end of file diff --git a/docs/discovery/index.md b/docs/discovery/index.md index 8c9f028..b6a60f7 100644 --- a/docs/discovery/index.md +++ b/docs/discovery/index.md @@ -5,4 +5,5 @@ ## Discovery 목록 | ID | 날짜 | 이슈명 | 문서 | 상태 | -|---|---|---|---|---| \ No newline at end of file +|---|---|---|---|---| +| dcy-001_20260430_real-db-migration-validation-and-operations-readiness | 20260430 | 실DB 마이그레이션 검증 및 운영 준비 | [Discovery](./dcy-001_20260430_real-db-migration-validation-and-operations-readiness.md) | confirmed | \ No newline at end of file diff --git a/docs/srs/Documentation/req-003_local-db-operations-runbook-and-baseline-updates.md b/docs/srs/Documentation/req-003_local-db-operations-runbook-and-baseline-updates.md new file mode 100644 index 0000000..25ad20e --- /dev/null +++ b/docs/srs/Documentation/req-003_local-db-operations-runbook-and-baseline-updates.md @@ -0,0 +1,119 @@ +# req-003: 로컬 DB 운영 runbook 및 baseline 문서 갱신 + +- Status: Approved +- Type: Documentation +- Priority: Medium +- Owner: repository-maintainers + +## Intent +- 이 요구사항은 로컬 docker compose 기반 DB 검증 결과를 운영자가 반복 사용할 수 있는 runbook과 baseline 문서로 정리하기 위한 문서화 backlog를 정의한다. +- README, docs/runtime-flows.md, docs/project-structure.md에 로컬 DB 준비 절차, release gate 기준, rollback 또는 재시도 판단 기준을 반영하는 것이 목표다. + +## Requirement +- 프로젝트는 로컬 docker compose 기반 DB 검증 범위를 반영해 README, docs/runtime-flows.md, docs/project-structure.md를 갱신해야 하며, init-db와 migrate-db 실행 흐름, release gate 증거, rollback 또는 재시도 판단 기준을 운영자가 추적 가능한 runbook 형태로 정리해야 한다. + +## Acceptance Criteria +1. Given 로컬 DB validation 범위가 확정되어 있을 때, When README를 갱신하면, Then docker compose 기반 준비 절차, init-db와 migrate-db 실행 순서, health-check 및 smoke flow 검증 기준이 포함되어 있어야 한다. +2. Given Alembic와 runtime ownership 경계가 정리될 때, When docs/project-structure.md와 docs/runtime-flows.md를 갱신하면, Then 구조 제약과 실행 흐름 제약이 baseline 문서에 반영되어 있어야 한다. +3. Given 이번 Discovery의 release gate가 로컬 DB validation 기준으로 확정되어 있을 때, When 운영 runbook을 작성하면, Then rollback 또는 재시도 판단 기준과 남겨야 할 검증 로그가 문서에 명시되어 있어야 한다. + +## Impacted Area +- Docs: README.md, docs/project-structure.md, docs/runtime-flows.md, docs/discovery/dcy-001_20260430_real-db-migration-validation-and-operations-readiness.md +- Modules: app/cli/commands/health.py, app/db/migrations.py, app/repositories/postgres.py +- Tests: 문서 기반 수동 검증 체크리스트와 release gate evidence review 절차 + +## Notes +- 이 요구사항은 dcy-001의 FR-3 일부, FR-4, NFR-3, S-3을 구현 가능한 Documentation 단위로 정규화한 것이다. +- baseline 문서 전체를 복제하지 않고, 로컬 DB 검증과 직접 관련된 구조 제약과 흐름 제약만 업데이트 대상으로 삼는다. +- 성공 지표의 세부 artifact 위치는 REQ 승인 또는 batch planning에서 확정할 수 있다. + +## Change Log + +### CHG-20260430-02 +- Date: 2026-04-30 +- Author: GitHub Copilot + +#### Change Summary +- confirm-req 승인 게이트를 통과해 이 REQ를 Approved로 전환했다. + +#### Intent +- dcy-001의 delivery input으로 사용할 수 있는 확정 requirement로 승격하기 위해 상태를 변경했다. + +#### Acceptance Criteria Delta +- Added: + - none +- Updated: + - none +- Removed: + - none + +#### Impacted Area Delta +- Docs: + - docs/srs/index.md +- Modules: + - none +- Tests: + - none + +#### Delivery Trace Delta +- Batches: + - none +- Releases: + - none + +#### Revalidation Impact +- Reverification Needed: no +- Existing Implementation Invalidated: no +- Status Recommendation: approved +- Follow-up Action: suggest-batch-reqs 또는 draft-batch 단계에서 REQ-003의 runbook 산출물 범위를 delivery scope로 연결한다. + +#### Validation Plan +- REQ 본문 필수 섹션, Acceptance Criteria 구체성, docs/srs/index.md 상태 동기화를 확인한다. + +### CHG-20260430-01 +- Date: 2026-04-30 +- Author: GitHub Copilot + +#### Change Summary +- dcy-001에서 로컬 DB 운영 runbook 및 baseline 문서 갱신 요구사항을 신규 Proposed REQ로 생성했다. + +#### Intent +- 운영 준비 산출물과 baseline 문서 갱신 요구를 독립 Documentation backlog로 관리하기 위해 생성했다. + +#### Acceptance Criteria Delta +- Added: + - README 로컬 DB 검증 절차 갱신 기준 정의 + - docs/project-structure.md와 docs/runtime-flows.md baseline 갱신 기준 정의 + - rollback 또는 재시도 판단 기준과 로그 수집 기준 정의 +- Updated: + - none +- Removed: + - none + +#### Impacted Area Delta +- Docs: + - README.md + - docs/project-structure.md + - docs/runtime-flows.md + - docs/discovery/dcy-001_20260430_real-db-migration-validation-and-operations-readiness.md +- Modules: + - app/cli/commands/health.py + - app/db/migrations.py + - app/repositories/postgres.py +- Tests: + - 문서 기반 수동 검증 체크리스트와 release gate evidence review 절차 + +#### Delivery Trace Delta +- Batches: + - none +- Releases: + - none + +#### Revalidation Impact +- Reverification Needed: no +- Existing Implementation Invalidated: no +- Status Recommendation: keep-current +- Follow-up Action: confirm-req 단계에서 baseline 문서 갱신 범위와 runbook 산출물 위치를 검토하고 승인한다. + +#### Validation Plan +- confirm-req 전까지 Acceptance Criteria가 dcy-001의 FR-3 일부, FR-4, NFR-3, S-3와 일치하는지 검토하고, 이후 batch 단계에서 README 및 baseline 문서 갱신안을 작성한다. \ No newline at end of file diff --git a/docs/srs/Migration/req-002_alembic-runtime-schema-ownership.md b/docs/srs/Migration/req-002_alembic-runtime-schema-ownership.md new file mode 100644 index 0000000..b308868 --- /dev/null +++ b/docs/srs/Migration/req-002_alembic-runtime-schema-ownership.md @@ -0,0 +1,118 @@ +# req-002: Alembic와 runtime schema ownership 경계 정리 + +- Status: Approved +- Type: Migration +- Priority: High +- Owner: repository-maintainers + +## Intent +- 이 요구사항은 Alembic migration 경로와 PostgresPortfolioRepository.ensure_schema() 경로가 같은 schema 객체를 다룰 때 발생할 수 있는 drift와 재실행 실패를 줄이기 위한 경계 규칙을 정의한다. +- 로컬 docker compose 환경에서 fresh DB와 runtime-precreated schema 상태를 기준으로 허용 순서, 사전 점검, 보정 규칙을 문서화하는 것이 목표다. + +## Requirement +- 프로젝트는 로컬 docker compose 기반 DB 환경에서 Alembic migration과 runtime schema bootstrap이 다루는 테이블과 인덱스의 ownership 경계를 식별해야 하며, migrate-db 실행 시 허용되는 순서, 충돌 가능 지점, 사전 점검 규칙, 보정 원칙을 명시해야 한다. + +## Acceptance Criteria +1. Given app/repositories/postgres.py와 migrations/versions/ 아래 현재 revision들이 있을 때, When schema ownership 분석을 수행하면, Then Alembic과 runtime ensure_schema()가 다루는 주요 객체와 충돌 가능 지점이 식별되어 있어야 한다. +2. Given 로컬 docker compose 기반 fresh DB와 app runtime이 일부 schema를 먼저 만든 DB 시나리오가 있을 때, When migrate-db 실행 규칙을 정의하면, Then 허용 순서, 금지 순서, 필요한 사전 점검과 보정 규칙이 문서로 정리되어 있어야 한다. +3. Given 코드 안에 legacy schema stamp 분기가 남아 있을 때, When migration 경계 문서를 작성하면, Then 이번 REQ와 관련 batch 범위에서 legacy DB 지원이 제외된다는 점이 명시되어 있어야 한다. + +## Impacted Area +- Docs: docs/project-structure.md, docs/runtime-flows.md, docs/data-model.md +- Modules: app/repositories/postgres.py, app/db/migrations.py, migrations/versions/*.py +- Tests: 로컬 schema ownership 검토 체크리스트 또는 migrate-db 충돌 시나리오 검증 절차 + +## Notes +- 이 요구사항은 dcy-001의 FR-2, FR-3 일부, S-2, R-1, R-2를 구현 가능한 Migration 단위로 정규화한 것이다. +- legacy DB support와 legacy stamp 경로 검증은 Discovery 범위에서 이미 제외되었으므로, 이 REQ는 local runtime bootstrap 흔적과 Alembic의 상호작용에 집중한다. +- 문서화만으로 해결되지 않는 ownership 충돌이 발견되면 후속 batch에서 코드 수정이 필요할 수 있다. + +## Change Log + +### CHG-20260430-02 +- Date: 2026-04-30 +- Author: GitHub Copilot + +#### Change Summary +- confirm-req 승인 게이트를 통과해 이 REQ를 Approved로 전환했다. + +#### Intent +- dcy-001의 delivery input으로 사용할 수 있는 확정 requirement로 승격하기 위해 상태를 변경했다. + +#### Acceptance Criteria Delta +- Added: + - none +- Updated: + - none +- Removed: + - none + +#### Impacted Area Delta +- Docs: + - docs/srs/index.md +- Modules: + - none +- Tests: + - none + +#### Delivery Trace Delta +- Batches: + - none +- Releases: + - none + +#### Revalidation Impact +- Reverification Needed: no +- Existing Implementation Invalidated: no +- Status Recommendation: approved +- Follow-up Action: suggest-batch-reqs 또는 draft-batch 단계에서 REQ-002의 ownership 문서를 delivery scope로 연결한다. + +#### Validation Plan +- REQ 본문 필수 섹션, Acceptance Criteria 구체성, docs/srs/index.md 상태 동기화를 확인한다. + +### CHG-20260430-01 +- Date: 2026-04-30 +- Author: GitHub Copilot + +#### Change Summary +- dcy-001에서 Alembic와 runtime schema ownership 경계 요구사항을 신규 Proposed REQ로 생성했다. + +#### Intent +- migrate-db와 runtime bootstrap의 경계가 불분명해 생길 수 있는 drift와 재실행 실패를 독립 Migration backlog로 관리하기 위해 생성했다. + +#### Acceptance Criteria Delta +- Added: + - Alembic과 runtime ensure_schema() ownership 분석 기준 정의 + - local runtime-precreated schema 시나리오용 허용 순서와 보정 규칙 정의 + - legacy DB 비지원 범위 명시 +- Updated: + - none +- Removed: + - none + +#### Impacted Area Delta +- Docs: + - docs/project-structure.md + - docs/runtime-flows.md + - docs/data-model.md +- Modules: + - app/repositories/postgres.py + - app/db/migrations.py + - migrations/versions/*.py +- Tests: + - migrate-db 충돌 시나리오 검토 체크리스트 또는 동등한 검증 절차 + +#### Delivery Trace Delta +- Batches: + - none +- Releases: + - none + +#### Revalidation Impact +- Reverification Needed: no +- Existing Implementation Invalidated: no +- Status Recommendation: keep-current +- Follow-up Action: confirm-req 단계에서 ownership 경계의 대상 객체와 범위 제외 항목을 검토하고 승인한다. + +#### Validation Plan +- confirm-req 전까지 Acceptance Criteria가 dcy-001의 FR-2, FR-3 일부, S-2와 일치하는지 검토하고, 이후 batch 단계에서 실제 객체 목록과 허용 순서 문서를 작성한다. \ No newline at end of file diff --git a/docs/srs/Testing/req-001_local-db-validation-scenarios.md b/docs/srs/Testing/req-001_local-db-validation-scenarios.md new file mode 100644 index 0000000..fb739bc --- /dev/null +++ b/docs/srs/Testing/req-001_local-db-validation-scenarios.md @@ -0,0 +1,118 @@ +# req-001: 로컬 DB 초기화 및 마이그레이션 검증 시나리오 정의 + +- Status: Approved +- Type: Testing +- Priority: High +- Owner: repository-maintainers + +## Intent +- 이 요구사항은 로컬 docker compose 기반 PostgreSQL 또는 TimescaleDB 환경에서 init-db, migrate-db, health-check, 최소 smoke flow를 반복 가능하게 검증하기 위한 기준선을 정의한다. +- 운영자와 유지보수 담당자가 같은 명령 순서와 같은 증거 형식으로 DB 준비 결과를 비교할 수 있도록 검증 절차를 명시하는 것이 목표다. + +## Requirement +- 프로젝트는 로컬 docker compose 기반 DB 환경에 대해 fresh DB 시나리오와 app runtime이 일부 schema를 먼저 만든 시나리오를 포함한 검증 매트릭스를 정의해야 하며, init-db, migrate-db, health-check, 최소 인증 또는 portfolio smoke flow의 실행 순서, 기대 결과, 실패 조건, 증거 수집 방식을 함께 제공해야 한다. + +## Acceptance Criteria +1. Given 로컬 docker compose 기반 DB와 필요한 환경 변수가 준비되어 있을 때, When 운영자가 init-db, health-check, 최소 인증 또는 portfolio smoke flow를 실행하면, Then 명령 순서, 기대 출력, pass or fail 기준, 남겨야 할 로그가 문서로 정의되어 있어야 한다. +2. Given fresh DB와 app runtime이 일부 schema를 먼저 만든 DB 시나리오가 있을 때, When 운영자가 migrate-db를 실행하면, Then 각 시나리오별 기대 결과와 실패 조건, 확인해야 할 증거가 구분되어 문서화되어 있어야 한다. +3. Given 동일한 로컬 검증 절차를 반복 실행할 때, When 운영자가 같은 명령 세트를 다시 실행하면, Then 결과 비교가 가능하도록 출력 형식과 로그 수집 위치가 일관되게 정의되어 있어야 한다. + +## Impacted Area +- Docs: README.md, docs/runtime-flows.md, docs/discovery/dcy-001_20260430_real-db-migration-validation-and-operations-readiness.md +- Modules: docker-compose.local-test.yml, app/cli/commands/health.py, app/db/migrations.py +- Tests: 로컬 docker compose 기반 수동 검증 체크리스트 또는 동등한 smoke validation 절차 + +## Notes +- 이 요구사항은 dcy-001의 FR-1, NFR-1, NFR-2, S-1을 주로 구현 가능한 backlog로 정규화한 것이다. +- shared dev DB, staging, production-like 환경 검증은 이번 요구사항 범위에 포함하지 않는다. +- 성공 지표의 세부 artifact 형식은 REQ 승인 또는 batch planning 단계에서 확정할 수 있다. + +## Change Log + +### CHG-20260430-02 +- Date: 2026-04-30 +- Author: GitHub Copilot + +#### Change Summary +- confirm-req 승인 게이트를 통과해 이 REQ를 Approved로 전환했다. + +#### Intent +- dcy-001의 delivery input으로 사용할 수 있는 확정 requirement로 승격하기 위해 상태를 변경했다. + +#### Acceptance Criteria Delta +- Added: + - none +- Updated: + - none +- Removed: + - none + +#### Impacted Area Delta +- Docs: + - docs/srs/index.md +- Modules: + - none +- Tests: + - none + +#### Delivery Trace Delta +- Batches: + - none +- Releases: + - none + +#### Revalidation Impact +- Reverification Needed: no +- Existing Implementation Invalidated: no +- Status Recommendation: approved +- Follow-up Action: suggest-batch-reqs 또는 draft-batch 단계에서 REQ-001의 검증 절차를 delivery scope로 연결한다. + +#### Validation Plan +- REQ 본문 필수 섹션, Acceptance Criteria 구체성, docs/srs/index.md 상태 동기화를 확인한다. + +### CHG-20260430-01 +- Date: 2026-04-30 +- Author: GitHub Copilot + +#### Change Summary +- dcy-001에서 로컬 DB 검증 시나리오 요구사항을 신규 Proposed REQ로 생성했다. + +#### Intent +- 로컬 DB 준비와 smoke validation 절차를 독립 구현 및 독립 검증 가능한 Testing 단위로 분리하기 위해 생성했다. + +#### Acceptance Criteria Delta +- Added: + - 로컬 docker compose 기반 init-db, health-check, smoke flow의 검증 기준 정의 + - fresh DB와 runtime-precreated schema 시나리오별 migrate-db 검증 기준 정의 + - 반복 실행 가능한 증거 수집 형식 정의 +- Updated: + - none +- Removed: + - none + +#### Impacted Area Delta +- Docs: + - README.md + - docs/runtime-flows.md + - docs/discovery/dcy-001_20260430_real-db-migration-validation-and-operations-readiness.md +- Modules: + - docker-compose.local-test.yml + - app/cli/commands/health.py + - app/db/migrations.py +- Tests: + - 로컬 DB 수동 검증 체크리스트 또는 동등한 smoke validation 절차 + +#### Delivery Trace Delta +- Batches: + - none +- Releases: + - none + +#### Revalidation Impact +- Reverification Needed: no +- Existing Implementation Invalidated: no +- Status Recommendation: keep-current +- Follow-up Action: confirm-req 단계에서 검증 매트릭스 초안의 범위와 증거 형식을 승인한다. + +#### Validation Plan +- confirm-req 전까지 Acceptance Criteria가 dcy-001의 FR-1 및 S-1과 일치하는지 검토하고, 이후 batch 단계에서 실제 검증 절차와 로그 수집 artifact를 작성한다. \ No newline at end of file diff --git a/docs/srs/index.md b/docs/srs/index.md index 67c789c..8a741bf 100644 --- a/docs/srs/index.md +++ b/docs/srs/index.md @@ -74,14 +74,21 @@ ## Next Requirement ID -- Current: `REQ-001` +- Current: `REQ-004` - Rule: `Requirement Register`에 있는 가장 큰 REQ 번호보다 정확히 1 커야 한다. ## Requirement Register | ID | Title | Type | Status | Priority | Owner | Link | | --- | --- | --- | --- | --- | --- | --- | +| REQ-001 | 로컬 DB 초기화 및 마이그레이션 검증 시나리오 정의 | Testing | Approved | High | repository-maintainers | [REQ-001](./Testing/req-001_local-db-validation-scenarios.md) | +| REQ-002 | Alembic와 runtime schema ownership 경계 정리 | Migration | Approved | High | repository-maintainers | [REQ-002](./Migration/req-002_alembic-runtime-schema-ownership.md) | +| REQ-003 | 로컬 DB 운영 runbook 및 baseline 문서 갱신 | Documentation | Approved | Medium | repository-maintainers | [REQ-003](./Documentation/req-003_local-db-operations-runbook-and-baseline-updates.md) | ## Recent Change Log Summary -- 없음 \ No newline at end of file +- 2026-04-30: REQ-003 Approved 전환 — 로컬 DB 운영 runbook 및 baseline 문서 갱신 +- 2026-04-30: REQ-002 Approved 전환 — Alembic와 runtime schema ownership 경계 정리 +- 2026-04-30: REQ-001 Approved 전환 — 로컬 DB 초기화 및 마이그레이션 검증 시나리오 정의 +- 2026-04-30: REQ-003 Proposed 생성 — 로컬 DB 운영 runbook 및 baseline 문서 갱신 (source Discovery: dcy-001) +- 2026-04-30: REQ-002 Proposed 생성 — Alembic와 runtime schema ownership 경계 정리 (source Discovery: dcy-001) \ No newline at end of file