452 lines
10 KiB
Markdown
452 lines
10 KiB
Markdown
# PRD: App Factory + Config 统一重构（PR1 Batch 2）
|
||
|
||
## 背景
|
||
|
||
PR1 Batch 1 已完成并通过验证，已落地：
|
||
|
||
- `shared/config_base.py`
|
||
- `shared/error_handlers.py`
|
||
- `shared/app_factory.py`
|
||
- `tests/test_shared_config_base.py`
|
||
- `tests/test_error_handlers.py`
|
||
- `tests/test_app_factory.py`
|
||
|
||
当前 Batch 1 已验证通过，共 **26 个测试通过**，说明 shared 基础骨架已经可用。
|
||
|
||
接下来的 Batch 2 不再新增基础模块，而是把这些 shared 能力**真正接入五个服务**：
|
||
|
||
1. 改造五个服务的 `config.py`
|
||
2. 改造五个服务的 `main.py`
|
||
3. 调整必要的兼容测试与行为验证
|
||
|
||
这一批是 PR1 中真正高风险的部分，因为它会影响现有服务启动与运行行为。
|
||
|
||
---
|
||
|
||
## Batch 2 目标
|
||
|
||
本批次完成后，应该达到：
|
||
|
||
1. 五个服务 `config.py` 改为复用 shared config helper
|
||
2. 五个服务 `main.py` 改为通过 shared app factory 创建 app
|
||
3. `home` 继续兼容历史 `ENVIRONMENT`
|
||
4. `/health` 只保留统一实现，不产生重复注册
|
||
5. 外部行为保持兼容：
|
||
- URL 不变
|
||
- docs_url 行为不变
|
||
- static 挂载策略不被误改
|
||
- 404/500 页面行为兼容
|
||
|
||
---
|
||
|
||
## 非目标
|
||
|
||
这一批**不做**：
|
||
|
||
- 不收敛 `sys.path.insert`
|
||
- 不改数据库 migration 归属
|
||
- 不改 service API
|
||
- 不调整目录结构
|
||
- 不统一所有 config 展示字段的内容
|
||
|
||
原因：这一批的核心任务是**接入 shared 骨架**，不是扩大范围做结构总清理。
|
||
|
||
---
|
||
|
||
## 批次顺序建议
|
||
|
||
为了降低回归风险，建议不要一次性全量乱序改。
|
||
|
||
### 先改 `config.py`
|
||
顺序建议：
|
||
1. `auth/src/config.py`
|
||
2. `blog/src/config.py`
|
||
3. `canvas/src/config.py`
|
||
4. `prompt/src/config.py`
|
||
5. `home/src/config.py` 最后
|
||
|
||
原因：
|
||
- `home` 有 `ENVIRONMENT` 历史兼容包袱，特殊性最强
|
||
- 先处理标准服务，再处理兼容服务，排障更容易
|
||
|
||
### 再改 `main.py`
|
||
顺序建议：
|
||
1. `canvas/src/main.py`
|
||
2. `prompt/src/main.py`
|
||
3. `blog/src/main.py`
|
||
4. `auth/src/main.py`
|
||
5. `home/src/main.py` 最后
|
||
|
||
原因：
|
||
- `canvas` 和 `prompt` 相对简单
|
||
- `blog`/`auth` 启动逻辑与历史 handler 更复杂
|
||
- `home` 还涉及重复 `/health`，最容易出兼容问题
|
||
|
||
---
|
||
|
||
## Step 5：改造五个服务 `config.py`
|
||
|
||
涉及：
|
||
- `auth/src/config.py`
|
||
- `blog/src/config.py`
|
||
- `canvas/src/config.py`
|
||
- `home/src/config.py`
|
||
- `prompt/src/config.py`
|
||
|
||
目标：
|
||
- 删除重复的 `.env` / required / optional / env mode helper
|
||
- 改为复用 `shared/config_base.py`
|
||
- 保持各服务专属字段与校验逻辑不变
|
||
|
||
---
|
||
|
||
### 5.1 `auth/src/config.py`
|
||
|
||
### 保留内容
|
||
- `AUTH_SECRET_KEY`
|
||
- `DATABASE_PATH`
|
||
- `COOKIE_DOMAIN`
|
||
- `COOKIE_NAME`
|
||
- `TOKEN_MAX_AGE`
|
||
- `PROJECT_ROOT`
|
||
- `TEMPLATES_DIR`
|
||
- `validate_config()`
|
||
|
||
### 改造方式
|
||
- 用 `load_service_env(_project_root)` 替换本地 `.env` 加载逻辑
|
||
- 用 `get_required_env()` / `get_optional_env()` 替换本地 helper
|
||
- 用 shared summary helper 统一打印机制
|
||
|
||
### 注意事项
|
||
- `validate_config()` 的行为不能漂移
|
||
- 现有 auth 的输出字段尽量保持一致，避免影响排障习惯
|
||
|
||
---
|
||
|
||
### 5.2 `blog/src/config.py`
|
||
|
||
### 保留内容
|
||
- `AUTH_SECRET_KEY`
|
||
- `TOKEN_MAX_AGE`
|
||
- `CONTENT_DIR`
|
||
- `CACHE_DIR`
|
||
- `SEARCH_INDEX_DIR`
|
||
- `COOKIE_NAME`
|
||
- `PROJECT_ROOT`
|
||
- `STATIC_DIR`
|
||
- `TEMPLATES_DIR`
|
||
|
||
### 改造方式
|
||
- 替换 env helper 为 shared helper
|
||
- 保留：
|
||
- `CONTENT_DIR` 存在性检查
|
||
- `CACHE_DIR.mkdir(...)`
|
||
- `SEARCH_INDEX_DIR.mkdir(...)`
|
||
|
||
### 注意事项
|
||
- 不要把目录初始化逻辑抽进 shared 层
|
||
- blog 目录语义应继续由 blog 自己负责
|
||
|
||
---
|
||
|
||
### 5.3 `canvas/src/config.py`
|
||
|
||
### 保留内容
|
||
- `AUTH_SECRET_KEY`
|
||
- `TOKEN_MAX_AGE`
|
||
- `CONTENT_DIR`
|
||
- `COOKIE_NAME`
|
||
- `PROJECT_ROOT`
|
||
- `TEMPLATES_DIR`
|
||
|
||
### 改造方式
|
||
- 替换 env helper 为 shared helper
|
||
- 保留 `CONTENT_DIR` 不存在时自动创建的行为
|
||
|
||
### 注意事项
|
||
- 不能把当前行为从“自动创建”改成“配置报错退出”
|
||
- 这点和 blog 不同，不能硬统一
|
||
|
||
---
|
||
|
||
### 5.4 `prompt/src/config.py`
|
||
|
||
### 保留内容
|
||
- `AUTH_SECRET_KEY`
|
||
- `TOKEN_MAX_AGE`
|
||
- `DATABASE_PATH`
|
||
- `PROJECT_ROOT`
|
||
- `TEMPLATES_DIR`
|
||
- `validate_config()`
|
||
|
||
### 改造方式
|
||
- 替换 env helper 为 shared helper
|
||
- 暂时不扩大范围去彻底修 prompt 的 import 结构
|
||
|
||
### 注意事项
|
||
- 这一批只做 config 接入，不顺手改 import 体系
|
||
- 避免把单个 PR 变成“顺便半重构”
|
||
|
||
---
|
||
|
||
### 5.5 `home/src/config.py`
|
||
|
||
这是本批 `config.py` 里最需要小心的一个。
|
||
|
||
### 保留内容
|
||
- `STATIC_DIR`
|
||
- `TEMPLATES_DIR`
|
||
- `COOKIE_NAME`
|
||
- `SERVICE_PORT`
|
||
- `AUTH_PORT`
|
||
- `AUTH_BASE_URL`
|
||
- `AUTH_LOGIN_URL`
|
||
- `validate_config()`
|
||
|
||
### 改造方式
|
||
- 使用 `resolve_environment(legacy_key="ENVIRONMENT")`
|
||
- `ENV` 成为统一主字段
|
||
- 兼容历史 `ENVIRONMENT`
|
||
|
||
### 必测要求
|
||
- 只设置 `ENVIRONMENT=development` 时，仍进入开发模式
|
||
- 同时设置 `ENV=production` 与 `ENVIRONMENT=development` 时，以 `ENV` 为准
|
||
|
||
### 注意事项
|
||
- 这里不要用“看起来统一”破坏历史兼容
|
||
- `AUTH_BASE_URL` / `AUTH_LOGIN_URL` 逻辑必须保持不变
|
||
|
||
---
|
||
|
||
## Step 6：改造五个服务 `main.py`
|
||
|
||
涉及：
|
||
- `auth/src/main.py`
|
||
- `blog/src/main.py`
|
||
- `canvas/src/main.py`
|
||
- `home/src/main.py`
|
||
- `prompt/src/main.py`
|
||
|
||
目标：
|
||
- 删除重复的 app 创建与通用装配逻辑
|
||
- 改为统一通过 `shared.app_factory.create_service_app(...)`
|
||
|
||
每个服务应保留：
|
||
- service 专属 lifespan
|
||
- router 列表
|
||
- 标题/描述/version
|
||
- templates/static 路径
|
||
- service_name
|
||
|
||
---
|
||
|
||
### 6.1 `canvas/src/main.py`
|
||
|
||
建议先改这个，因为最简单。
|
||
|
||
### 要保留
|
||
- `validate_config()`
|
||
- `print_config_summary()`
|
||
- canvas 专属 lifespan
|
||
- `pages/admin/service_api` routers
|
||
|
||
### 要替换
|
||
- 手写 `FastAPI(...)`
|
||
- 手写 `install_security_headers(app)`
|
||
- 手写 limiter 装配
|
||
- 手写 static mount
|
||
- 手写 error handlers
|
||
- 手写 `/health`
|
||
|
||
### 注意事项
|
||
- `static_dir` 传入时必须兼容“目录存在才挂载”策略
|
||
|
||
---
|
||
|
||
### 6.2 `prompt/src/main.py`
|
||
|
||
### 要保留
|
||
- `init_db()`
|
||
- `print_config_summary()`
|
||
- prompt 专属 routers
|
||
|
||
### 注意事项
|
||
- app factory 只负责 app 壳，不负责 prompt 特有 db 初始化
|
||
- db 初始化仍放在 prompt 自己 lifespan 里
|
||
|
||
---
|
||
|
||
### 6.3 `blog/src/main.py`
|
||
|
||
### 要保留
|
||
- search index 启动检查逻辑
|
||
- `print_config_summary()`
|
||
- blog 专属 routers
|
||
|
||
### 注意事项
|
||
- 这批不要顺手优化“搜索索引启动阻塞”问题
|
||
- 只做 app factory 接入，保持当前行为
|
||
|
||
---
|
||
|
||
### 6.4 `auth/src/main.py`
|
||
|
||
### 要保留
|
||
- `init_db()`
|
||
- `_build_login_target()` 与 root redirect 逻辑
|
||
- `print_config_summary()`
|
||
- auth 专属 routers
|
||
|
||
### 注意事项
|
||
- auth 有较多 redirect / login 细节，这批只做 app 壳替换，不改 redirect 语义
|
||
|
||
---
|
||
|
||
### 6.5 `home/src/main.py`
|
||
|
||
这是本批 `main.py` 中最需要小心的一个。
|
||
|
||
### 必做
|
||
- 将 app 创建迁到 factory
|
||
- 处理 `/health` 重复定义
|
||
|
||
### 推荐做法
|
||
- 删除 `home/src/routes/pages.py` 中的 `/health`
|
||
- 统一由 app factory 提供 `/health`
|
||
|
||
### 原因
|
||
如果两处都保留，会出现：
|
||
- 路由重复
|
||
- 行为漂移
|
||
- 后续 health 契约难统一
|
||
|
||
### 注意事项
|
||
- `home` 是兼容包袱最多的服务，建议最后处理
|
||
|
||
---
|
||
|
||
## 需要补的验证
|
||
|
||
## 一、config 层验证
|
||
建议至少验证：
|
||
|
||
```bash
|
||
python -m pytest tests/test_security_hardening.py -q
|
||
python -m pytest auth/tests -q
|
||
python -m pytest blog/tests -q
|
||
python -m pytest canvas/tests -q
|
||
python -m pytest home/tests -q
|
||
python -m pytest prompt/tests -q
|
||
```
|
||
|
||
重点确认：
|
||
- `home` 的 `ENVIRONMENT` 兼容逻辑仍然成立
|
||
- 各服务 config import 后不会报错
|
||
|
||
---
|
||
|
||
## 二、main.py 接入验证
|
||
建议验证：
|
||
|
||
- 所有服务仍能创建 app
|
||
- dev 模式 `/docs` 仍可用
|
||
- `/health` 正常
|
||
- API 404 返回 JSON
|
||
- 页面 404/500 继续使用模板
|
||
- static 挂载策略不漂移
|
||
|
||
如本地可启动，建议：
|
||
|
||
```bash
|
||
python main.py --reload
|
||
```
|
||
|
||
手动检查：
|
||
- home / auth / blog / canvas / prompt 均可启动
|
||
- 任意不存在 API 路径返回 JSON 404
|
||
- 任意不存在页面返回模板 404
|
||
|
||
---
|
||
|
||
## 必须特别注意的 4 个坑
|
||
|
||
### 1. 不要扩大范围改 import 结构
|
||
这批不要顺手去处理 `sys.path.insert`。
|
||
|
||
原因：
|
||
- 会扩大变更面
|
||
- 增加排障难度
|
||
- 混淆“是 app factory 接入问题，还是 import 重构问题”
|
||
|
||
---
|
||
|
||
### 2. 不要把 `print_config_summary()` 内容硬统一
|
||
共享层只应统一**打印机制**，而不是强行让所有服务显示完全同样的字段。
|
||
|
||
原因：
|
||
- 每个服务关注的关键字段不同
|
||
- 一刀切会损失调试价值
|
||
|
||
---
|
||
|
||
### 3. API 500 JSON 化属于“标准化改进”，要显式说明
|
||
Batch 1 中 shared error handler 已将 API 500 规范成 JSON：
|
||
|
||
```json
|
||
{"detail": "Internal Server Error"}
|
||
```
|
||
|
||
development 模式可额外包含：
|
||
|
||
```json
|
||
{"detail": "Internal Server Error", "error": "..."}
|
||
```
|
||
|
||
这是合理改进，但应在实现说明中显式标注，避免被误解为无意行为变化。
|
||
|
||
---
|
||
|
||
### 4. `home/src/routes/pages.py` 的 `/health` 不能双留
|
||
如果 app factory 已统一提供 `/health`，就不能再保留 home pages 里的那份。
|
||
|
||
这是本批次最可能引发路由重复问题的点。
|
||
|
||
---
|
||
|
||
## 建议提交拆分
|
||
|
||
建议至少拆成 4 个 commit：
|
||
|
||
1. `refactor: migrate auth/blog/canvas/prompt config modules to shared helpers`
|
||
2. `refactor: migrate home config module with ENVIRONMENT compatibility`
|
||
3. `refactor: migrate canvas/prompt/blog/auth main modules to shared app factory`
|
||
4. `refactor: migrate home main module to shared app factory and unify health endpoint`
|
||
|
||
这样更方便分批 review 和定位问题。
|
||
|
||
---
|
||
|
||
## 完成定义
|
||
|
||
Batch 2 完成后，必须满足：
|
||
|
||
- [ ] 五个服务 `config.py` 已接入 `shared/config_base.py`
|
||
- [ ] 五个服务 `main.py` 已接入 `shared/app_factory.py`
|
||
- [ ] `home` 兼容 `ENVIRONMENT`
|
||
- [ ] `/health` 统一且无重复注册
|
||
- [ ] static 挂载策略保持兼容
|
||
- [ ] API 404/500 与页面 404/500 行为符合预期
|
||
- [ ] 所有相关测试通过
|
||
|
||
---
|
||
|
||
## 后续建议
|
||
|
||
Batch 2 完成后，下一步就可以进入：
|
||
|
||
1. PR1 收尾复查
|
||
2. PR2：抽 `shared/service_api/*` 与 `tests/helpers/*`
|
||
3. PR3：处理 import 结构与 `sys.path.insert`
|
||
4. PR4：统一 DB schema / migration ownership
|
||
|
||
这才是合理的节奏：先把 shared app/config 真正接上，再继续更深的结构治理。 |