portfolio-hub/docs/srs/Interface/req-035_health-response-db-enabled-field.md

REQ-035: GET /health 응답에 db_enabled 필드 추가

• Status: Implemented
• Type: Interface
• Priority: Medium
• Owner: Justin Ko

Intent

• 현재 HealthResponse 모델(app/api/health.py:17-21)이 status, service, version, checked_at 4필드만 노출하여 외부 health probe가 DB 사용 설정 상태를 직접 관찰할 수 없다.
• REL-001 verification 체크리스트의 "GET /health → HTTP 200 + db_enabled: true" 요구사항과 응답 모델 gap을 닫는다.
• 본 필드는 환경변수 PORTFOLIOHUB_DB_ENABLED 설정값을 노출하는 것이며 actual DB connectivity ping이 아님을 baseline 문서(docs/runtime-flows.md)에 명문화한다.

Requirement

• HealthResponse 모델에 db_enabled: bool 필드를 추가한다.
• healthcheck() 핸들러가 settings.db_enabled(환경변수 PORTFOLIOHUB_DB_ENABLED 설정값)를 db_enabled 필드에 채워서 응답한다.
• docs/runtime-flows.md에 "GET /health 응답의 db_enabled는 환경변수 설정값 노출이며 actual DB connectivity ping이 아니다. production-grade readiness probe는 별도 /readiness endpoint 분리로 후속 처리한다"는 의미 명문화 노트를 추가한다.
• docs/interface-contract.md에 /health 응답 schema의 db_enabled 필드 명세를 추가한다.

Acceptance Criteria

1. Given PORTFOLIOHUB_DB_ENABLED=true 환경, When GET /health 호출, Then HTTP 200 응답 본문에 "db_enabled": true 필드가 포함된다.
2. Given PORTFOLIOHUB_DB_ENABLED=false 환경, When GET /health 호출, Then HTTP 200 응답 본문에 "db_enabled": false 필드가 포함된다.
3. Given 응답 본문, When status, service, version, checked_at, db_enabled 5필드 확인, Then 모두 노출되고 기존 4필드 동작은 회귀 통과한다.
4. Given grep grep -n "db_enabled" docs/runtime-flows.md, When 실행, Then "설정값 노출, actual ping 아님" 의미 노트가 매치된다.
5. Given grep grep -n "/health.*db_enabled\|db_enabled.*health" docs/interface-contract.md, When 실행, Then /health 응답 schema에 db_enabled 필드 명세가 매치된다.

Impacted Area

• Docs:
  • docs/runtime-flows.md — /health probe flow 섹션에 "db_enabled는 설정값 노출, actual ping 아님" 의미 노트 추가 (baseline 문서 갱신)
  • docs/interface-contract.md — /health 응답 schema에 db_enabled: bool 필드 추가
• Modules:
  • app/api/health.py — HealthResponse에 db_enabled: bool 필드 추가 + healthcheck() 핸들러가 settings.db_enabled 채움
• Tests:
  • 신규 tests/test_app.py::test_health_exposes_db_enabled — AC-1 검증 (PORTFOLIOHUB_DB_ENABLED=true 환경)
  • (선택) 추가 케이스 — AC-2 검증 (PORTFOLIOHUB_DB_ENABLED=false 환경)

Notes

• 본 REQ는 dcy-005 FR-3 산출물. REL-001 verification gap을 닫는 정합화.
• db_enabled 값은 단순 설정값 노출이며 actual DB connectivity 보장이 아니다. production-grade readiness probe(SELECT 1 ping 등)는 본 REQ 범위 밖이며 별도 후속 Discovery + /readiness endpoint 분리로 처리.
• 본 REQ는 별도 REL-002로 분리 배포(dcy-005 OQ-3 결정, 2026-06-01). REL-001은 현 상태(체크리스트 db_enabled 미노출 [~] 부분 통과)로 배포 진행.
• Source: dcy-005 FR-3, rel-001 Feedback Handoff 후보.

Change Log

CHG-20260601-03

• Date: 2026-06-01
• Author: Justin Ko

Change Summary

• Status: Approved → Implemented

Intent

• BAT-015 confirm-batch-verification 완료(2026-06-05). AC-1~5 모두 PASSED. HealthResponse 확장 + handler + pytest 3건(test_healthcheck 갱신 + 신규 2건) + baseline 문서(docs/runtime-flows.md) 명문화 + interface-contract.md 정합 모두 evidence 확보.

Acceptance Criteria Delta

• No change

Impacted Area Delta

• No change

Delivery Trace Delta

• Batches:
  • BAT-015 (release-candidate)
• Releases:
  • REL-002 (예정)

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: implemented
• Follow-up Action: 미래 production-grade readiness probe(/readiness endpoint 분리)는 본 REQ 범위 밖, 별도 후속 Discovery 후보.

CHG-20260601-02

• Date: 2026-06-01
• Author: Justin Ko

Change Summary

• Status: Proposed → Approved

Intent

• 승인 게이트 통과: 필수 필드(Status/Type/Priority/Owner/Intent/Requirement/AC/Impacted Area/Change Log) 모두 충족, AC-1~5 구체성 확인 완료, blocker 없음. baseline 문서(docs/runtime-flows.md) 갱신 요구가 AC-4에 반영됨.

Acceptance Criteria Delta

• No change

Impacted Area Delta

• No change

Delivery Trace Delta

• Batches: none (미정)
• Releases: none (미정 — REL-002 분리 예정)

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: promote-to-approved
• Follow-up Action: batch 계획 편입 (BAT-015 후보)

CHG-20260601-01

• Date: 2026-06-01
• Author: Justin Ko

Change Summary

• 최초 생성 — dcy-005 confirm-discovery 후 draft-req 실행. dcy-005 FR-3 산출물.

Intent

• REL-001 verification checklist의 /health db_enabled gap을 닫고 응답 모델 확장 + baseline 문서(runtime-flows.md) 명문화.

Acceptance Criteria Delta

• Added:
  • AC-1~5 최초 작성

Impacted Area Delta

• Docs: docs/runtime-flows.md (baseline), docs/interface-contract.md — 최초 지정
• Modules: app/api/health.py — 최초 지정
• Tests: tests/test_app.py — 최초 지정

Delivery Trace Delta

• Batches: none (미정)
• Releases: none (미정 — REL-002 분리 예정)

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: confirm-req 후 batch 계획 편입

Validation Plan

• pytest TestClient로 AC-1~3 검증; grep으로 AC-4/AC-5 baseline 문서 명문화 검증