diff --git a/prd-app-factory-config-unification-batch2-fix-health.md b/prd-app-factory-config-unification-batch2-fix-health.md new file mode 100644 index 0000000..2ecb868 --- /dev/null +++ b/prd-app-factory-config-unification-batch2-fix-health.md @@ -0,0 +1,149 @@ +# PRD: App Factory + Config 统一重构(PR1 Batch 2 收尾修复) + +## 背景 + +PR1 Batch 2 已完成大部分 shared app/config 接入工作,当前远端代码提交为: + +- `6d94b08` — `Refactor all apps to use shared config and app factory` + +本轮复查发现: + +- shared/regression 相关测试可通过 +- 五个服务已基本接入 shared config/app factory +- 但仍存在一个**明确且已被源码证实的问题**: + +`home/src/routes/pages.py` 中的 `/health` 路由**仍然保留**,与 Batch 2 目标不一致。 + +这意味着 `/health` 的统一归口尚未真正完成。 + +--- + +## 问题定义 + +### 现状 +根据当前代码状态: + +`home/src/routes/pages.py` 仍包含: + +```python +@router.get("/health") +async def health_check() -> dict: + from shared.health import build_health_response + return build_health_response("home.ephron.ren") +``` + +而 Batch 2 的目标是: +- `/health` 由 shared app factory 统一提供 +- 不在服务自己的 pages route 中重复定义 + +### 为什么这是问题 +即使当前没有立刻引发测试失败,它仍然会造成以下风险: + +1. **所有权不清晰** + `health` 到底由 factory 管,还是由 `home/pages.py` 管,不再明确。 + +2. **行为漂移风险** + 后续若 app factory 的 `/health` 响应结构升级,而 `home/pages.py` 保持旧实现,`home` 会成为唯一例外。 + +3. **违背 PR1 Batch 2 的设计目标** + 这次重构的目标之一就是把通用 app 端点统一到 shared app factory。 + +4. **后续测试契约难统一** + 当测试开始断言“所有服务 health 由 shared app factory 提供”时,`home` 会成为特例。 + +--- + +## 修复目标 + +完成这次收尾修复后,应满足: + +1. `home/src/routes/pages.py` 不再定义 `/health` +2. `home` 的 `/health` 只由 `shared.app_factory.create_service_app(...)` 提供 +3. `home` 的 health 响应结构与其他服务统一 +4. 不影响: + - `/` + - `/logout` + - `/robots.txt` + 等 `home/pages.py` 中其他路由 + +--- + +## 最小修复方案 + +### 修改文件 +- `home/src/routes/pages.py` + +### 具体修改 +删除以下代码块: + +```python +@router.get("/health") +async def health_check() -> dict: + """健康检查端点""" + from shared.health import build_health_response + return build_health_response("home.ephron.ren") +``` + +### 不要做的事 +- 不要在这次修复里顺手改 `home/src/main.py` +- 不要顺手调整 app factory +- 不要顺手改 `robots.txt` / `logout` / 首页逻辑 +- 不要扩大到 import 结构清理 + +本次修复应该是**最小闭环**:只解决 `/health` 重复归口问题。 + +--- + +## 验证要求 + +### 一、回归测试 +至少执行: + +```bash +python -m pytest tests/test_security_hardening.py tests/test_frontend_backend_reuse_contract.py -q +``` + +预期: +- 测试继续通过 + +### 二、行为验证 +如可本地启动,额外验证: + +```bash +python main.py --reload +``` + +手动检查: +- `home` 服务仍能正常启动 +- `GET /health` 仍返回正常 health 响应 +- `GET /`、`GET /robots.txt`、`GET /logout` 不受影响 + +### 三、契约确认 +修复后,应能明确说: + +> `home` 的 `/health` 已与其他服务一样,由 shared app factory 统一提供。 + +--- + +## 完成定义 + +本收尾修复完成后,必须满足: + +- [ ] `home/src/routes/pages.py` 中已删除 `/health` +- [ ] `home` 的 `/health` 由 shared app factory 统一提供 +- [ ] 回归测试通过 +- [ ] 不引入其他额外结构性改动 + +--- + +## 备注 + +这不是一个大 PR,而是 **PR1 Batch 2 的收尾修正**。 + +建议提交信息: + +```bash +git commit -m "fix(home): remove duplicate health route after app factory migration" +``` + +这样后续复查时,意图会非常清晰。 \ No newline at end of file