538 lines
16 KiB
Markdown
538 lines
16 KiB
Markdown
# PRD — App Factory / Config Unification 完整优化清单
|
||
|
||
## 背景
|
||
|
||
`ephron.ren` 当前已经完成了一轮 app factory / config shared 化重构，远端相关主线提交为：
|
||
|
||
- `14484ca` — Add shared modules: app factory, config base, error handlers with tests
|
||
- `6d94b08` — Refactor all apps to use shared config and app factory
|
||
- `378a4e5` — Update home pages route and add test templates
|
||
|
||
现状不是“完全没做”，而是：
|
||
|
||
- shared 基础设施已经建立
|
||
- 五个服务已经基本接入 shared app/config 骨架
|
||
- 但整体状态仍停留在“完成了第一轮统一”，还没达到“结构稳定、依赖完整、验证闭环、后续不易漂移”的完成态
|
||
|
||
因此这份 PRD 不再按 Batch 1 / Batch 2 / follow-up 拆分，而是直接给出 **从当前状态到完成态的完整优化清单**。
|
||
|
||
这份文档的目标是：开发只看这一份，就知道哪些必须改、哪些建议改、哪些不要顺手乱改，以及最后怎么验收。
|
||
|
||
---
|
||
|
||
## 总体结论
|
||
|
||
当前重构方向是对的，但还差四类关键补完：
|
||
|
||
1. **依赖契约没补齐**
|
||
- `shared.app_factory` 已把 `slowapi` 变成公共硬依赖
|
||
- 但测试/安装链路没有完全同步，导致服务入口级测试会直接 import 失败
|
||
|
||
2. **导入边界不稳定**
|
||
- `main.py` / `config.py` 乃至 route/service/test 里仍保留大量 `sys.path.insert(...)`
|
||
- 说明 shared 化了逻辑，但没收住模块边界
|
||
|
||
3. **admin 路由守卫仍是服务内私有实现**
|
||
- `home` 已有实际 guard
|
||
- 但 guard 骨架没 shared 化，未来其他服务继续扩展时很容易复制漂移
|
||
|
||
4. **验证层只证明了 shared 能跑，没充分证明服务入口能跑**
|
||
- 当前 shared tests 通过，不代表五个服务入口都可稳定导入/装配
|
||
|
||
---
|
||
|
||
## 优化目标
|
||
|
||
完成本清单后，应该达到以下状态：
|
||
|
||
1. 五个服务的 app 创建与 config 读取，已经统一且可维护
|
||
2. shared app factory 的依赖在开发、测试、部署三条链路中一致成立
|
||
3. Batch 2 涉及的 10 个 `main.py/config.py` 文件不再各自复制路径注入模板
|
||
4. `home` 的 admin 守卫公共骨架进入 shared 层，后续可供其他服务复用
|
||
5. `/health` 只由 shared app factory 统一归口
|
||
6. 测试不仅覆盖 shared 合同，还覆盖服务入口装配合同
|
||
7. 改完后可以明确说：这轮统一已经从“代码抽取”升级为“工程约束已建立”
|
||
|
||
---
|
||
|
||
## 非目标
|
||
|
||
本轮不要做以下事情：
|
||
|
||
- 不重写整站认证体系
|
||
- 不全量重构所有 route/service/test 的导入结构
|
||
- 不一次性把所有 auth/token 逻辑全部抽进 shared
|
||
- 不改业务权限模型
|
||
- 不改 service API 设计
|
||
- 不迁移仓库目录结构
|
||
- 不强制一步到位改成完整 package 化（如全面 pyproject/installable layout）
|
||
- 不顺手做与本次重构无关的业务修复
|
||
|
||
原则很简单：**只修 app/config 统一后暴露出来的结构性缺口，不把这轮工作膨胀成全仓重构。**
|
||
|
||
---
|
||
|
||
## 一、必须修改（P0 / P1）
|
||
|
||
## P0-1. 补齐 `slowapi` 依赖契约
|
||
|
||
### 问题
|
||
|
||
`shared.app_factory.py` 已直接依赖：
|
||
|
||
- `slowapi._rate_limit_exceeded_handler`
|
||
- `slowapi.errors.RateLimitExceeded`
|
||
|
||
这意味着：
|
||
|
||
- 只要服务入口用 shared factory
|
||
- `slowapi` 就不再是“某服务可选依赖”
|
||
- 而是整个服务启动路径的公共硬依赖
|
||
|
||
复审中的实际验证结果也说明了这个问题：
|
||
|
||
```bash
|
||
python -m pytest tests/test_security_hardening.py tests/test_frontend_backend_reuse_contract.py -q
|
||
```
|
||
|
||
通过；但执行：
|
||
|
||
```bash
|
||
python -m pytest auth/tests/test_security_hardening.py auth/tests/test_login_redirect_flow.py -q
|
||
```
|
||
|
||
在 collection 阶段报：
|
||
|
||
```text
|
||
ModuleNotFoundError: No module named 'slowapi'
|
||
```
|
||
|
||
### 必须改什么
|
||
|
||
1. 检查项目实际依赖入口
|
||
- 根依赖文件
|
||
- 测试依赖入口
|
||
- 部署安装入口
|
||
2. 保证 `slowapi` 在这三条链路里都被安装
|
||
3. 如果存在多个 requirements 文件，必须统一，不允许某条链路漏掉
|
||
4. 若 CI 有单独安装脚本，也必须同步更新
|
||
|
||
### 验收标准
|
||
|
||
以下命令在标准开发环境中必须通过：
|
||
|
||
```bash
|
||
python -m pytest tests/test_security_hardening.py tests/test_frontend_backend_reuse_contract.py -q
|
||
python -m pytest auth/tests/test_security_hardening.py auth/tests/test_login_redirect_flow.py -q
|
||
```
|
||
|
||
且不允许再出现：
|
||
|
||
```text
|
||
ModuleNotFoundError: slowapi
|
||
```
|
||
|
||
---
|
||
|
||
## P0-2. `/health` 必须只保留 shared app factory 单一归口
|
||
|
||
### 问题
|
||
|
||
app factory 统一后的设计目标之一，就是 `/health` 由 shared factory 统一注册。
|
||
|
||
这件事必须做到“单一所有权”，否则后续一旦 health 响应结构升级，很容易出现某个服务还是旧实现。
|
||
|
||
当前重点确认点：
|
||
- `home/src/routes/pages.py` 不应再重复定义 `/health`
|
||
- 其他服务也不应在页面路由层残留重复 health endpoint
|
||
|
||
### 必须改什么
|
||
|
||
1. 全仓检查 `/health` 定义位置
|
||
2. 保留 shared app factory 中的统一实现
|
||
3. 删除各服务 pages/routes 中的重复实现
|
||
4. 保证最终每个服务的 `/health` 都来自同一装配路径
|
||
|
||
### 验收标准
|
||
|
||
- 服务层页面路由文件中不再重复定义 `/health`
|
||
- `GET /health` 行为仍与现有外部契约兼容
|
||
- 相关 shared / entrypoint tests 通过
|
||
|
||
---
|
||
|
||
## P1-1. 收敛 Batch 2 目标文件中的 `sys.path.insert(...)` 残留
|
||
|
||
### 问题
|
||
|
||
本轮 shared 化后，以下 10 个核心文件本身仍保留路径注入模板：
|
||
|
||
- `auth/src/config.py`
|
||
- `blog/src/config.py`
|
||
- `canvas/src/config.py`
|
||
- `prompt/src/config.py`
|
||
- `home/src/config.py`
|
||
- `auth/src/main.py`
|
||
- `blog/src/main.py`
|
||
- `canvas/src/main.py`
|
||
- `prompt/src/main.py`
|
||
- `home/src/main.py`
|
||
|
||
这说明当前统一只是“逻辑 shared 化”，不是“导入边界稳定化”。
|
||
|
||
### 必须改什么
|
||
|
||
本轮至少把这 10 个文件收住，不要求一次性清理全仓。
|
||
|
||
推荐两种方案里选一种：
|
||
|
||
#### 方案 A：抽统一 import bootstrap helper（推荐）
|
||
|
||
例如新增：
|
||
- `shared/imports.py`
|
||
|
||
提供统一函数，例如：
|
||
|
||
```python
|
||
def ensure_project_root(file_path: str, levels: int = 3) -> None: ...
|
||
```
|
||
|
||
让入口/配置文件统一调用 helper，不再各自复制：
|
||
|
||
```python
|
||
project_root = Path(...)
|
||
if str(project_root) not in sys.path:
|
||
sys.path.insert(0, str(project_root))
|
||
```
|
||
|
||
#### 方案 B：修正运行/测试约定，让入口文件不再自行改 path
|
||
|
||
如果当前项目运行方式允许，也可以通过统一 cwd / pytest path / uvicorn 启动约定来消除核心入口内的 path hack。
|
||
|
||
但从风险和改造成本看，本轮更推荐方案 A。
|
||
|
||
### 最低要求
|
||
|
||
至少保证上面列出的 10 个文件不再各自手写重复模板，哪怕先统一到一个 helper。
|
||
|
||
### 验收标准
|
||
|
||
- 10 个核心文件中不再散落重复的 path 注入模板
|
||
- 改完后这 10 个文件仍然可导入
|
||
- 不引入新的循环依赖
|
||
|
||
---
|
||
|
||
## P1-2. 将 home/admin 路由守卫的公共骨架提取到 shared
|
||
|
||
### 问题
|
||
|
||
当前 `home/src/routes/admin.py` 实际上已经有明确的服务端路由守卫：
|
||
|
||
- 未登录跳转 auth 登录页
|
||
- 带 redirect 返回
|
||
- 已登录但无权限则拒绝/跳转
|
||
- service token 禁止访问 home admin
|
||
|
||
这说明现在 **有 guard**，但它仍然是 `home` 服务内的私有实现。问题不在“有没有守卫”，而在“守卫骨架没有统一”。
|
||
|
||
如果未来 blog/canvas/prompt 继续加强 admin 规则，极容易再次复制 `_require_auth(...)` 模式，造成：
|
||
|
||
- 登录跳转策略漂移
|
||
- redirect 处理方式漂移
|
||
- service token admin 访问策略漂移
|
||
|
||
### 必须改什么
|
||
|
||
1. 在 `shared/` 新增 admin guard helper（命名可调整）
|
||
2. helper 至少负责这三件事：
|
||
- 未登录时的登录跳转 URL 拼装
|
||
- service token 是否允许访问 admin 的统一策略
|
||
- 权限失败时的统一返回约定
|
||
3. `home/src/routes/admin.py` 改为消费 shared helper
|
||
4. 先落地 home，不要求本轮同步改完所有服务 admin
|
||
|
||
### 不需要在本轮做的事
|
||
|
||
- 不要求把所有业务权限判断都抽进去
|
||
- 不要求统一所有服务特有的资源级权限逻辑
|
||
- 不要求一次性重写 blog/canvas/prompt 的 admin 认证结构
|
||
|
||
### 验收标准
|
||
|
||
- `home/src/routes/admin.py` 不再保留大段内联 guard 骨架模板
|
||
- shared helper 能表达登录跳转 / redirect / service token admin 禁入策略
|
||
- home 现有 admin 行为无回归
|
||
|
||
---
|
||
|
||
## P1-3. 补服务入口装配级合同测试
|
||
|
||
### 问题
|
||
|
||
当前 shared 测试通过，能证明：
|
||
- shared config base 基本可用
|
||
- shared error handlers 基本可用
|
||
- shared app factory 基本可用
|
||
|
||
但这不等于五个真实服务入口都还能导入、装配、挂 router、提供 `/health`。
|
||
|
||
现在缺的是一类非常轻量但非常关键的测试：**服务入口装配合同测试**。
|
||
|
||
### 必须改什么
|
||
|
||
新增一组轻量测试，重点不是测业务，而是测“服务入口仍站得住”。
|
||
|
||
建议覆盖：
|
||
|
||
1. 五个服务入口都可导入
|
||
- `auth/src/main.py`
|
||
- `blog/src/main.py`
|
||
- `canvas/src/main.py`
|
||
- `prompt/src/main.py`
|
||
- `home/src/main.py`
|
||
2. 导入后存在 `app`
|
||
3. `app.routes` 中包含 `/health`
|
||
4. docs 开关仍符合 dev/prod 预期
|
||
5. static mount / router 注册没有在统一重构中丢失
|
||
|
||
### 验收标准
|
||
|
||
新增测试能在这些情况给出明确失败信号：
|
||
- shared factory 依赖缺失
|
||
- 入口导入断裂
|
||
- `/health` 丢失
|
||
- app factory 装配未生效
|
||
|
||
---
|
||
|
||
## 二、建议修改（P2）
|
||
|
||
这些不是“本轮不改就一定阻断”的问题，但建议一起纳入开发检查表。
|
||
|
||
## P2-1. 统一依赖声明与文档说明
|
||
|
||
### 建议改什么
|
||
|
||
1. 在依赖文件中明确标注 shared app factory 的新增公共依赖
|
||
2. 若项目有 README / 开发说明，补一句：
|
||
- 使用 shared app factory 的服务，需要安装公共依赖集
|
||
3. 若有部署脚本或 bootstrap 脚本，检查是否与 requirements 同步
|
||
|
||
### 目的
|
||
|
||
避免开发者只看代码不看变更背景，导致本地能跑 shared tests、却跑不动服务 tests。
|
||
|
||
---
|
||
|
||
## P2-2. 为 `ENV` / `ENVIRONMENT` 兼容关系补显式测试
|
||
|
||
### 背景
|
||
|
||
当前 `home` 仍兼容历史 `ENVIRONMENT`，这是对的，但兼容行为需要被明确测试下来，否则后面很容易被“顺手清理”掉。
|
||
|
||
### 建议增加的断言
|
||
|
||
至少覆盖：
|
||
|
||
1. 只设置 `ENVIRONMENT=development` 时，`home` 仍进入开发模式
|
||
2. 同时设置 `ENV=production` 与 `ENVIRONMENT=development` 时，以 `ENV` 为准
|
||
3. 未设置时默认回落到 `production`
|
||
|
||
### 目的
|
||
|
||
把“历史兼容”从口头约定变成测试契约。
|
||
|
||
---
|
||
|
||
## P2-3. 统一 config summary 输出风格，但不要统一业务字段含义
|
||
|
||
### 建议改什么
|
||
|
||
1. 保持 summary 打印格式统一
|
||
2. 但不要为了“字段看起来一样”而强行让各服务展示完全同一组字段
|
||
|
||
### 原则
|
||
|
||
- 统一的是打印骨架
|
||
- 不是每个服务必须展示完全一样的业务字段
|
||
|
||
例如：
|
||
- `blog` 仍应展示 `CONTENT_DIR` / `CACHE_DIR`
|
||
- `home` 仍应展示 `AUTH_BASE_URL` / `SERVICE_PORT`
|
||
|
||
### 目的
|
||
|
||
避免“形式统一”侵入业务语义。
|
||
|
||
---
|
||
|
||
## P2-4. 为后续全仓导入治理保留清单，但不要本轮扩大范围
|
||
|
||
### 已确认存在的后续技术债
|
||
|
||
除了 10 个核心文件外，route/service/test 层仍有较多 `sys.path.insert(...)`。
|
||
|
||
### 建议处理方式
|
||
|
||
- 本轮只在 PRD 中登记为后续项
|
||
- 不要在这轮顺手扩展到全仓清理
|
||
|
||
### 原因
|
||
|
||
这类改动跨面太大，容易把“当前可收敛的重构收尾”演变成“无法控风险的大扫除”。
|
||
|
||
---
|
||
|
||
## 三、明确不要修改的内容
|
||
|
||
以下内容在本轮必须明确禁止“顺手改”：
|
||
|
||
1. **不要重写业务权限模型**
|
||
- 例如 owner/admin/user 的权限体系
|
||
- 不属于 app/config 统一收尾范围
|
||
|
||
2. **不要把所有 auth/token 校验逻辑一次性抽到 shared**
|
||
- 当前只要求抽 admin guard 公共骨架
|
||
- 不是全站认证大重构
|
||
|
||
3. **不要一口气清理所有 `sys.path.insert(...)`**
|
||
- 只收缩 Batch 2 涉及的核心入口/配置文件
|
||
- 其余留待后续技术债专项
|
||
|
||
4. **不要改 service API / 路由外部契约**
|
||
- URL 不变
|
||
- 响应形态不因为这轮统一而改变
|
||
|
||
5. **不要顺手改目录结构**
|
||
- 不迁移为全量 package layout
|
||
- 不移动服务目录
|
||
|
||
6. **不要把 config 层业务逻辑抽进 shared**
|
||
- 例如 blog 的缓存目录创建
|
||
- canvas 的 content 目录自动创建
|
||
- 这些仍应由各服务自己负责
|
||
|
||
---
|
||
|
||
## 四、建议实施顺序
|
||
|
||
虽然这份文档不再按阶段写，但实际落地仍建议按风险从低到高推进：
|
||
|
||
### 1. 先补依赖契约
|
||
- 先解决 `slowapi` 安装链路
|
||
- 否则后续很多入口测试都没法真实验证
|
||
|
||
### 2. 再补入口合同测试
|
||
- 先建立“导入/装配级失败能被看见”的机制
|
||
- 避免边改边盲飞
|
||
|
||
### 3. 再收敛 10 个核心文件的 path hack
|
||
- 控制范围，不碰全仓
|
||
|
||
### 4. 再抽 home/admin guard 骨架
|
||
- 这是结构优化，不是依赖修复，放在后面更稳
|
||
|
||
### 5. 最后全量回归
|
||
- shared tests
|
||
- auth smoke
|
||
- home tests
|
||
- 新增 entrypoint tests
|
||
|
||
---
|
||
|
||
## 五、建议涉及文件
|
||
|
||
## 必改文件
|
||
|
||
- `shared/app_factory.py`
|
||
- `shared/config_base.py`（如需补 helper / 兼容逻辑 / 测试契约）
|
||
- `auth/src/main.py`
|
||
- `blog/src/main.py`
|
||
- `canvas/src/main.py`
|
||
- `prompt/src/main.py`
|
||
- `home/src/main.py`
|
||
- `auth/src/config.py`
|
||
- `blog/src/config.py`
|
||
- `canvas/src/config.py`
|
||
- `prompt/src/config.py`
|
||
- `home/src/config.py`
|
||
- 依赖声明文件（按项目实际结构）
|
||
|
||
## 建议新增文件
|
||
|
||
- `shared/imports.py` 或等价 helper
|
||
- `shared/admin_guard.py` 或等价 helper
|
||
- `tests/test_service_entrypoints.py` 或等价入口合同测试文件
|
||
|
||
## 只观察，不要求本轮修改
|
||
|
||
- `home/src/services/auth.py`
|
||
- 其他 route/service/test 中的历史 `sys.path.insert(...)`
|
||
- 任何 service API / 业务 handler 的功能逻辑
|
||
|
||
---
|
||
|
||
## 六、完整验收命令
|
||
|
||
至少执行并记录以下验证：
|
||
|
||
```bash
|
||
cd /home/ubuntu/ephron.ren
|
||
git fetch origin
|
||
python -m pytest tests/test_security_hardening.py tests/test_frontend_backend_reuse_contract.py -q
|
||
python -m pytest auth/tests/test_security_hardening.py auth/tests/test_login_redirect_flow.py -q
|
||
```
|
||
|
||
如果新增了入口合同测试，再执行：
|
||
|
||
```bash
|
||
python -m pytest tests/test_service_entrypoints.py -q
|
||
```
|
||
|
||
如果抽了 home admin guard helper，再补：
|
||
|
||
```bash
|
||
python -m pytest home/tests -q
|
||
```
|
||
|
||
如果有 shared 相关新增单测，也一并跑：
|
||
|
||
```bash
|
||
python -m pytest tests/test_shared_config_base.py tests/test_error_handlers.py tests/test_app_factory.py -q
|
||
```
|
||
|
||
---
|
||
|
||
## 七、完成定义
|
||
|
||
满足以下全部条件，才算这轮优化真正完成：
|
||
|
||
1. `slowapi` 在开发、测试、部署链路中都已被视为公共硬依赖
|
||
2. 服务入口级测试不再因 `slowapi` 缺失而 import 失败
|
||
3. `/health` 已统一归口到 shared app factory
|
||
4. Batch 2 涉及的 10 个核心 `main.py/config.py` 文件不再各自复制 path 注入模板，或至少统一到同一 helper
|
||
5. `home` 的 admin 路由守卫公共骨架已进入 shared 层
|
||
6. 新增服务入口装配合同测试，并实际通过
|
||
7. shared 层测试 + auth smoke + home 相关测试均通过
|
||
8. 外部行为未发生非预期变化：
|
||
- URL 不变
|
||
- docs_url 行为兼容
|
||
- static mount 行为兼容
|
||
- 404/500 页面行为兼容
|
||
|
||
---
|
||
|
||
## 八、一句话给开发的执行原则
|
||
|
||
这轮工作的本质不是“继续抽公共代码”，而是：
|
||
|
||
> 把已经做完的 shared 化，补成一套真正可依赖、可验证、可持续的工程约束。
|
||
|
||
判断标准也很明确：
|
||
|
||
- 不是“代码看起来更整洁了”
|
||
- 而是“入口真的能导入、依赖真的齐、guard 不再乱飘、测试真的能兜住回归”
|
||
|
||
做到这一点，这轮 app factory / config unification 才算真正收口。
|