chore: 新增上线检查单与脱敏 env 模板

docs/before-prod/production-readiness-summary-2026-03-11.md

@@ -0,0 +1,137 @@
+# Production 上线判断总结（2026-03-11）
+
+## 结论
+
+当前代码已经接近可上线状态，但是否可以直接进入 `production`，取决于图片功能的上线策略。
+
+- 如果接受丢弃历史旧图，并且上线时将 `MEMOIR_IMAGE_ENABLED=false`，则本次改动不需要额外做数据库迁移，整体风险可控，可以作为保守方案进入生产。
+- 如果准备在生产立即启用章节配图功能，则仍需确认生产 COS 资源、Liblib 凭证、Celery worker 部署和新依赖安装均已就绪，之后再启用更稳妥。
+
+## 本次评估范围
+
+本次评估针对 `8b4a058..HEAD` 期间的改动，重点检查了以下内容：
+
+- 数据库模型和迁移脚本是否变化
+- API / WebSocket / Celery 是否有生产兼容性风险
+- 回忆录图片链路是否会影响现网章节读取、阅读页和 PDF 导出
+- 生产环境变量和容器部署形态是否能承接新能力
+
+## 数据库与迁移判断
+
+### 不需要新增 schema 迁移
+
+本次区间内没有新增数据库表、字段或字段类型修改。
+
+- `api/database/models.py` 中 `Chapter.images` 只有注释语义变化，从“图片 URL 列表”变成“图片元数据对象列表”
+- `api/migrations/sync_schema_to_models.sql` 在这段提交区间没有新增迁移内容
+
+因此：
+
+- 不需要新增 SQL migration
+- 不需要执行结构性数据迁移
+
+## 图片功能判断
+
+### `MEMOIR_IMAGE_ENABLED` 不是“全功能总开关”
+
+这个开关能控制的是：
+
+- 是否初始化待生成图片资产
+- 是否派发 `generate_chapter_images` 任务
+- 是否在读取章节时过滤掉未完成图片状态
+
+这个开关不能完全关闭的内容：
+
+- 章节正文里的图片占位符注入逻辑仍会存在
+- 已完成图片仍可能继续被返回和渲染
+- 章节接口仍会进入图片归一化逻辑
+- PDF 导出仍会处理已完成图片
+
+### 旧 `chapters.images` 数据兼容性
+
+历史文档里 `images` 被定义为“图片 URL 列表”，但当前代码要求每个元素都具备至少以下字段：
+
+- `placeholder`
+- `description`
+
+否则在归一化时会被过滤掉。
+
+结论：
+
+- 如果必须保留历史旧图，需要额外做读兼容或数据修复
+- 如果业务允许丢弃历史旧图，则这项不再构成上线阻塞
+
+### 当前推荐策略
+
+结合当前讨论结果，推荐采用以下上线策略：
+
+1. 允许丢弃历史旧图
+2. 生产环境先保持 `MEMOIR_IMAGE_ENABLED=false`
+3. 先完成主链路上线
+4. 等生产 COS / Liblib / worker 验证完成后，再单独开启图片能力
+
+这样做的好处：
+
+- 不需要补兼容代码
+- 不需要回填旧数据
+- 能把风险集中在“新生成图片”而不是“历史数据”
+
+## 生产环境配置判断
+
+### 已具备的条件
+
+- `Dockerfile` 会安装新的 Python 依赖，包括 `cos-python-sdk-v5`
+- `docker-compose.yml` 已包含 `api` 和 `celery-worker`
+- `api/.env.production` 已经包含图片链路需要的 `LIBLIB_*` 和 `TENCENT_COS_*` 配置项
+
+### 仍需确认的点
+
+- `TENCENT_COS_BUCKET` 和 `TENCENT_COS_BASE_URL` 是否为真正的生产资源
+- API 镜像和 Celery worker 是否会同步升级
+- 部署时是否一定会基于最新 `requirements.txt` 重新构建镜像
+
+## 当前建议的上线结论
+
+### 可以进入生产的前提
+
+满足以下条件时，可以作为稳妥方案进入生产：
+
+1. 接受丢弃历史旧图
+2. 保持 `MEMOIR_IMAGE_ENABLED=false`
+3. 使用最新镜像同时部署 `api` 与 `celery-worker`
+4. 确认 COS 配置不是误填开发资源
+
+### 不建议直接开启图片功能的场景
+
+如果满足以下任一情况，建议不要在本次发版里直接启用图片生成：
+
+- 生产 COS bucket 尚未确认
+- Liblib 凭证未经生产验证
+- Celery worker 不会同步升级
+- 希望保留历史旧图但尚未做兼容或数据修复
+
+## 最短上线检查单
+
+发版前至少确认以下 5 项：
+
+1. `api/.env.production` 中 `MEMOIR_IMAGE_ENABLED` 是否符合本次上线策略
+2. `TENCENT_COS_BUCKET` / `TENCENT_COS_BASE_URL` 是否为生产资源
+3. `api` 和 `celery-worker` 是否会使用同一版新镜像
+4. 镜像是否会基于最新 `requirements.txt` 重建
+5. 团队是否明确接受“历史旧图可能消失”
+
+## 建议的发布策略
+
+推荐分两步：
+
+### 第一步：保守上线
+
+- 发布当前代码
+- `MEMOIR_IMAGE_ENABLED=false`
+- 观察 API、WebSocket、章节读取、PDF 导出是否稳定
+
+### 第二步：功能放量
+
+- 确认 COS / Liblib / worker 正常
+- 再将 `MEMOIR_IMAGE_ENABLED=true`
+- 仅对新生成章节启用图片功能