feat: apply rel-001 feedback cleanup

2026-06-05 13:57:46 +09:00
parent 84de34c301
commit 2470c0a00c
28 changed files with 992 additions and 32 deletions
@@ -0,0 +1,126 @@
+# REQ-034: LoginRequest 추가 필드 거부 enforcement (session no_expiry 정책 정합)
+
+- Status: Implemented
+- Type: Interface
+- Priority: Medium
+- Owner: Justin Ko
+
+## Intent
+- REQ-021 정책 본문이 "session에서 `no_expiry` 시도 → HTTP 422 또는 ValueError 거부"로 명시하지만, 현재 `LoginRequest` 스키마([app/schemas/auth.py:13-23](../../app/schemas/auth.py#L13-L23))가 Pydantic 기본(`extra="ignore"`)이라 외부에서 `no_expiry: true`를 추가해 보내도 silently 무시된다.
+- `LoginRequest`에 `extra="forbid"` 적용으로 정책 명문과 코드 동작을 일치시켜 audit 명확성을 확보한다.
+
+## Requirement
+- `app/schemas/auth.py:LoginRequest`에 `model_config = ConfigDict(extra="forbid")`를 적용한다.
+- 외부 client가 LoginRequest에 정의되지 않은 필드(`no_expiry` 포함, 기타 임의 필드)를 전송하면 FastAPI/Pydantic이 HTTP 422로 거부한다.
+- `AuthService.login`([app/services/auth_service.py:47-65](../../app/services/auth_service.py#L47-L65))의 동작은 변경하지 않는다(정책 enforcement는 스키마 단계에서 처리).
+- 기존 정상 client(username/password 2필드만 전송)는 영향 없음을 회귀 테스트로 확인한다.
+
+## Acceptance Criteria
+1. Given valid username/password, When `POST /auth/login` body `{"username": "...", "password": "..."}` 호출, Then HTTP 200 + 정상 TokenResponse 반환(기존 동작 회귀).
+2. Given valid username/password + 추가 필드, When `POST /auth/login` body `{"username": "...", "password": "...", "no_expiry": true}` 호출, Then HTTP 422 응답 + Pydantic validation error detail에 `extra_forbidden` 표기.
+3. Given valid username/password + 임의 추가 필드, When `POST /auth/login` body `{"username": "...", "password": "...", "arbitrary_field": "x"}` 호출, Then HTTP 422 응답 (extra="forbid" 일반 동작 회귀).
+4. Given codebase grep `grep -n "extra.*forbid" app/schemas/auth.py`, When 본 REQ 구현 후, Then `LoginRequest` 정의 부근에 매치된다.
+5. Given 본 REQ 구현 후 전체 pytest 회귀, When 실행, Then 기존 통과 케이스 모두 유지.
+
+## Impacted Area
+- Docs:
+  - (선택) `docs/srs/Documentation/req-021_token-expiry-and-rotation-policy.md` Notes에 "AC-4 enforcement는 REQ-034로 분리 구현" 추가 (cross-reference)
+- Modules:
+  - `app/schemas/auth.py` — `LoginRequest.model_config = ConfigDict(extra="forbid")` 추가
+- Tests:
+  - 신규 `tests/test_auth.py::test_login_rejects_no_expiry_extra_field` — AC-2 검증
+  - 신규 `tests/test_auth.py::test_login_rejects_arbitrary_extra_field` — AC-3 검증 (또는 AC-2와 단일 케이스로 합침)
+
+## Notes
+- 본 REQ는 dcy-005 FR-2 산출물. REQ-021 follow-up.
+- `extra="forbid"`는 `LoginRequest` 전체에 추가 필드 거부 효과. 기존 정상 client는 username/password만 전송하므로 영향 없음. 본 워크스페이스는 개발용이라 외부 monitoring 영향 무.
+- 본 REQ는 별도 REL-002로 분리 배포(dcy-005 OQ-3 결정, 2026-06-01).
+- Source: dcy-005 FR-2, REQ-021 AC-5 follow-up.
+
+## 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. `LoginRequest` extra="forbid" 적용 + pytest 422 회귀 2건 신규 + 로컬 smoke 422 + extra_forbidden 확인.
+
+#### 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: none
+
+### 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 없음.
+
+#### 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-2 산출물.
+
+#### Intent
+- REQ-021 정책 본문과 LoginRequest 코드 동작 일치 (session no_expiry 거부 enforcement).
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~5 최초 작성
+
+#### Impacted Area Delta
+- Docs: (선택) docs/srs/Documentation/req-021_*.md cross-reference — 최초 지정
+- Modules: app/schemas/auth.py — 최초 지정
+- Tests: tests/test_auth.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 검증
@@ -0,0 +1,128 @@
+# REQ-035: GET /health 응답에 db_enabled 필드 추가
+
+- Status: Implemented
+- Type: Interface
+- Priority: Medium
+- Owner: Justin Ko
+
+## Intent
+- 현재 `HealthResponse` 모델([app/api/health.py:17-21](../../app/api/health.py#L17-L21))이 `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 문서 명문화 검증