docs: add batch 2 follow-up unification PRD
This commit is contained in:
Ubuntu
404
prd-app-factory-config-unification-batch2-followup.md
Normal file
404
prd-app-factory-config-unification-batch2-followup.md
Normal file
@@ -0,0 +1,404 @@
|
||||
# PRD — App Factory / Config Unification Batch 2 Follow-up
|
||||
|
||||
## 背景
|
||||
|
||||
基于 `origin/main` 最新代码的完整复审，Batch 2 已经完成了两项重要统一：
|
||||
|
||||
1. 五个服务入口 `main.py` 已统一切到 `shared.app_factory.create_service_app(...)`
|
||||
2. 五个服务配置 `config.py` 已基本统一切到 `shared.config_base`
|
||||
|
||||
对应远端提交主线为：
|
||||
- `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
|
||||
|
||||
这说明 Batch 2 的方向是正确的，且公共启动逻辑已经完成第一轮收敛。
|
||||
|
||||
但完整复审后，当前状态还不能定义为“重构完成”。现有实现仍存在三类结构性残留：
|
||||
|
||||
- 入口层和业务层仍大量依赖 `sys.path.insert(...)` 做导入兜底
|
||||
- `shared.app_factory` 已把 `slowapi` 变成统一启动依赖，但测试/安装契约没有同步补齐
|
||||
- home/admin 的认证守卫仍是服务内私有实现，没有进一步抽象为 shared guard helper，后续容易再次漂移
|
||||
|
||||
因此需要补一轮 follow-up 修正，目标不是继续大规模抽象，而是把 Batch 2 从“表面统一”推进到“结构上站稳”。
|
||||
|
||||
---
|
||||
|
||||
## 本轮目标
|
||||
|
||||
1. 消除本轮重构后最显著的导入技术债，减少 `sys.path.insert(...)` 残留
|
||||
2. 补齐 `slowapi` 的依赖契约与测试契约，确保 shared factory 在开发、测试、部署三条链路上一致
|
||||
3. 为 home/admin 当前的路由守卫模式定义统一抽象边界，避免未来各服务重复复制 `_require_auth(...)`
|
||||
4. 补齐回归验证标准，让“通过”不再只表示 shared 单测通过，而是关键服务入口也能被实际导入/启动
|
||||
|
||||
---
|
||||
|
||||
## 非目标
|
||||
|
||||
本轮不做以下内容：
|
||||
|
||||
- 不重写整站认证体系
|
||||
- 不把所有服务的 auth/token 校验一次性全量抽到 shared
|
||||
- 不强行改成 Python package 完整安装式布局（如一次性引入 pyproject + editable install 作为唯一导入方案）
|
||||
- 不改动业务权限模型本身
|
||||
- 不为所有历史测试做全面 fixture 重构
|
||||
|
||||
本轮只处理 Batch 2 复审中已经暴露、且会持续影响后续维护的最小必要问题。
|
||||
|
||||
---
|
||||
|
||||
## 发现的问题
|
||||
|
||||
### P0. shared factory 统一后，`slowapi` 变成强依赖，但测试/环境契约未同步
|
||||
|
||||
#### 现象
|
||||
|
||||
复审中执行：
|
||||
|
||||
```bash
|
||||
python -m pytest tests/test_security_hardening.py tests/test_frontend_backend_reuse_contract.py -q
|
||||
```
|
||||
|
||||
结果通过：
|
||||
|
||||
```text
|
||||
13 passed
|
||||
```
|
||||
|
||||
但执行 auth 侧 smoke tests：
|
||||
|
||||
```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'
|
||||
```
|
||||
|
||||
#### 根因
|
||||
|
||||
`shared.app_factory.py` 直接导入：
|
||||
|
||||
- `from slowapi import _rate_limit_exceeded_handler`
|
||||
- `from slowapi.errors import RateLimitExceeded`
|
||||
|
||||
这意味着一旦服务入口统一切到 shared factory，`slowapi` 就不再是某些服务“可选依赖”，而是所有服务公共启动路径的硬依赖。
|
||||
|
||||
但是当前测试环境或依赖清单没有保证这一点，导致：
|
||||
|
||||
- shared 层合同测试可以过
|
||||
- 真实服务入口测试却无法 import app
|
||||
|
||||
这会制造“重构似乎完成，但服务级 smoke 根本没跑”的假阳性。
|
||||
|
||||
#### 需要修改
|
||||
|
||||
1. 检查并统一项目依赖声明，确保 `slowapi` 出现在实际安装入口中
|
||||
- 根 `requirements*.txt` / 服务依赖清单 / 部署安装脚本中必须一致
|
||||
2. 如果项目采用多入口安装方式，至少保证：
|
||||
- 本地开发安装能拿到 `slowapi`
|
||||
- CI / 测试安装能拿到 `slowapi`
|
||||
- 生产部署安装能拿到 `slowapi`
|
||||
3. 补一条最小 smoke 验证：
|
||||
- 能成功 `import auth/src/main.py` 对应 app
|
||||
- 能成功 `import home/src/main.py` 对应 app
|
||||
|
||||
#### 验收标准
|
||||
|
||||
以下命令在标准开发环境中必须通过：
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
不允许再出现 `ModuleNotFoundError: slowapi`。
|
||||
|
||||
---
|
||||
|
||||
### P1. `sys.path.insert(...)` 残留过多，说明 shared 化尚未形成稳定导入边界
|
||||
|
||||
#### 现象
|
||||
|
||||
本轮复审中，目标文件本身仍保留路径注入：
|
||||
|
||||
- `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`
|
||||
|
||||
此外，搜索结果表明更多 route / service / test 文件中也仍在重复同一模式。
|
||||
|
||||
#### 问题
|
||||
|
||||
这说明当前 shared 重构虽然抽走了公共逻辑，但**没有真正建立清晰的模块导入边界**。直接后果有三个：
|
||||
|
||||
1. 各服务仍默认依赖“脚本式运行 + 手动改 sys.path”
|
||||
2. 测试文件需要反复插 path 才能 import `src.*`
|
||||
3. 后续任何目录结构变化，都会在多个服务同时引发脆弱导入问题
|
||||
|
||||
#### 本轮建议策略
|
||||
|
||||
不要一口气清理全仓所有 `sys.path.insert(...)`，而是先做“核心路径收缩”：
|
||||
|
||||
##### 第一阶段：只处理 Batch 2 涉及的入口与配置
|
||||
|
||||
目标：
|
||||
- 让五个 `main.py`
|
||||
- 五个 `config.py`
|
||||
|
||||
尽量不再各自复制路径注入模板。
|
||||
|
||||
推荐方案二选一：
|
||||
|
||||
**方案 A：抽一个 shared import bootstrap helper**
|
||||
- 新建如 `shared/imports.py` 或等价模块
|
||||
- 提供统一函数，例如：
|
||||
- `ensure_project_root(__file__, levels=3)`
|
||||
- 所有入口/配置文件统一调用这一 helper，而不是手写 `Path(...); if str(...) not in sys.path: sys.path.insert(...)`
|
||||
|
||||
**方案 B：明确项目运行约定，减少入口内 path hack**
|
||||
- 如果现有运行方式允许，以仓库根目录为 working directory 运行 uvicorn / pytest
|
||||
- 配合测试配置修正 import path
|
||||
- 让入口文件不再自己改 `sys.path`
|
||||
|
||||
本轮更推荐 **方案 A**，原因：
|
||||
- 改动小
|
||||
- 风险低
|
||||
- 不要求一次性重建整个包结构
|
||||
- 能先消掉最显眼的重复模板
|
||||
|
||||
##### 第二阶段：只在 follow-up 里列出，不要求本轮全做
|
||||
|
||||
- route 层残留 `sys.path.insert(...)`
|
||||
- service 层残留 `sys.path.insert(...)`
|
||||
- test 层残留 `sys.path.insert(...)`
|
||||
|
||||
这部分可以作为下一轮技术债治理，不在本轮强制清仓。
|
||||
|
||||
#### 验收标准
|
||||
|
||||
至少以下 10 个文件不再各自手写重复的 `sys.path.insert(...)` 模板，或改为统一 helper：
|
||||
|
||||
- `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`
|
||||
|
||||
并补一条测试/检查，验证这些入口仍可被正常导入。
|
||||
|
||||
---
|
||||
|
||||
### P1. home/admin 路由守卫真实存在，但仍是私有实现，后续易漂移
|
||||
|
||||
#### 现象
|
||||
|
||||
`home/src/routes/admin.py` 目前已经具备明确的服务端守卫逻辑：
|
||||
|
||||
- `_require_auth(...)` 负责 cookie 用户校验
|
||||
- 未登录跳转到 auth 登录页，并携带 redirect
|
||||
- 已登录但无权限时拒绝或回首页
|
||||
- service token 明确禁止访问 home admin
|
||||
|
||||
这说明 ephron.ren 现状是：
|
||||
|
||||
- 前台公开页无全局 guard
|
||||
- 管理后台路由有服务端 guard
|
||||
|
||||
这一方向本身是合理的。
|
||||
|
||||
#### 问题
|
||||
|
||||
现在的 guard 逻辑仍被实现为 `home` 服务内部私有函数，风险在于：
|
||||
|
||||
1. 如果 blog/canvas/prompt 后续继续补 admin 规则，很容易各自再复制一份 `_require_auth(...)`
|
||||
2. 登录跳转、redirect 处理、service token 禁入策略可能在不同服务间漂移
|
||||
3. 审计时很难快速确认“所有 admin 路由是否遵循同一守卫契约”
|
||||
|
||||
#### 本轮要求
|
||||
|
||||
本轮不要求把所有服务的鉴权都重构完，但至少要把“守卫抽象边界”定下来。
|
||||
|
||||
推荐最小改法：
|
||||
|
||||
1. 在 `shared/` 新增 admin guard helper（命名可调整）
|
||||
- 负责未登录重定向的通用拼装
|
||||
- 负责 service token 是否允许访问 admin 的统一策略
|
||||
- 负责权限失败的统一响应约定
|
||||
2. `home/src/routes/admin.py` 改为消费 shared helper，而不是继续把完整策略内嵌在文件内部
|
||||
3. 先以 home 为落点，其他服务后续增量迁移
|
||||
|
||||
#### 范围边界
|
||||
|
||||
本轮 shared guard helper 不要求覆盖：
|
||||
- 所有业务权限判断细节
|
||||
- 各服务特有的资源级校验
|
||||
- 所有服务 token 行为差异
|
||||
|
||||
只需要先统一“admin 入口守卫”的公共骨架。
|
||||
|
||||
#### 验收标准
|
||||
|
||||
- `home/src/routes/admin.py` 中不再保留大段内联守卫模板代码
|
||||
- 登录跳转、redirect、service token 禁止访问 admin 的公共逻辑进入 shared helper
|
||||
- 现有 home admin 行为保持不变
|
||||
|
||||
---
|
||||
|
||||
### P2. 当前回归验证偏 shared 层，缺少“服务入口可导入”级别的合同测试
|
||||
|
||||
#### 现象
|
||||
|
||||
当前已经有的 shared/contract 测试能证明：
|
||||
- 安全头策略存在
|
||||
- reuse contract 存在
|
||||
|
||||
但它们不能证明：
|
||||
- 五个服务入口都还能成功 import
|
||||
- shared app factory 的依赖在真实入口层可用
|
||||
- 各服务在统一 factory 下仍保持自己的 startup 责任
|
||||
|
||||
#### 需要补齐
|
||||
|
||||
新增一组轻量合同测试，目标不是测业务，而是测“入口仍然站得住”：
|
||||
|
||||
建议至少覆盖：
|
||||
|
||||
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 开关、static mount、router 注入保留各自行为（可做轻量断言）
|
||||
|
||||
#### 验收标准
|
||||
|
||||
新增测试在标准环境下通过，并能在 shared factory 依赖缺失、入口装配损坏、health route 丢失时给出明确失败信号。
|
||||
|
||||
---
|
||||
|
||||
## 建议实施顺序
|
||||
|
||||
### Task 1 — 补齐 `slowapi` 依赖契约
|
||||
|
||||
- 检查根依赖声明
|
||||
- 检查测试环境安装入口
|
||||
- 补齐缺失项
|
||||
- 跑 auth smoke tests 验证
|
||||
|
||||
### Task 2 — 收缩 Batch 2 目标文件中的 path hack
|
||||
|
||||
- 先只处理五个 `main.py`
|
||||
- 再处理五个 `config.py`
|
||||
- 如果采用 shared helper，保证 helper 本身足够轻量，不引入新的循环依赖
|
||||
|
||||
### Task 3 — 提取 home admin guard 公共骨架
|
||||
|
||||
- 保留当前行为不变
|
||||
- 只抽公共流程，不重写权限模型
|
||||
- 先让 `home` 成为第一个 shared guard 使用者
|
||||
|
||||
### Task 4 — 补轻量入口合同测试
|
||||
|
||||
- 测入口 import
|
||||
- 测 `/health`
|
||||
- 测 shared factory 关键装配结果
|
||||
|
||||
---
|
||||
|
||||
## 建议涉及文件
|
||||
|
||||
### 必改
|
||||
|
||||
- `shared/app_factory.py`
|
||||
- `shared/config_base.py`（如需辅助 import/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
|
||||
- 新的入口合同测试文件
|
||||
|
||||
### 本轮只观察，不强制修改
|
||||
|
||||
- `home/src/services/auth.py`
|
||||
- 其他 route/service/test 中的历史 `sys.path.insert(...)`
|
||||
|
||||
---
|
||||
|
||||
## 验证命令
|
||||
|
||||
至少执行并记录以下命令：
|
||||
|
||||
```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 相关抽象变动，补对应最小验证：
|
||||
|
||||
```bash
|
||||
python -m pytest home/tests -q
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 完成定义
|
||||
|
||||
满足以下条件才算本轮完成：
|
||||
|
||||
1. `slowapi` 不再导致服务入口测试 import 失败
|
||||
2. Batch 2 涉及的 10 个入口/配置文件不再各自复制同一段 path 注入模板，或至少统一为同一个 helper
|
||||
3. home/admin 的公共守卫骨架进入 shared 层，当前行为无回归
|
||||
4. 新增轻量入口合同测试，能证明五个服务入口仍可正常装配
|
||||
5. 所有新增/修改测试通过
|
||||
|
||||
---
|
||||
|
||||
## 备注
|
||||
|
||||
本 PRD 的定位不是重新定义 Batch 2，而是对 Batch 2 做“完整复审后的结构补强”。
|
||||
|
||||
换句话说，前一轮已经解决“多个服务启动方式不统一”的问题；这一轮要解决的是：
|
||||
|
||||
- 统一之后是否真的可维护
|
||||
- 统一之后测试是否真能覆盖到入口层
|
||||
- 统一之后 guard/导入边界是否足够稳定
|
||||
|
||||
这轮做完，才能把 Batch 2 从“完成了一次重构”提升为“建立了可持续的基础设施约束”。
|
||||
Reference in New Issue
Block a user