# 一键流式优化主流程设计

## 目标

把当前 GEO 文章优化主流程从“分析文章 -> 确认事实卡 -> 开始优化”改成“一键开始优化”。用户只需要粘贴完整文章并点击开始，系统自动提取事实卡、生成草稿、检查质量、定向修复并产出终稿。

第一版要让优化结果区像主流 LLM 产品一样持续有反馈，但不做 token 级逐字模型流。真实内容以阶段事件形式到达，前端负责用光标、呼吸高亮和打字机播放已到达内容来制造流式感。

## 范围

本设计覆盖现有 GEO 主流程，不改变普通文案优化标签页设计，不引入批量任务、团队审批、发布平台 API 或多品牌事实库。

本设计覆盖并替代旧 MVP 设计中“必须确认事实卡后才能优化”的主路径要求。旧的确认接口和非流式优化接口可以暂时保留为兼容和调试入口，但新首页主路径不再依赖它们。

## 用户流程

```mermaid
flowchart TD
  A["粘贴完整文章"] --> B["点击开始优化"]
  B --> C["后端创建任务并提取事实卡"]
  C --> D["事实卡区展示紧凑事实卡"]
  C --> E["结果区进入生成中状态"]
  E --> F["显示优化草稿"]
  F --> G["质量检查"]
  G --> H{"需要定向修复?"}
  H -->|是| I["显示修复中状态并更新稿件"]
  I --> J["显示终稿"]
  H -->|否| J
  D --> K["用户可编辑事实卡"]
  K --> B
```

## 输入体验

文章输入取消标题和正文的强制区别。

- 主输入改成一个大文本框，标签为 `粘贴文章`。
- `body` 仍是唯一必填内容。
- `title` 可空，放到“更多选项”里作为可选输入。
- 如果标题为空，后端把 `title` 规范化为空字符串并保存；不从正文首行派生内部标题。最终优化结果仍必须返回标题。
- 图片描述、目标平台、用户要求保持现有能力。

用户点击 `开始优化` 后，前端清空旧结果，进入流式读取状态。

## 事实卡体验

事实卡仍然是独立事实卡区，不放进进度区。

事实卡区缩小为紧凑展示面板：

- 默认展示公司全称或简称、产品/品牌、目标行业、目标受众、核心事实数量、待确认事项数量。
- `uncertain_items` 不再阻塞优化，而是以黄色提示展示。
- 用户可以展开编辑完整事实卡字段。
- 用户编辑事实卡后，再次点击 `开始优化`，使用当前事实卡重新跑一次优化。

第一版重新优化建议创建新 job，而不是覆盖原 job 的事实卡和导出结果。这样历史语义清楚，避免旧导出和新事实卡互相污染。

## 结果区流式感

结果区采用“草稿到终稿”的路线。

开始后立即显示动态结果框：

- 顶部显示当前阶段：`正在提取事实`、`正在生成草稿`、`正在检查质量`、`正在定向修复`、`终稿完成`。
- 内容区显示空白稿纸、骨架段落和动态光标。
- 等待真实内容时，可以让光标旋转或跳动，让当前段落轻微呼吸高亮。
- 收到真实草稿后，前端用打字机效果播放已到达的草稿内容。
- 进入 QA 或修复阶段时，结果区保留当前稿件，并对正在处理的段落做呼吸高亮。
- 收到修复稿后，更新稿件内容，并可短暂高亮被替换的段落。
- 收到终稿后停止动效，展示终稿、导出链接和 QA 报告。

前端可以展示状态提示和骨架文本，但不能凭空生成正文内容伪装成模型输出。所有正文、标题、摘要、修复稿和终稿必须来自后端真实事件。

## API 设计

新增流式一键接口：

```text
POST /api/jobs/optimize-stream
```

该接口使用 `fetch` + `ReadableStream`，不使用浏览器原生 `EventSource`。原因是当前项目通过 `x-api-key` 传递访问密钥，`fetch` 可以继续安全地发送请求头。

请求头继续使用现有访问控制：

```text
x-api-key: <访问密钥>
content-type: application/json
```

请求体：

```json
{
  "title": "",
  "body": "完整文章内容",
  "image_lines": "",
  "platform": "official_site",
  "user_instructions": "",
  "fact_card": null
}
```

`fact_card` 为可选字段。为空时后端从文章提取事实卡；有值时表示用户编辑过事实卡，本次优化直接使用传入事实卡。

## 流式事件

响应采用 newline-delimited JSON，每行一个事件：

```json
{"type":"job_created","job":{"id":"job_xxx"}}
{"type":"fact_card_ready","job_id":"job_xxx","fact_card":{}}
{"type":"draft_started","job_id":"job_xxx","message":"正在生成优化草稿"}
{"type":"draft_ready","job_id":"job_xxx","article":{}}
{"type":"qa_started","job_id":"job_xxx","message":"正在检查质量"}
{"type":"qa_ready","job_id":"job_xxx","qa_report":{}}
{"type":"rewrite_started","job_id":"job_xxx","round":1}
{"type":"rewrite_ready","job_id":"job_xxx","round":1,"article":{}}
{"type":"final_ready","job_id":"job_xxx","optimized_article":{},"qa_report":{},"export_paths":{}}
```

失败事件：

```json
{"type":"failed","job_id":"job_xxx","stage":"draft","error":"LLM provider error: ..."}
```

事件规则：

- `fact_card_ready` 只更新事实卡区。
- `draft_ready`、`rewrite_ready`、`final_ready` 更新优化结果区。
- `qa_started`、`rewrite_started` 更新结果区状态和动效，不生成正文。
- `failed` 保留已经收到的事实卡或草稿，并显示失败阶段和真实错误。

## 后端编排

后端按以下顺序执行：

1. 校验访问密钥。
2. 校验输入，`body` 不能为空，`title` 可以为空。
3. 创建 article job。
4. 如果请求带 `fact_card`，解析并保存该事实卡；否则调用事实卡提取器。
5. 推送 `fact_card_ready`。
6. 调用文章优化器生成草稿，推送 `draft_ready`。
7. 调用质量检查器，推送 `qa_ready`。
8. 如果 QA 有失败项，最多执行现有定向修复轮次，并推送 `rewrite_started` / `rewrite_ready`。
9. 保存最终优化稿、QA 报告和导出文件。
10. 推送 `final_ready`。

新增一个流式 workflow wrapper，复用 `optimizeArticle`、`inspectQualityWithLlm`、`rewriteFailedSections` 和导出逻辑。现有 `runOptimizationWorkflow` 保留给非流式兼容接口，避免一次改动同时重塑两条 API 路径。

## 数据模型调整

`ArticleInput.title` 和 `articleInputSchema.title` 需要允许空字符串。

事实卡保存需要支持“未人工确认但可作为本次优化约束”的状态。第一版新增 `OptimizationFactCard`，并把 repository 的 `saveFactCard` / `getFactCard` 类型从 `ConfirmedFactCard` 放宽到 `OptimizationFactCard`。`OptimizationFactCard` 保留 `confirmed_by_user?: boolean`，避免继续把“系统自动事实卡”伪装成“用户确认事实卡”。

`confirmedFactCardSchema` 可以保留给旧确认接口；新流式接口使用新的 `optimizationFactCardSchema`。

## 错误处理

- 空正文：返回中文错误 `请输入需要优化的文章内容`。
- 访问密钥缺失或错误：沿用现有 `401`。
- LLM/provider 错误：推送 `failed`，显示真实错误，不静默 fallback。
- LLM 结构校验失败：推送 `failed`，保留阶段和校验摘要。
- 事实卡公司名、行业或受众为空：允许继续优化，但事实卡区提示约束不足，QA 中体现事实风险。
- `uncertain_items` 不阻塞优化，只作为事实卡区提示和 QA 风险信息。
- 用户中途再次点击开始优化：前端应中断当前 stream，清空旧动效，创建新优化请求。

## 前端状态

首页主状态新增：

- `streamStatus`: idle | running | completed | failed
- `streamStage`: 当前阶段标签
- `streamError`: 失败文本
- `displayedDraft`: 结果区正在播放或展示的稿件
- `finalArticle`: 终稿
- `factCardExpanded`: 事实卡是否展开

结果区组件负责：

- 解析阶段文章。
- 播放打字机效果。
- 展示光标和呼吸高亮。
- 在终稿到达后停止动效。

页面级组件负责：

- 发起 stream 请求。
- 读取 NDJSON。
- 将事实卡事件分发给事实卡区。
- 将稿件事件分发给结果区。
- 处理中断和失败。

## 兼容策略

保留现有接口：

- `POST /api/jobs`
- `POST /api/jobs/:jobId/confirm-fact-card`
- `POST /api/jobs/:jobId/optimize`
- `GET /api/jobs/:jobId/progress`

新首页主流程改用 `POST /api/jobs/optimize-stream`。旧接口可以继续服务测试、调试或未来非流式降级路径。

## 测试计划

单元测试：

- `articleInputSchema` 接受空标题但拒绝空正文。
- 新 `optimizationFactCardSchema` 接受未确认事实卡和非空/空的可编辑字段。
- NDJSON 编码 helper 可以按行输出合法 JSON。

API 测试：

- 未提供访问密钥返回 `401`。
- 空正文返回中文错误。
- 无 `fact_card` 时会调用事实卡提取器，并输出 `job_created`、`fact_card_ready`、`draft_ready`、`qa_ready`、`final_ready`。
- 有 `fact_card` 时跳过事实卡提取器，直接使用传入事实卡。
- LLM 失败时输出 `failed`，错误包含阶段。
- QA 失败时仍写导出文件，并通过修复事件展示修复轮次。

组件测试：

- 开始优化后结果区显示动态光标和阶段文案。
- 收到 `draft_ready` 后打字机播放真实草稿。
- 收到 `rewrite_ready` 后结果区更新稿件并高亮变化。
- 收到 `final_ready` 后停止动效并显示导出链接。
- `fact_card_ready` 更新紧凑事实卡区，不进入进度区。

E2E 测试：

- 用户只粘贴正文，点击 `开始优化`。
- 页面显示事实卡小面板。
- 优化结果区出现动态状态和草稿。
- 最终显示终稿、QA 报告和导出链接。
- 用户展开并编辑事实卡后，再次点击 `开始优化` 可以开始新一轮流式优化。

## 不做范围

- 不做 token 级模型逐字输出。
- 不把事实卡放进进度区。
- 不要求用户确认事实卡后才能优化。
- 不用前端伪造正文内容。
- 不移除旧 API。
- 不新增团队审批、批量队列或发布平台 API。