149 lines
3.7 KiB
Markdown
149 lines
3.7 KiB
Markdown
# 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"
|
||
```
|
||
|
||
这样后续复查时，意图会非常清晰。 |