设计长期优化案例存储机制

2026-07-08 11:30:05 +08:00
parent bf7be12dad
commit 3fb9db8474
3 changed files with 713 additions and 0 deletions
@@ -0,0 +1,573 @@
+# 长期优化案例存储设计
+
+## 目标
+
+建立一套长期存储机制，把运行过程中的原始输入、关键约束、正式产物、过程摘要、LLM 审计摘要和发布后的效果反馈沉淀为可回看、可复用、可学习的优化案例库。
+
+这套机制第一版覆盖两类案例：
+
+- `文章优化案例`：GEO 文章优化主流程产生的案例。
+- `人味文案优化案例`：普通文案人味优化产生的案例。
+
+案例库不仅是历史记录，也是效果学习库。它要能解释“当时为什么这样生成”，也要能继续记录“发布后表现如何”。
+
+## 背景
+
+当前项目已经有一部分长期数据能力：
+
+- 文章优化会保存 `article_jobs`、事实卡、优化稿、QA 报告和导出路径。
+- 文章导出在本地写入 `data/exports/<jobId>/`，Cloudflare 路径写入私有 R2。
+- 发布表现校准已有发布记录、效果快照、评分 run 和校准事件模型。
+- 人味文案优化当前是一次性 API，返回优化后文案、修改说明和 AI 味检查，但不落库。
+
+现有结构能支撑文章优化，但缺少统一案例入口、跨类型列表、案例元数据、失败案例保留、LLM 审计摘要和人味文案长期记录。
+
+## 范围
+
+第一版包含：
+
+- 统一优化案例库。
+- 文章优化案例和人味文案优化案例两种案例类型。
+- 优化时自动保存案例。
+- 成功和失败案例都保存。
+- 结果版本化，重新运行优化生成新版本。
+- 案例列表和案例详情页。
+- 客户、品牌、项目标签、备注等可选归属信息。
+- 基础关键词搜索和常用筛选。
+- 发布记录、效果快照和效果学习入口。
+- 两类案例各自一套评分口径，但共用发布记录和效果快照结构。
+
+第一版不包含：
+
+- 用户账号、团队权限或多租户隔离。
+- 平台 API 自动采集效果数据。
+- 完整全文搜索引擎和搜索高亮。
+- 案例硬删除。
+- 人味文案优化导出文件快照。
+- 默认长期保存完整 prompt/response。
+
+## 核心决策
+
+### 统一案例库
+
+文章优化和人味文案优化都进入同一个优化案例库，通过案例类型筛选。
+
+理由：
+
+- 两类案例都包含原始输入、优化结果、LLM 审计摘要、归属信息和发布表现。
+- 用户需要从一个地方检索和复用历史成果。
+- 详情内容按类型拆分即可，不需要拆成两个入口。
+
+### 自动保存
+
+案例在优化流程中自动保存，不要求用户优化完成后再手动点击保存。
+
+运行开始时创建案例记录，后续持续补充过程摘要、结果版本、审计摘要和错误状态。用户可以在完成后补标题、客户、品牌、项目标签和备注。
+
+### 失败案例保留
+
+失败的优化也保存为失败案例。
+
+失败案例不进入正式产物区，但详情页展示：
+
+- 原始输入。
+- 失败阶段。
+- 错误摘要。
+- LLM 审计摘要。
+- 已产生的过程摘要。
+
+### 结果版本
+
+同一案例重新运行优化时生成新的结果版本，不覆盖旧结果。
+
+发布记录绑定结果版本，而不是绑定整个案例。效果快照继续绑定发布记录。
+
+关系是：
+
+```text
+优化案例 -> 结果版本 -> 发布记录 -> 效果快照 -> 校准结论
+```
+
+### LLM 审计边界
+
+默认长期保存 LLM 审计摘要，不保存完整 prompt/response。
+
+审计摘要包含：
+
+- provider。
+- model。
+- task。
+- duration_ms。
+- schema 校验状态。
+- 错误摘要。
+- 输入内容 hash。
+- 输出内容 hash。
+
+完整 prompt/response 只作为调试证据临时保留，并应有过期时间。第一版可以先不实现完整调试证据存储，但不能把完整 prompt/response 默认写入长期库。
+
+## 数据保留边界
+
+### 文章优化案例
+
+长期保存：
+
+- 原文标题和正文。
+- 图片说明或链接。
+- 目标发布平台。
+- 用户补充要求。
+- 事实卡。
+- 最终优化稿。
+- QA 报告。
+- 评分结果。
+- 导出文件快照。
+- 过程摘要。
+- LLM 审计摘要。
+- 发布记录、效果快照和校准结论。
+
+默认不长期保存：
+
+- 每一轮草稿和 rewrite 全文。
+- 完整 prompt/response。
+- 前端流式事件原始流。
+
+### 人味文案优化案例
+
+长期保存：
+
+- 原始文案。
+- 优化目标。
+- 修改强度。
+- 补充要求。
+- 发布目标。
+- 优化后文案。
+- 修改说明。
+- AI 味检查。
+- warnings。
+- 过程摘要。
+- LLM 审计摘要。
+- 发布记录、效果快照和校准结论。
+
+第一版不保存：
+
+- Markdown/DOCX 导出文件快照。
+- 完整 prompt/response。
+
+### 过程摘要
+
+过程摘要只保存可复盘的轻量信息：
+
+- 阶段名。
+- 开始和结束时间。
+- 耗时。
+- 状态。
+- 失败规则或错误摘要。
+- rewrite 轮次。
+- 是否产出正式版本。
+
+中间稿全文默认不保存。特殊样本保留更多过程内容可以作为后续能力。
+
+## 概念模型
+
+### 优化案例
+
+统一案例库中的顶层记录。
+
+公共字段：
+
+- `id`
+- `case_type`: `article` 或 `human_copy`
+- `title`
+- `summary`
+- `status`: `running`、`optimized`、`failed`、`archived`
+- `customer_name`
+- `brand_name`
+- `project_tags`
+- `notes`
+- `created_at`
+- `updated_at`
+- `archived_at`
+
+`customer_name`、`brand_name`、`project_tags` 和 `notes` 第一版都可选，允许优化完成后补录和编辑。
+
+### 案例输入
+
+保存每个案例的原始输入和约束信息。
+
+文章优化输入包含：
+
+- `source_title`
+- `source_body`
+- `image_inputs`
+- `publish_platform`
+- `user_instructions`
+- `fact_card`
+
+人味文案输入包含：
+
+- `source_text`
+- `goal`
+- `intensity`
+- `user_instructions`
+- `publish_target`
+
+### 结果版本
+
+一次成功优化产出的正式产物版本。
+
+公共字段：
+
+- `id`
+- `case_id`
+- `version`
+- `status`
+- `result_summary`
+- `process_summary`
+- `created_at`
+
+文章优化版本包含：
+
+- 优化稿结构化结果。
+- QA 报告。
+- 评分 run。
+- 导出文件快照引用。
+
+人味文案版本包含：
+
+- `optimized_text`
+- `change_notes`
+- `ai_taste_checks`
+- `warnings`
+- 人味文案评分 run。
+
+### 发布记录
+
+发布记录绑定到某个结果版本。
+
+字段包含：
+
+- `result_version_id`
+- `publish_target`
+- `url`
+- `published_at`
+- `status`
+- `notes`
+
+文章优化和人味文案优化共用这套概念。
+
+### 效果快照
+
+效果快照绑定发布记录。
+
+第一版以手动表现录入为主，保留来源字段：
+
+- `source`: `manual` 或未来的 `adapter:<name>`
+- `window_label`
+- `metrics`
+- `feedback_summary`
+- `raw_reference`
+- `snapshot_at`
+
+## 与现有模型的关系
+
+### 文章优化
+
+现有 `article_jobs`、`fact_cards`、`optimized_articles`、`qa_reports` 和导出存储仍可作为文章优化的底层实现。
+
+第一版实现时建议引入统一案例元数据层，并让文章优化创建案例时关联现有 article job：
+
+- 新增统一案例记录。
+- `article_jobs` 关联 `case_id`。
+- `optimized_articles.revision` 对应文章案例的结果版本号。
+- `qa_reports` 继续按文章结果版本保存。
+- 现有导出路径继续作为文章结果版本的导出文件快照。
+
+这样可以避免一次性重写文章优化主链路。
+
+### 人味文案优化
+
+人味文案优化当前接口可以保留技术路由名 `POST /api/copy/renwei-optimize`，但产品文案统一使用“人味文案优化”。
+
+第一版要把一次性 API 改为自动创建案例：
+
+- 请求开始时创建 `human_copy` 案例。
+- 保存原始文案、优化目标、强度、补充要求和发布目标。
+- 成功后保存结果版本，包含优化后文案、修改说明、AI 味检查和 warnings。
+- 失败时保存失败案例和错误摘要。
+
+### 发布和效果
+
+当前发布记录以文章 job 和 revision 为核心。统一案例库需要把发布记录的业务语义提升为“绑定结果版本”。
+
+实现可以选择兼容迁移路径：
+
+- 为发布记录增加统一结果版本引用。
+- 文章旧字段保留兼容，逐步迁移到结果版本引用。
+- 新的人味文案发布记录直接绑定结果版本。
+
+效果快照继续绑定发布记录。
+
+## 页面设计
+
+### 入口
+
+新增 `案例库` 入口。
+
+案例库是一个工作台页面，不是营销页。默认展示案例列表。
+
+### 案例列表
+
+默认列：
+
+- 标题/摘要。
+- 案例类型。
+- 客户/品牌。
+- 项目标签。
+- 发布目标。
+- 状态。
+- 创建时间。
+- 最近更新时间。
+
+默认隐藏归档案例。
+
+搜索和筛选：
+
+- 关键词搜索：标题、原文摘要、结果摘要、客户、品牌、备注。
+- 筛选：案例类型、状态、发布目标、项目标签、创建时间。
+- 第一版不做完整全文搜索引擎和高亮。
+
+### 案例详情
+
+详情页采用共享头部 + 类型专属模块。
+
+共享头部：
+
+- 标题。
+- 案例类型。
+- 状态。
+- 客户/品牌。
+- 项目标签。
+- 备注。
+- 创建和更新时间。
+- 最新结果版本。
+- LLM 审计摘要概览。
+- 归档/恢复操作。
+
+共享区域：
+
+- 结果版本列表。
+- 发布记录。
+- 效果快照。
+- 校准结论。
+- 重新运行优化。
+
+文章优化专属模块：
+
+- 原文标题和正文。
+- 图片输入。
+- 目标平台和补充要求。
+- 事实卡。
+- 当前版本优化稿。
+- QA 报告。
+- 导出链接。
+
+人味文案专属模块：
+
+- 原始文案。
+- 优化目标。
+- 修改强度。
+- 补充要求。
+- 发布目标。
+- 优化后文案。
+- 修改说明。
+- AI 味检查。
+- warnings。
+
+失败案例详情：
+
+- 显示失败状态。
+- 显示失败阶段和错误摘要。
+- 显示原始输入和 LLM 审计摘要。
+- 不展示正式产物区。
+- 允许从失败案例重新运行优化，成功后生成新结果版本。
+
+## API 设计
+
+新增案例库 API：
+
+```text
+GET /api/cases
+GET /api/cases/:caseId
+PATCH /api/cases/:caseId
+POST /api/cases/:caseId/archive
+POST /api/cases/:caseId/restore
+POST /api/cases/:caseId/rerun
+```
+
+发布和效果 API：
+
+```text
+POST /api/cases/:caseId/versions/:versionId/publications
+GET /api/cases/:caseId/versions/:versionId/publications
+POST /api/publications/:publicationId/performance
+```
+
+现有文章优化接口继续保留，但需要在运行过程中自动创建和更新案例：
+
+```text
+POST /api/jobs/optimize-stream
+POST /api/jobs
+POST /api/jobs/:jobId/optimize
+```
+
+现有人味文案接口保留技术路径，但响应中增加案例信息：
+
+```text
+POST /api/copy/renwei-optimize
+```
+
+成功响应应包含：
+
+```json
+{
+  "case": {
+    "id": "case_xxx",
+    "case_type": "human_copy"
+  },
+  "result_version": {
+    "id": "ver_xxx",
+    "version": 1
+  },
+  "result": {}
+}
+```
+
+失败响应仍返回明确错误，同时案例库中留下失败案例。
+
+## 状态规则
+
+案例状态：
+
+- `running`：优化已开始但尚未完成。
+- `optimized`：至少有一个成功结果版本。
+- `failed`：当前运行失败且没有成功结果版本，或最近一次运行失败。
+- `archived`：从默认列表隐藏但仍保留记录。
+
+结果版本状态：
+
+- `optimized`：成功产出正式产物。
+- `failed`：本次运行失败，没有正式产物。
+
+如果一个已有成功版本的案例重新运行失败，案例仍保留历史成功版本；详情页提示最近一次运行失败。
+
+## 评分口径
+
+文章优化和人味文案优化使用不同评分口径。
+
+文章优化评分继续关注：
+
+- 事实一致性。
+- 平台适配。
+- 搜索意图匹配。
+- 答案密度。
+- 信任信号质量。
+- 可读性。
+
+人味文案优化评分新增独立口径，建议关注：
+
+- 改动克制。
+- 原意保真。
+- 语气自然度。
+- 目标匹配。
+- AI 味风险。
+- 互动或转化表现。
+
+发布记录和效果快照共用结构，但评分 run 必须记录自己的 rubric 版本。
+
+## 错误处理
+
+- API 访问密钥继续沿用现有 `x-api-key` 规则。
+- 案例创建失败时，本次优化应返回明确错误，不继续产生孤立结果。
+- LLM 失败时保存失败阶段和错误摘要。
+- schema 校验失败时保存校验摘要，不保存完整 response。
+- 导出文件写入失败时，文章案例可以保存结构化结果并标记导出失败。
+- 发布记录必须绑定存在的结果版本，否则返回 `409` 或 `404`。
+- 效果快照必须绑定存在的发布记录，否则返回 `404`。
+
+## 测试计划
+
+单元测试：
+
+- 案例类型校验接受 `article` 和 `human_copy`。
+- 案例元数据允许客户、品牌、项目标签和备注为空。
+- 人味文案结果校验包含优化后文案、修改说明、AI 味检查和 warnings。
+- LLM 审计摘要不包含完整 prompt/response。
+- 结果版本号重新运行时递增。
+
+Repository 测试：
+
+- 可以创建文章优化案例。
+- 可以创建人味文案优化案例。
+- 可以保存失败案例。
+- 可以保存多个结果版本并按版本倒序读取。
+- 发布记录绑定结果版本。
+- 效果快照绑定发布记录。
+- 归档案例默认不出现在普通列表。
+
+API 测试：
+
+- 文章优化成功后可以在案例列表查到。
+- 人味文案优化成功后可以在案例列表查到。
+- LLM 失败后可以查到失败案例。
+- `PATCH /api/cases/:caseId` 可以补录客户、品牌、项目标签和备注。
+- `POST /api/cases/:caseId/archive` 后默认列表隐藏该案例。
+- `POST /api/cases/:caseId/rerun` 生成新结果版本，不覆盖旧版本。
+
+组件测试：
+
+- 案例列表展示默认列。
+- 案例列表支持类型、状态、发布目标、项目标签和时间筛选。
+- 文章案例详情展示事实卡、QA、导出链接和效果学习入口。
+- 人味文案案例详情展示修改说明、AI 味检查和效果学习入口。
+- 失败案例详情展示失败阶段和错误摘要，不展示正式产物区。
+
+E2E 测试：
+
+- 完成一次文章优化后进入案例库，能打开详情并下载文章导出文件。
+- 完成一次人味文案优化后进入案例库，能打开详情并查看修改说明。
+- 给案例补项目标签和备注后，列表可搜索或筛选到。
+- 从详情页重新运行优化后出现新结果版本。
+- 为某个结果版本录入发布记录和手动效果快照后，详情页显示效果学习信息。
+
+验证命令：
+
+```bash
+npm run lint
+npm test
+npm run build
+```
+
+## 迁移策略
+
+第一步先服务新产生的案例，不要求立即迁移所有旧数据。
+
+推荐顺序：
+
+1. 增加统一案例元数据和结果版本能力。
+2. 让文章优化新请求自动创建案例，并关联现有 article job。
+3. 让人味文案优化新请求自动创建案例和结果版本。
+4. 增加案例列表和详情页。
+5. 将发布记录和效果快照入口接到结果版本。
+6. 再评估是否需要把历史 `article_jobs` 批量补成案例。
+
+历史数据迁移可以延后，因为当前主要目标是让后续运行不再丢失长期资产。
+
+## 不做范围
+
+- 不做账号、角色和权限。
+- 不做平台 API 自动采集。
+- 不做人味文案导出文件快照。
+- 不默认保存完整 prompt/response。
+- 不做全文搜索引擎。
+- 不做硬删除。
+- 不把失败案例当作正式产物。
+- 不把两类案例强行合并为同一套评分口径。