# 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 才算真正收口。