# AI详情生成开发文档（当前实现版）

## 1. 文档定位

本文档不再描述理想中的完整目标架构，而是基于当前仓库代码与前端交互，整理出一份可直接用于开发、联调、排查和运营说明的“当前实现版”文档。

适用范围：

- 无限画布中的 `AI详情生成工作台`
- 前端入口与交互流程
- 当前已接入的后端 API
- `classic` 与 `agent_layout` 两种模式的真实差异
- 已上线能力、未上线能力、已知限制

如果后续要继续推进“项目化管理 / Layout QA / 14屏严格状态机 / 项目级 API”，请在本文件基础上新增“规划版”文档，不要再把目标方案和当前实现混写。

---

## 2. 状态说明

本文档中的状态标签含义如下：

- `已实现`：仓库中已有入口和主要逻辑，当前系统可走通
- `部分实现`：已有部分链路，但与原设计稿不完全一致
- `未实现`：文档中仅保留为后续规划，不应视为当前能力

---

## 3. 当前能力总览

### 3.1 功能入口 `已实现`

- 入口位置：无限画布右侧聊天工作台中的 `AI详情生成`
- 前端主文件：`components/canvas/CanvasChatPanel.tsx`
- 用户可以选择两种模式：
  - `classic`：传统生图
  - `agent_layout`：AGENT排版

### 3.2 当前真实输入约束 `已实现`

必填业务字段：

- `targetAudience`
- `usageScenario`
- `coreNeed`

当前前端强制素材要求：

- `5` 张产品图：必填
- `1` 张模特图：当前实现中必填
- `0-3` 张搭配图：可选

说明：

- 文档层面原本把模特图写成“可用于卖家视角场景”，但当前前端实现里它实际上是必填项。
- 如果没有模特图，前端会直接拦截，不会进入 AI 详情规划。

### 3.3 当前真实输出结构 `已实现`

当前 AI 详情一次生成的输出由两部分组成：

1. `详情主图分镜`
   - 通过 `/api/canvas/detail-plan` 先规划
   - 再逐屏调用生图接口

2. `买家评价与晒单`
   - 在主图全部完成后由前端追加生成
   - 不属于 `detail-plan` 主分镜返回本体

---

## 4. 当前系统里的真实流程

### 4.1 主流程概览 `已实现`

当前系统实际流程如下：

```mermaid
flowchart LR
    A["用户填写brief并上传素材"] --> B["前端校验必填字段和素材"]
    B --> C["POST /api/canvas/detail-plan"]
    C --> D["返回 screens/prompts/globalStyle/preflight"]
    D --> E["前端逐屏调用生图"]
    E --> F{"generation_mode"}
    F -->|classic| G["逐屏 detail-review 质检 + 可选二次修图"]
    F -->|agent_layout| H["前端叠加可编辑文字层"]
    G --> I["主图完成后追加评价晒图"]
    H --> I
    I --> J["写入画布节点 + 更新本地/数据库存档"]
```

### 4.2 关键特点

- 当前没有“项目级任务状态机 API”
- 当前没有后端统一的 `/detail-projects/:projectId/generate`
- 当前没有 SSE 进度接口
- 进度条、占位图、逐屏生成状态全部在前端本地维护

---

## 5. 两种模式的真实差异

## 5.1 `classic` 传统生图模式 `已实现`

特点：

- 生图模型直接生成整页详情图
- 提示词中会带标题、副标题、正文、FABE、排版说明
- 每屏生成后会调用 `/api/canvas/detail-review`
- 如果质检不通过，会基于 `revisedPrompt` 二次修图一次

优点：

- 成图速度快
- 页面信息一次成型

限制：

- 文生图模型对文字和排版控制不稳定
- 容易出现文字失真、布局漂移、参数被画出来等问题

## 5.2 `agent_layout` AGENT排版模式 `已实现`

特点：

- 生图模型只生成画面层
- 明确禁止模型输出可见文字、数字、Logo、水印
- 画面生成完成后，前端在图片节点上叠加 3 个可编辑文字节点：
  - 标题
  - 副标题
  - 正文

当前文字层位置：

- 标题：`y + 72`
- 副标题：`y + 214`
- 正文：`y + 304`
- 左边距：约画面宽度的 `7%`

优点：

- 文字可编辑
- 文案层级更统一
- 避免模型把整页文字烤死

限制：

- 当前文字层位置是前端固定模板，不是后端程序化版式引擎
- 当前 `agent_layout` 不走 `/api/canvas/detail-review`
- 当前没有“文字遮挡主体”的自动检测

---

## 6. 屏数与完成条件

### 6.1 当前真实规则 `已实现`

当前主图分镜数不是固定 14 屏，而是动态值：

- 前端会从用户输入文本里解析 `X张 / X屏 / X页`
- 如果没解析到，默认 `14` 屏
- 后端会把数量限制在 `5-20`
- 如果上传了搭配图，会额外加 `1` 屏搭配展示

### 6.2 当前真实完成条件 `已实现`

当前“完成”并不是“必须满 14 屏”，而是：

- 本次 `detail-plan` 返回了多少条 `prompts`
- 前端就按多少屏去生成
- 当 `generatedImages.length === prompts.length` 时，主图阶段视为完成

### 6.3 评价晒图的关系 `已实现`

买家评价与晒单是主图完成后的追加产物：

- 默认追加 `3` 条评价方案
- 每条评价生成 `3` 张晒单图
- 不计入主图 `prompts.length`

---

## 7. 当前接口清单

## 7.1 已上线接口

### 1. `POST /api/canvas/detail-plan` `已实现`

作用：

- 生成 AI 详情规划结果
- 返回：
  - `summary`
  - `prompts`
  - `globalStyle`
  - `skillFlow`
  - `qualityChecks`
  - `preflight`
  - `screens`
  - `generationMode`

输入重点：

- `prompt`
- `count`
- `generationMode`
- `referenceImages`
- `referenceImageNotes`
- `modelImageUrl`
- `bundleImageUrls`
- `brief`

### 2. `POST /api/canvas/detail-review` `已实现`

作用：

- 对已经生成的单屏整页图做双总监质检
- 仅在 `classic` 模式下调用

返回重点：

- `pass`
- `score`
- `designDirectorScore`
- `marketingDirectorScore`
- `issues`
- `layoutFixes`
- `revisedPrompt`

### 3. `GET|POST|PATCH|DELETE /api/canvas/[id]/detail-archives` `已实现`

作用：

- 详情生成历史归档
- 读取、保存、更新、删除历史详情项目快照

说明：

- 当前系统使用的是“归档快照”而不是“项目型任务管理”
- 实际归档里会保存：
  - prompt
  - generationMode
  - brief
  - slots
  - summary
  - coverUrl
  - imageCount

## 7.2 文档里曾规划但当前未上线的接口

以下接口在旧文档中出现过，但当前仓库未实现，不应视为现有能力：

- `POST /api/canvas/[id]/detail-projects`
- `GET /api/canvas/[id]/detail-projects`
- `GET /api/canvas/[id]/detail-projects/:projectId`
- `POST /api/canvas/[id]/detail-projects/:projectId/generate`
- `POST /api/canvas/[id]/detail-projects/:projectId/retry-screen`
- `GET /api/canvas/[id]/detail-projects/:projectId/progress`
- `POST /api/canvas/[id]/generation-mode`

状态：`未实现`

---

## 8. 当前真实数据与存储方式

### 8.1 当前真实存档模型 `已实现`

当前 AI 详情不是独立的 `detail_projects` 体系，而是基于：

- `canvasProject`
- `canvasDetailArchive`

来做归档和归属校验。

### 8.2 当前未实现的数据设计

以下是旧文档中规划过、但当前代码未接入的数据表概念：

- `detail_projects`
- `detail_project_inputs`
- `detail_assets`
- `detail_screen_specs`
- `detail_screen_renders`
- `detail_generation_jobs`

状态：`未实现`

---

## 9. 当前规划结果的数据结构

当前 `/api/canvas/detail-plan` 返回的每屏结构重点如下：

```ts
type DetailPlanScreen = {
  index: number;
  screenType: "A" | "B" | "C";
  objective: string;
  title: string;
  subtitle: string;
  copy: string;
  layoutNote: string;
  useModel: boolean;
  modelReason: string;
  bundleShowcase: boolean;
  bundleReason: string;
  visualPrompt: string;
  fabe: {
    b: string;
    f: string;
    a: string;
    e: string;
  };
};
```

说明：

- 当前虽然返回 `screens`，但这不是旧文档中那个完整的可编辑 `ScreenSpec` 协议
- 真实落地时，前端主要使用：
  - `visualPrompt`
  - `title`
  - `subtitle`
  - `copy`
  - `layoutNote`
  - `screenType`

---

## 10. 当前前端交互与画布落位

### 10.1 占位与落位 `已实现`

- 生成前先在画布中创建纵向占位图节点
- 每个节点尺寸固定 `790x1300`
- 纵向排列
- 占位图会显示当前状态：
  - 需求解析与分镜规划中
  - 分镜规划完成
  - 双总监预审通过
  - 主图首稿生成中
  - 排版层渲染中
  - 生成失败

### 10.2 `agent_layout` 文字叠加 `已实现`

画面生成完成后，前端会自动叠加文字节点：

- 标题：大字号、粗体
- 副标题：中字号、中高权重
- 正文：较小字号、灰阶色

当前是模板化坐标，不是自适应排版引擎。

### 10.3 手动编辑 `部分实现`

当前可编辑能力：

- 可直接在画布中改文字
- 图片节点可继续操作

当前未实现或未证实完整上线：

- 图标层体系
- 独立排版吸附策略
- 通过“保留版式仅重生画面”的专门 UI 按钮

---

## 11. 当前质检与兜底机制

## 11.1 分镜预审 `已实现`

`detail-plan` 在规划后会做一次“平面设计总监 + 营销总监”预审：

- 返回 `preflight`
- 包含：
  - `designDirectorScore`
  - `marketingDirectorScore`
  - `issues`
  - `rewriteApplied`

如果预审不理想，会优先尝试重写方案；仍不理想则回退到稳定模板。

## 11.2 单屏质检 `部分实现`

仅 `classic` 模式下：

- 每屏首稿完成后调用 `/api/canvas/detail-review`
- review 不通过时，会用 `revisedPrompt` 二次修图一次

`agent_layout` 模式下：

- 当前不走这套逐屏 review 流程

## 11.3 当前实际不存在的质检能力

以下内容在旧文档里有描述，但当前代码中未实现：

- `product_mask`
- `saliency_map`
- 遮挡率计算
- 文本对比度计算
- `qa_passed / qa_score / qa_issues / qa_fix_actions`
- 质检报告面板

状态：`未实现`

---

## 12. 当前失败与回退策略

### 12.1 已实现回退

1. `detail-plan` 超时或失败时
- 带参考图失败，先去掉参考图重试
- 仍失败，回退到 fallback 分镜模板

2. `detail-review` 失败时
- 保留当前屏结果
- 不会整套中断

3. 生图失败时
- 逐屏抛错
- 若最终成功屏数不等于计划屏数，则本轮主图任务报错

### 12.2 当前线上已观察到的问题

- `detail-plan` 经常 `generateText timed out after 45000ms`
- `preflight` 偶发 `10000ms` 超时
- 火山视觉兜底存在 `size` 参数不合法问题
- 火山视觉会因输入图超过 `10MB` 报错
- 当前日志对 `generationMode` 的显式记录不够

---

## 13. 当前性能与运维现状

### 13.1 已实现策略

- 参考图会先做可达性检查
- 规划阶段对内联图片数量有限制
- 规划超时和参考图失败会自动降级

### 13.2 当前真实瓶颈

- 规划模型 45 秒超时较常见
- 智能分析链路和 AI 详情共用资源时，容易放大整体超时概率
- 服务器高负载时，详情规划失败概率明显上升

---

## 14. 当前实现与旧文档差异总结

以下是最容易误导的几个点：

1. 不是“固定 14 屏严格状态机”
- 实际是动态屏数，默认 14，可在 `5-20` 之间浮动

2. 不是“项目型 API 架构”
- 实际是 `detail-plan + detail-review + detail-archives`

3. 不是“模特图可选”
- 实际前端要求模特图必填

4. 不是“Layout QA 已上线”
- 实际只有 LLM 预审和 classic 单屏 review

5. 不是“所有模式都逐屏质检”
- 实际 `agent_layout` 跳过 `/detail-review`

---

## 15. 推荐的下一步迭代顺序

基于当前系统现状，建议优先做这些“短路径、可落地”的改动：

### 第一阶段：修稳定性

- 在日志中显式打印 `generationMode`
- 降低 `detail-plan` 规划超时概率
- 修复火山视觉 `size` 参数映射
- 生图前压缩超大参考图

### 第二阶段：修文档与能力一致性

- 让模特图是否必填与产品策略一致
- 明确“主图屏数”和“评价晒单”之间的边界
- 把当前档案型接口正式定义清楚

### 第三阶段：增强 `agent_layout`

- 把前端固定文字坐标升级为可配置模板
- 让 `agent_layout` 也支持可控的逐屏质量检查
- 增加更明确的排版冲突规避策略

### 第四阶段：再考虑项目化

- 如需真正的 `detail-projects` / `progress` / `retry-screen` / `generation-mode` API，再单独设计
- 不建议在当前文档里继续把它们写成“已经存在的系统能力”

---

## 16. 代码入口索引

当前 AI 详情的主要代码入口如下：

- 前端工作台：`components/canvas/CanvasChatPanel.tsx`
- 详情规划：`app/api/canvas/detail-plan/route.ts`
- 详情质检：`app/api/canvas/detail-review/route.ts`
- 详情存档：`app/api/canvas/[id]/detail-archives/route.ts`

---

## 17. 结语

当前 AI 详情功能已经具备“可用”的主链路：

- 可规划
- 可逐屏生图
- 可归档
- 可区分 `classic` 与 `agent_layout`
- 可追加评价晒单

但它还不是旧文档里描述的完整项目化系统。

后续所有开发、测试、运营说明，建议以本文件为准；如果要继续推进目标架构，请新开“规划版”文档，不再修改本文件的“当前实现事实”定位。