# 《先马 AI 设计平台｜AI 商详焕新及本期关联功能优化｜V1.2 PRD》

## 0. 文档信息

| 项目 | 内容 |
|---|---|
| 所属平台 | 先马 AI 设计平台 |
| 本期模块 | AI 商详焕新 / AI 买家秀 / 主体替换 / 商品选择公共能力 / AI 多角度 / AI 视频素材尺寸预处理 / 素材库与提示词库导航 / 素材库图片自动识别命名 |
| 需求类型 | 新增 / 优化 / Bug 修复 |
| 文档版本 | V1.2 |
| 产品规则状态 | 已确认，产品侧待确认项为无 |
| 原型状态 | AI 商详焕新、AI 买家秀、主体替换、商品选择器、AI 多角度斜角编辑、素材库图片自动识别命名已有定稿前端原型；资源导航和 AI 多角度比例修复待同步；AI 视频流与无限画布沿用既有视频生成流程 |
| 开发状态 | 素材库主动上传识别与工作台快捷入库命名契约已完成脱敏演示数据驱动的本地前端原型；真实识别模型、跨入口素材服务、字段映射和埋点待技术评审与开发；其余模块状态沿用 V1.0，不代表已部署或上线 |
| 需求来源 | 用户本轮确认、用户反馈；无独立 REQ 编号 |
| 关键事实源 | 商品智库 MVP 规则；当前各功能原型；用户 2026-09-15 确认的素材库图片自动识别命名方案；`xianma_detail_refresh` Skill；2026-09-14 双模式真实生成测试与 R-03 单图复测报告；《先马 AI 设计平台埋点需求 PRD V1.0》（2026-07-27）；《埋点与效果衡量》功能地图；《数据智能报表 PRD》后续口径 |
| 对应入口 | `/ai-hub/detail-refresh`；`/ai-hub/buyer-show`；`/image-tools/subject-replace`；`/ai-hub/multi-angle`；`/ai-hub/video-stream`；`/ai-canvas`；`/materials`；顶部“素材库/提示词库”导航 |
| 文档日期 | 2026-09-11（2026-09-15 更新） |

### 修订记录

| 版本 | 日期 | 修订内容 |
|---|---|---|
| V1.0 | 2026-09-14 | 形成 AI 商详焕新及本期关联功能优化的首版开发基线。 |
| V1.1 | 2026-09-15 | 新增素材库新上传图片自动识别命名模块；补充命名规则、AI 契约、逐图采纳、失败回退、跨页面影响、埋点、验收与回滚边界；不新增 REQ。 |
| V1.2 | 2026-09-15 | 删除图片批量默认类目/标签；工作台本地上传勾选“同时加入个人素材”时改为后台自动识别并直接应用，不阻塞当前任务；AI 生成结果加入素材库仍不重复识别。 |

### 变更摘要

#### 1. AI 商详焕新｜新增

上传一组商品详情页图片，生成一组主体准确、细节焕新且组内视觉统一的详情图。

1. **双模式焕新**：支持“主体不变、细节焕新”和“主体替换、细节焕新”，分别锁定原商品或新商品为唯一商品事实源。
2. **多来源替换商品**：可从商品智库、素材库或本地图片提供替换商品；多来源冲突时以商品智库已确认版本为准。
3. **整组质量门禁**：AI 自动建立首张风格锚点并检查商品、贴合、文案、图片角色和组级一致性；失败单图最多自动重试 3 次，只向平台返回合格图片或失败状态。
4. **结果闭环**：支持单图重试、单图微调、认可/待调整、单张下载和整组下载；下载、积分、权限与历史记录沿用平台现有规则。

#### 2. AI 买家秀｜优化

在原有图片、品类和场景流程中增加商品智库商品选择，让运营直接复用已确认商品资料生成买家秀。

1. **选择商品**：在“商品与场景”区域增加可选商品入口，选择后自动带出商品智库标准品类和商品确认图。
2. **兼容原流程**：选商品后仍可补充手动参考图并独立选择场景；不选商品时保留原图片队列、品类和场景流程。
3. **联动与留痕**：切换品类时清空旧场景；任务提交时保存所选商品确认版本快照。

#### 3. 主体替换｜优化

增加商品智库商品作为独立替换主体来源，减少重复上传商品参考图，同时保留原有手动参考图流程。

1. **双来源流程**：选商品时只要求至少 1 张待替换原图，仍可补充手动主体参考图；不选商品时沿用“原图 + 至少 1 张主体参考图”。
2. **队列边界**：商品确认图不固定插入图片队列第 2 位；清除商品不删除用户手动上传的参考图。
3. **任务留痕**：任务提交时保存商品确认版本快照，商品后续变化不影响历史任务。

#### 4. 商品选择公共能力｜新增

AI 买家秀、主体替换和 AI 商详焕新统一复用同一商品选择能力，保持商品范围、状态和权限口径一致。

1. **统一入口能力**：支持个人、团队、公共商品库 Tab，以及商品名称/来源搜索和商品品类筛选。
2. **统一选择资格**：仅展示当前用户可见、状态为已确认且存在有效确认版本的商品。
3. **统一回填结果**：向各工作台返回商品基础信息、标准品类、有效确认图和确认版本，用于页面回填与任务快照。

#### 5. AI 多角度｜优化 / Bug 修复

允许运营编辑四个斜方向的近似角度，并保证多角度结果继承输入图片宽高比。

1. **斜角可编辑**：左前、右前、左后、右后支持在 `0°–90°` 内按 `5°` 步进编辑；正面、背面、左侧、右侧保持固定。
2. **会话与提示词**：角度修改仅当前页面会话生效，恢复默认回到 `45°` 且不改变选中状态；提交时固化显示名称、实际方位角、英文角度提示词和完整提示词。
3. **比例继承**：最终结果必须继承输入图宽高比；输入为 `4:3` 时所有多角度结果均为 `4:3`，不得被默认参数改为 `1:1`。

#### 6. 素材库 / 提示词库导航｜优化

从创作页面进入素材库或提示词库时在新标签页打开，避免原标签页跳转导致进行中的创作内容或任务上下文丢失。

1. **新标签页打开**：顶部全局导航中的“素材库”“提示词库”改为新标签页打开，当前创作页保持不变。
2. **范围边界**：工作台内的素材选择器、提示词选择器继续使用现有弹窗，不改为新标签页。
3. **失败保护**：浏览器阻止新标签页时，不得回退为当前页跳转或清空当前任务。

#### 7. AI 视频素材尺寸预处理｜新增

在 AI 视频流和无限画布调用海螺 H3、Seedance 2、Seedance 2.5 前自动适配小尺寸图片，确保图片输入满足模型最小尺寸要求，同时保留用户原图。

1. **统一预处理**：覆盖 AI 视频流参考图/首帧图/首尾帧图和无限画布视频生成素材；图片宽或高小于 300px 时，等比放大至短边 512px。
2. **格式与大小处理**：使用双线性插值，保持 JPG、PNG、WEBP 格式；放大后超过单张 30MB 时自动压缩至模型限制内。
3. **原图与提示**：处理图仅用于模型调用，不覆盖原图；被放大的图片在缩略图旁显示非阻塞提示，未放大的图片不显示。
4. **比例边界**：保持原始宽高比，不裁剪；比例超出 0.4–2.5 时仍按原比例传递，由模型侧处理或返回错误。

#### 8. 素材库图片自动识别命名｜新增

为新入库图片提供结构化识别命名：素材库主动上传支持逐张或全部采纳，工作台顺带入库自动应用，并在识别失败时保留原文件名继续入库。

1. **双入口识别**：`/materials` 新上传图片进入可采纳识别；工作台本地图片勾选“同时加入个人素材”后进入后台自动识别，不阻塞当前任务。
2. **建议与采纳**：每张图片展示建议名称、类目和标签，支持单张采纳与全部采纳；全部采纳跳过失败项和人工修改项。
3. **单张最终字段**：图片不再显示批量默认类目和标签；未采纳或失败图片保留系统默认值并可单张编辑，视频和音频继续使用统一设置。
4. **命名与回退**：名称按结构化槽位和可用序号生成，最长优先控制在 20 字；失败时保留原文件名、默认类目和空标签，不阻断上传或当前工作台任务。
5. **边界不变**：AI 生成结果和历史结果的“加入素材库”沿用结果名称，不重复识别；权限、审批、共享、备注和积分规则不变。

## 1. 本期目标与范围

### 1.1 背景与目标

- AI 商详焕新解决逐张重做周期长、组图风格不统一及商品信息失真的问题，输出数量、顺序、角色和尺寸与输入对应的一组可用详情图。
- AI 买家秀、主体替换和 AI 商详焕新复用商品智库已确认商品，减少重复上传并统一商品事实来源。
- AI 多角度允许调整四个斜方向的近似角度，并修复输入 `4:3`、输出变为 `1:1` 的比例错误。
- AI 视频流和无限画布调用指定视频模型时，自动处理不满足最小尺寸要求的图片，避免小图输入失败。
- 素材库和提示词库从顶部导航新标签页打开，避免误操作造成创作上下文丢失。
- 素材库主动上传图片在入库前获得可编辑的名称、类目和标签建议；工作台本地图片顺带入库时后台自动完成同类命名，减少跨场景素材整理成本，并保留失败图片可入库的兜底路径。

### 1.2 范围矩阵

| 模块 | 本期动作 | 用户结果 | 原型状态 | 待开发内容 | 编号前缀 |
|---|---|---|---|---|---|
| AI 商详焕新 | 新增 | 输出组内统一且主体准确的详情组图 | 前端交互原型已定稿 | AI 内部生成、质检、重试、真实任务与快照 | `DR` |
| AI 买家秀 | 优化 | 可直接选择已确认商品 | 前端原型已定稿 | 真实商品接口、权限与任务快照 | `BS` |
| 主体替换 | 优化 | 商品智库成为独立主体来源 | 前端原型已定稿 | 真实商品接口、权限与任务快照 | `SR` |
| 商品选择公共能力 | 新增 | 三个工作台使用相同商品范围和资格 | 公共组件原型已定稿 | 真实商品服务、权限鉴权、快照契约 | `PP` |
| AI 多角度 | 优化 / Bug 修复 | 斜角可编辑，结果比例继承输入 | 斜角交互原型已定稿 | 生成请求比例传递与结果文件校验 | `MA` |
| AI 视频素材尺寸预处理 | 新增 | 视频模型调用前自动适配小尺寸图片，避免尺寸不足失败 | AI 视频流、无限画布既有流程 | 统一图片预处理、模型入参接入、原图保护 | `VP` |
| 资源库导航 | 优化 | 新标签页打开，不打断创作 | 待同步 | 顶部导航行为与浏览器阻止场景 | `NAV` |
| 素材库图片自动识别命名 | 新增 | 主动上传可确认建议，工作台顺带入库自动命名 | 本地前端原型已定稿 | 真实识别模型、跨入口素材服务、字段映射与埋点 | `MN` |

### 1.3 本次不做

- 不做历史图片库或跨商品链接相似度比对，不承诺与历史图片完全不重复。
- 不支持同一组详情图替换多个商品或混入多个商品主体，不做跨商品批量任务和自动发布。
- 不新增风格模板市场、变化强度或风格方向控件。
- 不改变 AI 买家秀既有微调交互。
- 不改变 AI 多角度既有模型、质量档位、至少 2 个和最多 8 个角度的选择规则；不持久化个人角度预设。
- 不改变素材库、提示词库的权限、审批、共享规则和工作台内选择弹窗；素材库上传弹窗按本期 MN 模块增强。
- 不将前端演示数据或原型状态描述为真实生成接口已上线。
- 不做 AI 超分、裁剪或改变用户原图；预处理只服务三个指定视频模型的模型调用入参。
- 素材命名不处理存量素材，不识别视频或音频，不新增后台词表、多命名模板、CSV、置信度分级、模型选择，也不重新识别 AI 生成结果或历史结果的“加入素材库”。

## 2. AI 商详焕新

### 2.1 问题、目标与当前基线

| 项目 | 当前状态 | 本期目标 | 事实来源 |
|---|---|---|---|
| 详情组图换新 | 当前批量改图使用统一提示词逐张处理，不能保证详情角色和组级风格 | 生成同数量、同顺序、角色对应且组内统一的新详情图 | 用户确认；批量改图原型 |
| 运营交互 | 已有 1–9 张输入、商品选择、提示词、逐张状态、重试/微调、反馈和下载原型 | 保持现有交互，不增加锚点或文字人工确认 | `DetailRefreshPage.jsx`；专项测试 |
| AI 质量 | 原型只按任务状态展示候选结果 | Skill 内部完成五项检查，合格后才返回成功 | 定稿 Skill；真实测试与复测 |

### 2.2 本期变更

| 编号 | 变更内容 | 影响范围 |
|---|---|---|
| DR-CHG-01 | 新增 AI 商详焕新入口及 1–9 张详情图输入 | 能力中枢、输入区 |
| DR-CHG-02 | 输出与输入数量、顺序、详情角色和尺寸一一对应 | 任务、结果区 |
| DR-CHG-03 | 生成区别于原图且组内统一的视觉系统 | AI Skill |
| DR-CHG-04 | 替换商品可选；商品智库与上传商品图并行 | 商品参考区 |
| DR-CHG-05 | 支持提示词库、AI 润色和运营补充提示词 | 提示词区 |
| DR-CHG-06 | 支持单张重试、单张微调和版本保留 | 结果区、任务服务 |
| DR-CHG-07 | 每张结果支持认可/待调整互斥反馈 | 结果区 |
| DR-CHG-08 | 商品选择使用公共商品选择能力 | 商品选择弹窗 |
| DR-CHG-09 | 按替换来源进入主体不变或主体替换模式 | AI Skill、任务快照 |
| DR-CHG-10 | AI 自动建立并检查首张风格锚点 | AI Skill |
| DR-CHG-11 | 执行五项质量门禁，失败单图最多自动重试 3 次 | AI Skill、任务服务 |
| DR-CHG-12 | 只有合格图片返回平台成功状态 | AI Skill、任务状态 |
| DR-CHG-13 | 下载、点赞、编辑、权限、积分和历史沿用平台规则 | 结果区、公共服务 |

### 2.3 用户、入口与前置条件

- 入口：AI 能力中心 `/ai-hub/detail-refresh`。
- 输入：上传或从素材库选择 1–9 张可读详情图；如需替换商品，可选择商品智库商品、素材库图片或本地图片。
- 提示词：提示词库、AI 润色和运营补充均可选，不作为提交必填项。

### 2.4 用户流程

1. 用户上传或选择 1–9 张详情图，并可排序、预览、替换或删除。
2. 用户可选一个商品智库商品，也可独立上传替换商品图片；两类来源可并行。
3. 用户可选择提示词模板、AI 润色或填写补充要求。
4. 系统根据有效替换来源固化 `preserve_product` 或 `replace_product`，完成输入校验和整组理解。
5. AI 生成组级视觉系统和首张风格锚点，自动检查通过后逐张生成其余图片。
6. 每张候选图执行商品、贴合、文案、详情角色和组级一致性检查；失败只重试当前图，最多自动重试 3 次。
7. 正常成功时按原顺序一次性展示完整组图；达到上限仍失败时沿用平台现有部分成功或失败状态。
8. 运营按现有规则下载、点赞、待调整、单图重试或微调；反馈不决定下载资格。

分支：

- `preserve_product`：原详情图是商品事实源，只调整人物、背景、场景、光线、构图和视觉系统。
- `replace_product`：新商品参考是唯一商品事实源；原图只提供文案、版式、详情角色和场景语义。
- 商品智库与补充图冲突：商品智库已确认版本优先，补充图仅作额外参考。
- 缺少必要视角：不虚构不可见结构，改用有证据的正面或三分之四侧面构图。
- 单张微调或重试：只影响当前图并清空当前图旧反馈，其他图和反馈不变。

### 2.5 页面交互与用户文案

| 页面/区域 | 控件 | 用户操作 | 系统反馈/后续状态 |
|---|---|---|---|
| 详情图输入 | 图片队列 | 上传、选择、排序、预览、替换、删除 | 显示顺序和数量，进入待提交 |
| 替换商品 | 商品选择/图片上传 | 选择或清除商品、补充商品图 | 两类来源并行；无来源时保持原商品 |
| 提示词 | 编辑器 | 选模板、AI 润色、填写要求 | 保存任务约束；润色失败保留原文 |
| 生成操作 | 开始生成 | 提交整组任务 | 显示平台现有任务和单图状态 |
| 单张结果 | 预览、重试、微调、下载 | 操作当前图 | 只更新当前图片或版本 |
| 单张反馈 | 认可/待调整 | 点击或再次点击 | 互斥；再次点击取消；不影响下载 |

| 场景 | 文案 |
|---|---|
| 页面标题 | AI 商详焕新 |
| 页面说明 | 基于原详情组图，统一换新视觉风格，并支持商品、人物与场景调整。 |
| 空状态 | 上传 1–9 张详情页图片后开始生成。 |
| 替换商品说明 | “替换商品”可选；可从商品智库选择商品，也可从素材库或本地上传商品图片，两种来源并行。 |
| 优先级说明 | 同时选择时，商品智库中的已确认信息优先，上传商品图片作为额外参考；无来源时保持原商品。 |
| 生成按钮 | 开始生成商详组图 |
| 单张操作 | 重新生成 / 继续微调 / 认可 / 待调整 |
| 商品空状态 | 当前商品库暂无符合条件的已确认商品 |

### 2.6 业务规则

#### DR-R-01 组图对应关系

- MVP 支持 1–9 张详情图；输出数量、顺序、详情角色和每张对应尺寸与输入一致。
- 页面不展示模型和尺寸选择，输出尺寸按每张原图保持。

#### DR-R-02 双模式与商品事实

- 无有效替换来源为 `preserve_product`；原详情图锁定商品身份、结构、材质、颜色、Logo、关键部件和比例。
- 有有效替换来源为 `replace_product`；新商品参考是唯一商品事实源，原图旧商品结构和材质不得参与合并。
- 替换模式需生成新商品正向事实和旧商品排除项，禁止新旧商品特征折中。

#### DR-R-03 商品来源优先级

- 商品智库已确认版本优先于上传商品图片；两者冲突时采用商品智库事实。
- 无商品智库来源时可使用上传图；缺少可确认事实时调整构图或返回失败，不得推断虚构。

#### DR-R-04 组级视觉系统与锚点

- 整组只生成一套可执行视觉系统，至少包含主色及占比、辅助色、背景、人物服装、标题/标签色、光线、空间家族、字体、装饰、构图密度和禁止风格。
- 首张由 AI 自动检查，通过后成为只读风格锚点；不增加运营确认步骤。
- 原图仅提供布局和语义，不得让旧配色、服装或装饰回流；单张偏离锚点为硬失败。

#### DR-R-05 商品与物理保真

- 结构、材质、颜色、Logo、部件数量/位置/连接关系必须符合当前模式的唯一事实源。
- 穿戴或使用场景必须具备合理透视、遮挡、受力、接触阴影和贴合关系，不得悬浮、穿透或不合理变形。
- 缺少背面、侧面或遮挡区域证据时不得虚构。

#### DR-R-06 文案与版式

- 可调整文字组织和版式，但只使用原图或运营提供的信息，不新增参数、卖点、功效、认证、销量、排名或对比结论。
- 文字、数字、Logo、表格和箭头优先确定性渲染或后置合成；由模型生成时必须进入内部检查，不增加运营确认。

#### DR-R-07 重试、微调与反馈

- 内部质量失败仅重试当前图片，最多自动重试 3 次；每次只修正对应失败原因，不重做整组。
- 运营单图重试和微调沿用现有布局、版本与积分规则；重试或微调开始后清空当前图反馈。
- 认可/待调整互斥且可取消，只影响当前结果，不影响下载和其他图片。

#### DR-R-08 业务成功与硬失败

- 模型接口成功只代表获得候选图，不等于平台业务成功。
- 商品错误、旧主体残留、物理贴合错误、文案/参数/Logo/箭头错误、详情角色错配、输出尺寸错误或组内风格不一致均为硬失败。
- 只有五项检查通过并完成对应源图尺寸处理的图片才返回 `success`；达到 3 次上限仍失败时返回当前图片失败状态。

### 2.7 AI 能力契约

| 契约项 | 要求 |
|---|---|
| 输入与事实源 | 1–9 张详情图；可选商品智库快照和补充商品图；可选运营提示词 |
| 参考优先级 | 系统约束 > 当前模式商品事实 > 组级视觉系统/锚点 > 已验证模板 > AI 润色 > 运营补充 > 当前图片任务块 |
| AI 处理责任 | 输入校验、模式判定、整组理解、视觉系统、锚点、逐图计划、生成、五项质检和单图重试 |
| 输出 | 按输入顺序返回同数量结果项；合格图保持对应源图像素尺寸；失败项返回平台现有失败状态 |
| 业务成功 | 商品、物理贴合、文案事实、详情角色、组级一致性全部通过，且输出规格正确 |
| 重试停止 | 仅失败单图自动重试，最多 3 次；不覆盖其他已合格结果 |
| 用户可见状态 | 内部候选和失败证据不新增为 `raw/rejected/approved` 产品状态，平台继续使用现有任务枚举 |

#### 提示词装配与模板

最终提示词依次包含：系统安全与事实约束、模式与商品事实、组级视觉系统和锚点、可选提示词模板、经用户确认的 AI 润色结果、运营补充、当前图片任务块。任一可选来源为空时跳过，系统约束始终保留。

运营补充只可影响人物、背景、场景、氛围、构图和版式，不得覆盖商品事实、详情角色、输出尺寸和禁止项。AI 润色须回填编辑器，经用户确认后替换；取消或失败保留原文。

```text
任务：生成一组商品详情页焕新图，保持输入数量、顺序、详情角色和对应尺寸。
模式与商品事实：{mode}；{confirmed_product_facts}；{positive_product_facts}；{legacy_product_exclusions}
组级视觉系统：{color_system}；{scene_character_text_system}；{visual_system}；{forbidden_style}；{style_anchor}
当前图片：{index}；{role}；{must_preserve}；{allowed_changes}；{user_prompt}
禁止：改变商品事实、残留旧主体、物理关系错误、虚构卖点参数、改变角色或箭头语义、继承旧视觉、偏离锚点、乱码或虚假信息。
```

单张重试必须继续使用当前任务的模式、商品事实、排除项、视觉系统、锚点和详情角色，只追加本次失败类型、修正段落和 `retry_count/3`。

#### 质量门禁

| 检查项 | 通过标准 | 硬失败示例 |
|---|---|---|
| `product` | 符合唯一商品事实源 | 身份/结构错误、旧主体残留、虚构不可见结构 |
| `physical_fit` | 透视、遮挡、受力、接触和贴合合理 | 悬浮、穿透、变形 |
| `copy` | 文案、数字、参数、Logo、表格、箭头语义正确 | 错字、乱码、参数或指向错误 |
| `role` | 保持首屏、尺码、结构、场景等原详情角色 | 角色错配、核心信息缺失 |
| `group_consistency` | 主色占比、背景、服装、标签、光线、空间、字体、装饰和密度对齐锚点 | 单张冷暖、服装或版式风格明显偏离 |

### 2.8 状态、边界与异常

| 状态 | 枚举 | 进入条件 | 页面表现/操作 |
|---|---|---|---|
| 未开始 | `IDLE` | 未提交 | 可编辑输入 |
| 排队中 | `QUEUED` | 任务已提交 | 显示等待 |
| 处理中 | `PROCESSING` | 正在生成 | 显示整组与单图进度 |
| 部分成功 | `PARTIAL_SUCCESS` | 部分图通过并返回 | 保留成功图，失败图可单独重试 |
| 全部成功 | `SUCCESS` | 所有图通过内部检查 | 展示完整组图 |
| 全部失败 | `FAILED` | 所有图失败 | 沿用平台失败操作 |
| 已取消 | `CANCELLED` | 用户终止 | 沿用平台取消规则 |
| 单张重试中 | `RETRYING` | 当前图重新生成 | 其他图保持不变 |

| 边界/异常 | 处理规则 | 用户反馈/影响 |
|---|---|---|
| 0 张或超过 9 张 | 阻止提交 | 至少上传 1 张 / 最多 9 张 |
| 图片不可读 | 当前图不进入任务 | 请更换或重新上传 |
| 商品来源冲突 | 商品智库事实优先 | 已按商品智库信息处理 |
| 单图接口或质量失败 | 其他图继续；内部只重试当前图 | 处理中不展示不合格候选 |
| 达 3 次上限 | 停止自动重试并返回失败 | 可按平台规则单独重试或编辑 |
| 离开页面、超时、并发、积分 | 沿用平台历史任务、队列和积分规则 | 本期不新增口径 |

### 2.9 数据、快照与历史兼容

| 对象 | 字段 | 类型/枚举 | 必填 | 业务语义与校验 | 历史兼容 |
|---|---|---|---|---|---|
| 商详任务 | `mode` | `preserve_product/replace_product` | 是 | 提交时由有效替换来源判定，重试不可切换 | 历史任务无字段时按原记录展示，不反推改写 |
| 商详任务 | `product_snapshot` | 公共商品快照 | 否 | 选商品时沿用第 5 章对象；补充图另按现有素材结构保存 | 商品后续更新不影响已提交任务 |
| 商详任务 | `prompt_snapshot` | 字符串/对象 | 是 | 保存最终组级、单图提示词及来源顺序；长度沿用任务现有结构 | 重试读取任务快照 |
| 商详任务 | `visual_system_snapshot` | 对象 | 是 | 保存 DR-R-04 全部组级约束 | 整组和重试只读 |
| 商详任务 | `style_anchor_version_id` | 字符串 | 是 | 指向 AI 检查通过的首张锚点版本 | 不随页面临时值变化 |
| 结果图片 | `generation_status` | `pending/processing/success/failed` | 是 | `success` 仅用于通过内部检查并返回平台的图片 | 沿用平台结果展示 |
| 结果图片 | `quality_checks` | 对象 | 是 | 五项 `pass/fail` 与证据，仅内部使用 | 不新增前端状态 |
| 结果版本 | `retry_audit` | 对象 | 否 | 失败类型、修改段落、序号 1–3、提示词、模型任务 ID、内部路径 | 用于联调和问题追溯 |

### 2.10 责任边界与公共能力影响

| 责任方/能力 | 责任与对接 |
|---|---|
| 前端 | 输入、商品/素材/提示词选择、任务进度、结果、反馈、下载、微调；不展示内部候选和锚点确认 |
| 任务服务 | 校验、任务/商品/提示词快照、整组与单图状态、调用 Skill、最多 3 次重试编排、历史恢复 |
| `xianma_detail_refresh` Skill | 模式与事实锁定、视觉系统、提示词装配、逐图生成、五项质检和业务成功判定 |
| 商品/素材服务 | 提供已授权的商品快照和素材引用；商品选择沿用第 5 章 |
| 历史/权限/积分/下载 | 沿用平台现有规则，只补充本章新增快照和结果关联 |

### 2.11 验收标准

| 编号 | 关联项 | 前置条件/操作 | 预期结果 | 类型 |
|---|---|---|---|---|
| DR-AC-01 | DR-CHG-01/02、DR-R-01 | 分别上传 1 张、9 张并提交 | 分别输出 1、9 个对应结果，顺序和角色一致 | 正常/边界 |
| DR-AC-02 | DR-R-01 | 上传 10 张 | 阻止提交并提示最多 9 张 | 边界 |
| DR-AC-03 | DR-CHG-09、DR-R-02 | 不提供替换来源并生成 | 固化 `preserve_product`，原商品身份和结构不变 | 正常 |
| DR-AC-04 | DR-CHG-09、DR-R-02/03 | 选择新商品并生成 | 固化 `replace_product`，整组无旧主体残留 | 正常 |
| DR-AC-05 | DR-R-03 | 同时选择商品智库和冲突补充图 | 商品智库事实优先 | 联动 |
| DR-AC-06 | DR-CHG-10、DR-R-04 | 提交生成 | AI 自动检查锚点，通过后继续；运营无中间确认 | 质量 |
| DR-AC-07 | DR-CHG-05、DR-R-06 | 填写补充提示词并生成 | 只影响允许项，不覆盖商品事实 | 规则 |
| DR-AC-08 | DR-R-07/08 | 单张质量失败 | 只重试当前图，最多 3 次，其他图不变 | 异常 |
| DR-AC-09 | DR-R-07 | 对单张微调 | 只更新当前图并保留原版本 | 联动 |
| DR-AC-10 | DR-R-06 | 图片含文字、数字、Logo、表格或箭头 | 内部核对正确后才返回成功，不增加人工确认 | 质量 |
| DR-AC-11 | DR-R-05 | 新商品缺少背面参考 | 不虚构背面，改用有证据构图 | 边界 |
| DR-AC-12 | DR-R-08 | 候选含旧部件、悬浮、穿透或风格偏离 | 对应质量项失败，不返回成功 | 质量 |
| DR-AC-13 | DR-R-08 | 五项检查全部通过 | 按对应源图像素宽高返回成功 | 交付 |
| DR-AC-14 | DR-CHG-07、DR-R-07 | 切换/取消认可与待调整 | 反馈互斥可取消，不影响下载 | 交互 |
| DR-AC-15 | DR-R-07 | 已反馈图片重试或微调 | 当前反馈清空，其他反馈不变 | 联动 |
| DR-AC-16 | DR-CHG-13 | 未点赞直接下载单张或整组 | 成功图片可下载，命名沿用现有规则 | 交付 |
| DR-AC-17 | DR-CHG-05 | AI 润色取消或失败 | 原提示词、模板和人工输入不丢失 | 异常 |
| DR-AC-18 | DR-CHG-13 | 生成中离开后返回 | 任务与结果按平台现有历史逻辑恢复 | 兼容 |
| DR-AC-19 | DR-CHG-05、DR-R-06 | 同时存在模板、AI 润色和运营补充时提交 | 最终提示词按约定优先级装配，低优先级内容不能覆盖商品事实和系统禁止项 | 规则 |
| DR-AC-20 | DR-R-06 | 运营输入原图和提示词均未提供的新卖点、参数或功效 | 结果不得将该内容作为商品事实输出；命中时 `copy=fail` | 质量 |
| DR-AC-21 | DR-CHG-01～13 | 完成一次含内部质量失败后重试的任务 | `task_created`、质量检查、最终 `result_created`、`task_finished` 和 `credit_settled` 可由 `task_id` 串联；内部重试不记为用户 `task_retry` | 埋点/联动 |
| DR-AC-22 | DR-CHG-06/07/13 | 对成功结果分别下载、继续编辑、加入素材库、认可或待调整 | 成功采纳动作按 `result_id` 去重；预览、失败点击和待调整不计采纳 | 埋点/口径 |

### 2.12 原型、开发状态与证据

| 内容 | 状态 | 证据 | 尚未完成 |
|---|---|---|---|
| 前端交互 | 已定稿原型 | `DetailRefreshPage.jsx`、`detail-refresh-prototype.test.mjs` | 真实任务和接口 |
| 双模式与质量规则 | 已完成 Skill 与真实样例验证 | `.agents/skills/xianma_detail_refresh/`、两份测试报告 | 生产任务编排与自动质检联调 |
| 主体替换第 3 张误放行 | 已纠正 | R-03 复测报告 | 防止生产链路绕过 `group_consistency` |

### 2.13 埋点与效果衡量

#### 2.13.1 归属与统计边界

- `tool_key=ai_detail_refresh`；页面访问和入口点击只用于漏斗，不计功能实际使用。
- 功能实际使用以后台成功记录 `task_created` 为准；模型接口返回成功不等于业务成功，结果必须通过 DR-R-08 五项门禁和尺寸校验后才能以 `result_status=SUCCESS` 进入成功分子。
- 内部候选、五项质检和最多 3 次自动重试属于 Skill/任务服务内部事实；不得上报为运营主动 `task_retry`。运营点击单图重试时才记录 `task_retry`。

#### 2.13.2 事件与字段

> 下表事件继承 8.1 公共字段。完整提示词、原图 URL、模型原始响应和质检证据正文不得进入分析事件；仅记录结构化枚举、ID、数量和长度。

| 事件 | 上报端 | 触发/成功时机 | 本模块必填业务字段 | 去重/幂等 | 指标用途 |
|---|---|---|---|---|---|
| `page_view` | 前端 | 商详页渲染完成 | `page_path`、`tool_key`、`session_id` | `event_id` | 访问与提交漏斗；不计实际使用 |
| `material_select_success` / `local_upload_success` | 前端/上传服务 | 素材确认回填成功 / 本地文件上传成功 | `input_type=detail_image/replacement_image`、`asset_id` 或 `file_count`、`input_image_count` | 按公共规则；同一 `asset_id` 选择次数与任务实际复用分开 | 输入来源；不直接计核心素材复用 |
| `prompt_template_selected` | 前端 | 用户确认采用模板并回填 | `prompt_template_id`、`prompt_template_source`、`tool_key` | `event_id` | 模板使用；不记录提示词全文 |
| `task_submit_click` | 前端 | 点击“开始生成商详组图”且前端校验通过 | `request_id`、`mode`、`input_image_count`、`replacement_source`、`has_product_snapshot`、`expected_result_count`、`has_prompt_template`、`has_user_prompt` | `event_id` | 提交意图、前后端创建漏斗；不计成功 |
| `task_created` / `task_create_failed` | 后端 | 任务与快照创建成功 / 创建失败 | 成功：`task_id`、`request_id`、`mode`、`input_image_count`、`replacement_source`、`has_product_snapshot`、`expected_result_count`；选商品时增加 `product_id`、`confirmed_version_id`；失败时含 `error_code` | 成功按 `task_id`；失败按 `request_id` | 实际使用次数、创建成功率、商品使用归因 |
| `task_status_change` | 后端 | 任务进入排队、处理、部分成功、成功、失败或取消 | `task_id`、`old_status`、`new_status`、`event_time`、失败时 `error_code/failure_stage` | 状态版本号优先；否则 `task_id+new_status+event_time` | 状态漏斗、失败阶段 |
| `detail_quality_check_finished` | Skill 接入层/后端 | 每个候选完成五项门禁及尺寸校验 | `task_id`、`result_index`、`image_role`、`attempt_no`、`product_check`、`physical_fit_check`、`copy_check`、`role_check`、`group_consistency_check`、`size_check`、`quality_failure_type`、`is_final_attempt` | `task_id+result_index+attempt_no` | 五项失败分布、内部重试原因；本期专属新增事件 |
| `result_created` | 后端 | 每个结果形成最终成功或失败事实 | `result_id`、`task_id`、`result_index`、`image_role`、`result_status`、`internal_retry_count`；失败时 `quality_failure_type` | `result_id` | 成功结果数、失败结果数、单图质量与重试 |
| `task_finished` | 后端 | 整组进入最终态且结果计数落定 | `task_id`、`task_status`、`duration_ms`、`expected_result_count`、`success_result_count`、`failed_result_count`、`internal_retry_count`；失败/部分成功时 `error_code` | `task_id`；状态修正走更新或版本化，不重复累计 | 整组成功率、核心链路成功率、平均耗时 |
| `task_retry` | 前端/后端 | 运营主动发起单图重试且创建重试执行成功 | `task_id`、`result_id`、`result_index`、`retry_scope=single_result`、`retry_from_task_id` 或原任务版本 | 重试任务 ID 或 `event_id` | 运营返修率；不得包含内部自动重试 |
| `credit_settled` | 后端 | 实际扣减、退回或不扣费结算完成 | `task_id`、`credit_record_id`、`settle_type`、`credit_cost`、`refund_credit` | `credit_record_id`，无流水时 `task_id+settle_type` | 单任务、单成功任务、单有效结果成本 |
| `result_download_success` | 前端/下载服务 | 单张文件或整组 ZIP 实际生成并开始成功下载 | `result_id` 或 `suite_id`、`task_id`、`download_type=single/batch_detail_refresh`（新增枚举建议，待技术对齐） | 行为次数全量；采纳按 `result_id+user_id` 去重 | 下载与采纳；整组下载需展开关联成功结果，失败图不计 |
| `result_continue_edit_success` / `result_add_asset_success` | 前端/后端 | 成功进入编辑 / 素材写入成功 | `result_id`、`task_id`；加素材时 `asset_id`，编辑时 `target_tool_key` | `event_id`；资产按 `asset_id` | 结果采纳、资产沉淀、后续复用 |
| `result_approve_success` / `result_reject` | 前端/后端 | 认可保存成功 / 待调整状态保存成功 | `result_id`、`task_id`；待调整可带结构化 `reason_key` | 认可按 `result_id+user_id`；否定行为按 `event_id` | 认可计采纳；待调整计否定，不影响下载 |

#### 2.13.3 指标口径、异常与验收

| 指标 | 计算口径 | 排除项/说明 |
|---|---|---|
| 功能实际使用次数 | `count(distinct task_id where task_created.tool_key=ai_detail_refresh)` | 排除页面访问、提交点击和创建失败 |
| 核心链路成功率 | 最终 `SUCCESS` 任务数 / 成功创建任务数 | `PARTIAL_SUCCESS` 不进入全成功分子，可单列 |
| 整组可交付率 | `success_result_count=expected_result_count` 的任务数 / 完成任务数 | 以质量门禁后的业务状态为准 |
| 五项失败分布 | 按 `detail_quality_check_finished.quality_failure_type` 统计失败候选数及任务数 | 同一候选多项失败可分别计次数；报表同时给出去重任务数 |
| 平均内部重试次数 | 最终任务 `internal_retry_count` 总和 / 完成任务数 | 不与运营 `task_retry` 混算 |
| 平均处理时长 | `SUCCESS/PARTIAL_SUCCESS` 且时间完整任务的 `duration_ms` 平均值 | 缺时间、取消任务排除并监控缺失率 |
| 生成采纳率 | 至少发生一次成功采纳动作的去重成功 `result_id` 数 / 成功 `result_id` 数 | 预览、失败点击和 `result_reject` 不计；多动作只增加一个采纳结果 |
| 结果否定率 | 去重待调整 `result_id` 数 / 成功 `result_id` 数 | 认可取消不等同否定；以最终保存成功事实为准 |

- 数据质量验收：随机抽取完整成功、部分成功、质量失败、运营单图重试、整组下载各 1 条链路，验证 `task_id` 可串联 `result_id/history_id/credit_record_id/asset_id`；结果计数满足 `success_result_count+failed_result_count=expected_result_count`。
- 异常处理：埋点失败不得阻塞生成、下载或反馈；失败事件进入 `analytics_report_retry`，补偿上报仍以原 `event_id` 去重。历史任务不补造，只从埋点正式生效并完成数据验收后统计。

## 3. AI 买家秀

### 3.1 目标与变更

| 编号 | 变更内容 | 当前/目标状态 |
|---|---|---|
| BS-CHG-01 | “商品与场景”增加可选商品智库入口 | 原型已定稿，真实接口待开发 |
| BS-CHG-02 | 选商品后回填标准品类和有效确认图，仍可补充手动图 | 原型已定稿 |
| BS-CHG-03 | 切换品类清空旧场景；提交保存商品快照 | 原型已定稿，持久化待开发 |

### 3.2 流程、交互与规则

1. 用户可选择商品或跳过；选择后系统回填标准品类和确认图。
2. 用户仍可补充手动参考图，并独立选择场景；商品与具体场景不固定绑定。
3. 切换品类时清空旧场景，要求在新类目下重新选择；商品和手动图按现有规则保留。
4. 未选择商品时，图片队列、品类、场景和提交校验全部沿用现有逻辑。
5. 提交时引用第 5 章公共 `product_snapshot`，后续商品更新不改变历史任务。

#### BS-R-01 商品选择与兼容

- 商品选择可选；回填商品智库标准品类和有效确认图，确认图参与任务商品事实。
- 商品与场景独立；切换品类必须清空旧场景。
- 不选商品不新增任何必填条件。

### 3.3 状态、责任与数据

- 页面状态沿用 AI 买家秀现有流程，只增加未选/已选商品及商品空状态。
- 前端负责选择、回填、品类/场景联动；商品服务负责资格和快照；任务服务在提交时固化快照；AI 生成和既有微调规则本期不变。
- 数据引用第 5 章公共对象，不在本章重复定义 `product_snapshot`。

### 3.4 验收与证据

| 编号 | 关联项 | 操作 | 预期结果 | 类型 |
|---|---|---|---|---|
| BS-AC-01 | BS-CHG-01/02、BS-R-01 | 选择可用商品 | 自动带出标准品类和确认图，仍可补充手动图和选场景 | 正常 |
| BS-AC-02 | BS-R-01 | 不选商品按原流程提交 | 原流程可提交，无新增必填条件 | 兼容 |
| BS-AC-03 | BS-CHG-03、BS-R-01 | 已选场景后切换品类 | 旧场景清空，需重新选择 | 联动 |
| BS-AC-04 | BS-CHG-01～03 | 分别按选商品和未选商品路径完成任务 | 两条路径均产生可关联的提交、任务、结果、积分和采纳事实；选商品任务包含商品快照标识 | 埋点/联动 |
| BS-AC-05 | BS-CHG-03 | 已选场景后切换品类 | 记录品类变更及 `scene_clear_reason=category_change`，但不把配置行为计为任务使用 | 埋点/口径 |

- 原型/证据：`BuyerShowPage.jsx`、`buyer-show-product-selection.test.mjs`。

### 3.5 埋点与效果衡量

#### 3.5.1 归属与事件

- 沿用 `tool_key=ai_buyer_show`。商品选择只是该工具的输入方式，不新增独立工具使用次数。
- 既有生成、结果、积分、反馈和评价文案事件继续使用正式埋点方案；本期重点补齐商品快照、手动参考图及品类/场景联动字段。

| 事件 | 上报端 | 触发/成功时机 | 本模块必填业务字段 | 去重/幂等 | 指标用途 |
|---|---|---|---|---|---|
| `product_picker_open` / `product_select_success` | 前端 | 打开选择器 / 商品通过资格校验并回填页面 | `target_tool_key=ai_buyer_show`；选择成功时 `product_id`、`confirmed_version_id`、`standard_category` | `event_id` | 选择漏斗诊断；不计任务实际使用 |
| `material_select_success` / `local_upload_success` | 前端/上传服务 | 手动参考图回填或上传成功 | `tool_key`、`asset_id` 或 `file_count`、`input_type=manual_reference` | 按 8.1 公共规则 | 手动参考图补充率 |
| `parameter_change` | 前端 | 品类或场景确认发生变化 | `param_key=category_key/scene_key`、`param_value`、`previous_value`；切品类清场景时增加 `scene_clear_reason=category_change` | `event_id` | 品类/场景偏好与联动诊断；不计任务使用 |
| `task_submit_click` | 前端 | 点击生成且前端校验通过 | `request_id`、`category_key`、`scene_key`、`scene_source`、`has_product_snapshot`、`manual_reference_count`、`expected_result_count` | `event_id` | 提交意图与创建漏斗 |
| `task_created` / `task_create_failed` | 后端 | 任务与快照创建成功 / 创建失败 | 公共任务字段；成功时增加 `category_key`、`scene_key`、`scene_source`、`has_product_snapshot`、`manual_reference_count`；选商品时 `product_id`、`confirmed_version_id`；失败时 `error_code` | `task_id` / `request_id` | 实际使用、选商品任务占比、两条路径创建成功率 |
| `task_finished` / `credit_settled` / `result_created` | 后端 | 任务、结算、单结果形成最终事实 | 公共字段；结果增加 `image_role=buyer_show`、`result_index` | 分别按 `task_id`、`credit_record_id`、`result_id` | 成功率、耗时、成本、成功结果数 |
| `result_approve_success` / `result_reject` | 前端/后端 | 认可或待调整保存成功 | `result_id`、`task_id`、`tool_key`；待调整可带 `reason_key` | 认可按 `result_id+user_id`；否定按 `event_id` | 图片采纳率与否定率 |
| `result_download_success` / `result_continue_edit_success` / `result_add_asset_success` | 前端/后端 | 对应动作实际成功 | 公共采纳字段；批量下载 `download_type=batch_buyer_show` | 按 8.1 采纳去重规则 | 图片采纳、资产沉淀与复用 |
| `text_batch_generate_success` | 前端/后端 | 整套评价文案实际生成成功 | `task_id`、`generated_count`、`category_key`、`scene_key` | `event_id` | 文案生成使用；不直接计单条采纳 |
| `text_copy_success` / `text_export_success` | 前端/后端 | 复制或导出实际成功 | `source_type=buyer_show_review`、`source_id`、`task_id`；复制含 `copy_scope`，导出含 `export_format` | `event_id`；文案采纳按 `source_id+user_id` 去重 | 文案采纳率 |

#### 3.5.2 指标、异常与验收

| 指标 | 计算口径 |
|---|---|
| 商品选择任务占比 | `task_created` 中 `has_product_snapshot=true` 的任务数 / AI 买家秀任务数 |
| 商品选择后任务创建成功率 | 有有效商品回填的 `task_created` 数 / 对应 `task_submit_click` 数 |
| 手动商品图补充率 | 选商品且 `manual_reference_count>0` 的任务数 / 选商品任务数 |
| 核心链路成功率 | 最终成功任务数 / 成功创建任务数 |
| 图片采纳率 | 有任一成功采纳动作的去重成功图片 `result_id` 数 / 成功图片数 |
| 文案采纳率 | 被成功复制或导出的去重评价文案数 / 成功生成评价文案数 |

- 商品已回填但提交前失效时，由第 5 章记录失效事件；未创建任务，不得计入实际使用。
- 埋点验收需分别覆盖“选商品+补图”“选商品不补图”“不选商品”“切品类清场景”“评价复制/导出”五条链路，并验证商品版本、任务、结果和采纳归因一致。

## 4. 主体替换

### 4.1 目标与变更

| 编号 | 变更内容 | 当前/目标状态 |
|---|---|---|
| SR-CHG-01 | 增加商品智库商品作为独立主体来源 | 原型已定稿，真实接口待开发 |
| SR-CHG-02 | 根据是否选商品切换提交校验 | 原型已定稿 |
| SR-CHG-03 | 清除商品不删除手动参考图；提交保存商品快照 | 原型已定稿，持久化待开发 |

### 4.2 流程、交互与规则

1. 用户上传至少 1 张待替换原图，可选商品智库商品，也可继续上传手动主体参考图。
2. 已选商品时，商品是独立主体来源，不固定插入手动图片队列；至少 1 张原图即可提交。
3. 未选商品时，沿用“原图 + 至少 1 张主体参考图”的校验。
4. 清除商品只清除商品来源和回填信息，不删除手动图；提交时固化公共商品快照。

#### SR-R-01 主体来源和队列边界

- 商品智库商品与手动主体参考图是并行来源，选择商品后仍可补充手动图。
- 商品确认图不固定占用图片队列第 2 位，不改变手动图顺序。
- 商品选择资格与快照沿用第 5 章，既有结果、积分和历史规则不变。

### 4.3 状态、责任与数据

- 前端负责商品选择、清除、图片队列和动态提交校验；商品服务提供可选商品；任务服务固化快照；主体替换 AI 处理规则本期不变。
- 数据引用第 5 章公共对象，不重复定义 `product_snapshot`。

### 4.4 验收与证据

| 编号 | 关联项 | 操作 | 预期结果 | 类型 |
|---|---|---|---|---|
| SR-AC-01 | SR-CHG-01/02、SR-R-01 | 仅 1 张原图并选择商品后提交 | 校验通过，商品作为独立主体来源并保存快照 | 正常 |
| SR-AC-02 | SR-CHG-02、SR-R-01 | 仅 1 张原图且未选商品提交 | 阻止并提示补充主体参考图 | 边界/兼容 |
| SR-AC-03 | SR-CHG-03、SR-R-01 | 已选商品且有手动图，清除商品 | 手动图及顺序不变，提交改按未选商品校验 | 联动 |
| SR-AC-04 | SR-CHG-01～03 | 分别以商品智库、手动参考图、两者并用完成提交 | `task_created` 正确记录主体来源类型、商品快照和手动参考图数量 | 埋点/联动 |
| SR-AC-05 | SR-CHG-02 | 无任何有效主体来源时点击提交 | 记录结构化拦截原因，不产生 `task_created`，不计功能实际使用 | 埋点/边界 |

- 原型/证据：`SubjectReplaceWorkbench.jsx`、`product-picker-integration.test.mjs`。

### 4.5 埋点与效果衡量

#### 4.5.1 归属与事件

- 沿用 `tool_key=subject_replace`。商品智库和手动参考图是主体来源维度，不拆成新工具。
- `replacement_source_type` 固定枚举建议为 `product_library/manual_reference/product_and_manual`；最终字段名和枚举与现有实现对齐，但三种业务语义必须可区分。

| 事件 | 上报端 | 触发/成功时机 | 本模块必填业务字段 | 去重/幂等 | 指标用途 |
|---|---|---|---|---|---|
| `product_picker_open` / `product_select_success` / `product_clear` | 前端 | 打开选择器、成功回填、用户清除商品 | `target_tool_key=subject_replace`；选择成功时 `product_id`、`confirmed_version_id`；清除时 `had_manual_reference` | `event_id` | 商品选择与清除漏斗；不计实际使用 |
| `material_select_success` / `local_upload_success` | 前端/上传服务 | 原图或手动主体参考图成功回填 | `input_type=source_image/manual_subject_reference`、`asset_id` 或 `file_count`、`manual_reference_count` | 按 8.1 公共规则 | 输入来源和手动参考图补充 |
| `subject_source_blocked` | 前端 | 用户提交但缺少满足当前路径的主体来源 | `block_reason=no_product_and_no_manual_reference`、`source_image_count`、`manual_reference_count`、`has_product_snapshot` | 每次提交意图按 `event_id` | 提交拦截率；不得产生 `task_created` |
| `task_submit_click` | 前端 | 动态校验通过后点击生成 | `request_id`、`replacement_source_type`、`source_image_count`、`manual_reference_count`、`has_product_snapshot`、`expected_result_count` | `event_id` | 合法提交意图与创建漏斗 |
| `task_created` / `task_create_failed` | 后端 | 任务与主体来源快照创建成功 / 创建失败 | 公共任务字段；增加 `replacement_source_type`、`source_image_count`、`manual_reference_count`、`has_product_snapshot`；选商品时 `product_id`、`confirmed_version_id`；失败时 `error_code` | `task_id` / `request_id` | 实际使用、来源占比、两条提交路径成功率 |
| `task_status_change` / `task_finished` / `credit_settled` | 后端 | 状态变化、任务终态、积分结算完成 | 按 8.1 公共任务字段 | 分别按公共规则 | 状态漏斗、成功率、耗时、成本 |
| `result_created` | 后端 | 每个最终结果形成 | `result_id`、`task_id`、`result_index`、`result_status` | `result_id` | 成功/失败结果数 |
| `result_download_success` / `result_continue_edit_success` / `result_add_asset_success` / `result_approve_success` / `result_reject` | 前端/后端 | 对应结果动作实际成功 | 按 8.1 公共采纳字段 | 按 `result_id` 区分行为次数与去重采纳结果 | 采纳、否定、资产沉淀 |

#### 4.5.2 指标、异常与验收

| 指标 | 计算口径 |
|---|---|
| 商品选择任务占比 | `task_created` 中 `replacement_source_type in (product_library,product_and_manual)` 的任务数 / 主体替换任务数 |
| 手动主体图补充率 | 选商品且 `manual_reference_count>0` 的任务数 / 选商品任务数 |
| 缺主体来源拦截率 | `subject_source_blocked` 次数 /（`subject_source_blocked` 次数 + 前端校验通过的 `task_submit_click` 次数）；同时展示事件次数与去重用户数 |
| 两条路径任务创建成功率 | 分别按是否含商品快照计算 `task_created/task_submit_click` |
| 核心链路成功率 / 生成采纳率 | 按 8.1 公共口径，使用 `task_id/result_id` 去重 |

- 清除商品后如手动图仍存在，后续提交必须归入 `manual_reference`，不得继续携带已清除的 `product_id/confirmed_version_id`。
- 埋点验收需覆盖三种主体来源、清除商品后提交、缺来源拦截和提交前商品失效，核对页面选择事实与后端任务快照一致。

## 5. 商品选择公共能力

### 5.1 目标与变更

| 编号 | 变更内容 | 使用方 |
|---|---|---|
| PP-CHG-01 | 统一个人、团队、公共商品库 Tab、搜索和品类筛选 | AI 买家秀、主体替换、AI 商详焕新 |
| PP-CHG-02 | 统一商品可见范围、已确认状态和有效确认版本资格 | 三个工作台 |
| PP-CHG-03 | 统一回填对象和任务提交快照 | 三个工作台、任务服务 |

### 5.2 公共规则

#### PP-R-01 库范围与选择资格

- 支持个人、团队、公共商品库 Tab；按商品名称/来源搜索，按商品智库标准品类筛选。
- 仅展示当前用户有权查看、底层状态为 `confirmed` 且存在有效确认版本/确认图的商品。
- 个人库包括本人创建且处于允许选择的团队/公共审核状态商品；团队库包括团队可用、公共审核中、公共已驳回、公共可用；公共库仅公共可用。
- 草稿、识别中、待补充、还原中、待确认、部分成功、修订中、已归档及无有效确认版本商品不可选。

#### PP-R-02 回填与权限契约

- 返回商品 ID、名称、标准品类、有效确认版本 ID、有效确认图和已确认商品事实。
- 公共能力只负责列表、筛选、资格、权限和回填；各工作台负责回填位置、页面校验和任务使用。
- 服务端必须再次鉴权，前端隐藏不可代替权限校验；接入工作台不得扩大商品可见范围。

#### PP-R-03 快照与版本

- 任务提交时固化当前有效确认版本及其商品事实和确认图；商品后续修改不影响历史任务。
- 三个模块复用同一 `product_snapshot` 业务对象，不分别定义同名不同义字段。

### 5.3 数据契约

> 字段名优先沿用商品智库和任务服务现有结构；下表定义最低业务语义，最终字段命名由开发技术方案确认。

| 字段语义 | 建议字段 | 类型 | 必填 | 校验/版本规则 |
|---|---|---|---|---|
| 商品标识 | `product_id` | 字符串 | 是 | 必须在提交时仍对当前用户可见 |
| 商品名称 | `product_name` | 字符串 | 是 | 保存提交时展示值 |
| 标准品类 | `standard_category` | 现有品类对象/标识 | 是 | 沿用商品智库唯一标准品类 |
| 确认版本 | `confirmed_version_id` | 字符串 | 是 | 必须为提交时有效确认版本 |
| 确认图 | `confirmed_images` | 图片引用数组 | 是 | 至少 1 张有效确认图；保存版本引用或快照 |
| 商品事实 | `confirmed_product_facts` | 对象 | 否 | 下游 AI 需要商品事实时保存；内容来自确认版本 |
| 固化时间 | `snapshot_at` | 时间 | 是 | 使用平台统一时间格式；提交后不可变 |

历史任务无商品快照时按原参数展示，不反向补齐或自动关联当前商品版本。

### 5.4 责任、状态与异常

| 责任方 | 责任 |
|---|---|
| 公共选择器前端 | Tab、搜索、筛选、空状态、选择和回填 |
| 商品服务 | 可见范围、状态、有效确认版本和服务端鉴权 |
| 业务工作台 | 页面回填、输入校验、清除规则和提交参数 |
| 任务服务 | 提交时二次校验并固化公共快照 |

- 商品列表加载、空、失败状态沿用公共选择器现有模式；失败时不得保留无效旧选择。
- 提交前商品失效或权限变化时阻止提交并要求重新选择；具体错误码和接口由开发定义。

### 5.5 验收与证据

| 编号 | 关联项 | 操作 | 预期结果 | 类型 |
|---|---|---|---|---|
| PP-AC-01 | PP-CHG-01/02、PP-R-01 | 在三个工作台切换库、搜索、筛选 | 使用相同范围和资格，仅展示可见且有有效确认版本的已确认商品 | 公共能力/权限 |
| PP-AC-02 | PP-R-02 | 选择同一商品 | 三处获得一致商品、品类、确认版本和确认图；各自按模块规则回填 | 联动 |
| PP-AC-03 | PP-R-03 | 提交后更新商品确认版本 | 历史任务继续使用提交时快照，新任务使用新有效版本 | 兼容 |
| PP-AC-04 | PP-R-01/02 | 提交前商品失效或权限被收回 | 阻止使用旧选择，不扩大可见范围 | 异常/权限 |
| PP-AC-05 | PP-CHG-01～03 | 在三个工作台完成打开、筛选、选择并提交 | 选择器事件均带 `target_tool_key`；只有后端 `task_created` 绑定商品快照后才计下游商品实际使用 | 埋点/口径 |
| PP-AC-06 | PP-R-01/02 | 模拟空结果、加载失败、提交前失效 | 三类诊断事件可区分，且不影响或伪造下游任务成功事实 | 埋点/异常 |

- 原型/证据：`ProductPickerModal.jsx`、`product-picker-integration.test.mjs`、公共组件目录。

### 5.6 埋点与效果衡量

#### 5.6.1 归属与事件

- 商品选择器是公共输入组件，不设置独立核心 `tool_key`，所有事件必须携带 `target_tool_key=ai_detail_refresh/ai_buyer_show/subject_replace` 归因到目标工作台。
- `product_select_success` 只代表商品资格校验通过并成功回填页面，不代表生成任务创建成功；商品的实际使用以 `task_created` 成功绑定 `product_id+confirmed_version_id+task_id` 为准。

| 事件 | 上报端 | 触发/成功时机 | 必填业务字段 | 去重/幂等 | 指标用途 |
|---|---|---|---|---|---|
| `product_picker_open` | 前端 | 选择器成功打开并可交互 | `target_tool_key`、`source_page`、`session_id`、`picker_instance_id` | `event_id` | 选择漏斗起点 |
| `product_library_tab_change` | 前端 | 用户切换个人/团队/公共库且列表请求发起 | `target_tool_key`、`picker_instance_id`、`library_scope=personal/team/public`、`previous_scope` | `event_id` | 各库使用偏好与加载诊断 |
| `product_search` | 前端 | 用户确认搜索或防抖请求实际发起 | `target_tool_key`、`picker_instance_id`、`library_scope`、`query_length`、`has_query=true/false` | `event_id` | 搜索使用；不得记录搜索原文 |
| `product_category_filter` | 前端 | 品类筛选实际生效 | `target_tool_key`、`picker_instance_id`、`library_scope`、`category_key` 或 `is_all=true` | `event_id` | 筛选使用和空结果定位 |
| `product_picker_empty_result` | 前端 | 列表请求成功但当前条件返回 0 条 | `target_tool_key`、`picker_instance_id`、`library_scope`、`has_query`、`category_key` | 同一次请求按 `trace_id` | 空结果率；不等同加载失败 |
| `product_picker_load_failed` | 前端/后端 | 商品列表请求失败且页面进入失败态 | `target_tool_key`、`picker_instance_id`、`library_scope`、`error_code`、`trace_id` | `trace_id+error_code` | 可用性与失败定位 |
| `product_select_success` | 前端 | 商品仍有效且确认版本成功回填工作台 | `target_tool_key`、`picker_instance_id`、`product_id`、`confirmed_version_id`、`library_scope`、`standard_category` | `event_id`；一次回填一次事件 | 打开到选择成功率；不计核心使用 |
| `product_clear` | 前端 | 用户清除已回填商品 | `target_tool_key`、`product_id`、`confirmed_version_id`、`clear_source=user` | `event_id` | 清除率与页面联动诊断 |
| `product_selection_invalidated` | 后端/前端 | 提交二次鉴权发现商品、版本或权限失效并阻止提交 | `target_tool_key`、`product_id`、`confirmed_version_id`、`invalid_reason=product_unavailable/version_changed/permission_revoked`、`request_id` | `request_id+product_id` | 提交前失效拦截率 |
| 下游 `task_created` | 后端 | 工作台任务创建成功且商品快照固化完成 | `tool_key`、`task_id`、`product_id`、`confirmed_version_id`、`has_product_snapshot=true` | `task_id` | 商品实际使用、下游转化和复用事实 |

#### 5.6.2 指标、异常与验收

| 指标 | 计算口径 |
|---|---|
| 打开到选择成功率 | 有 `product_select_success` 的去重 `picker_instance_id` 数 / `product_picker_open` 的去重 `picker_instance_id` 数 |
| 搜索/筛选空结果率 | `product_picker_empty_result` 请求数 / 成功返回的搜索或筛选请求数 |
| 加载失败率 | `product_picker_load_failed` 请求数 / 商品列表请求数 |
| 提交前失效拦截率 | `product_selection_invalidated` 次数 / 携带商品选择的提交请求数 |
| 商品实际使用次数 | 下游 `task_created` 中带有效 `product_id+confirmed_version_id` 的去重 `task_id` 数，按 `tool_key` 分组 |

- 商品名称、确认图 URL、商品事实全文不进入分析事件；报表只使用稳定 ID、品类和来源范围。组织归属使用事件发生时快照。
- 同一用户重复打开、筛选或选择可计行为次数；任务实际使用必须按 `task_id` 去重。前端选择事件缺失不得用后端任务反向补造，后端任务事实也不得由选择事件推断。

## 6. AI 多角度

### 6.1 目标与变更

| 编号 | 变更内容 | 当前/目标状态 |
|---|---|---|
| MA-CHG-01 | 四个斜方向在 `0°–90°` 内按 `5°` 步进编辑 | 原型已定稿 |
| MA-CHG-02 | 提交时固化方向、方位和提示词快照 | 原型已定稿，任务持久化待开发 |
| MA-CHG-03 | 所有结果继承输入图宽高比 | 用户反馈缺陷，待真实链路修复 |

### 6.2 流程与交互

1. 用户上传 1 张主体图，系统读取并保存像素宽高和宽高比。
2. 用户选择 2–8 个方向；正面、背面、左侧、右侧固定，四个斜方向通过独立铅笔入口编辑。
3. 确认后更新按钮角度但不改变选中状态；取消、点击外部或 `Escape` 不保存。
4. 提交时固化显示名称、目标角度、实际方位角、英文角度提示词、完整提示词和输入比例。
5. 生成请求使用输入比例；结果返回后校验实际像素宽高比，不一致不得成功。

用户固定提示：自定义角度为近似值，模型会尽量按指定角度生成，实际效果可能存在 `±15°` 偏差，极端角度效果可能不理想。

### 6.3 业务规则

#### MA-R-01 方向编辑

- 固定方向无编辑入口；左前、右前、左后、右后默认 `45°`，只改角度不改方位。
- 有效范围 `0°–90°`、步进 `5°`；失焦或确认时取最近 `5°` 倍数并限制上下限。
- 恢复默认将四个斜角恢复 `45°`，不改变选中状态；自定义仅当前页面会话生效。

#### MA-R-02 方位与提示词快照

| 方向 | 实际方位角 | 英文提示词 |
|---|---|---|
| 正面 / 右侧 / 背面 / 左侧 | `0° / 90° / 180° / 270°` | `front/right side/back/left side view` |
| 右前 `XX°` | `XX°` | `XX degrees right-front view` |
| 右后 `XX°` | `180°-XX°` | `XX degrees right-back view` |
| 左后 `XX°` | `180°+XX°` | `XX degrees left-back view` |
| 左前 `XX°` | `360°-XX°`，`0°` 记为 `0°` | `XX degrees left-front view` |

提示词顺序：基础摄影与当前角度 → 商品身份/结构/颜色/材质/文字/Logo/包装一致性 → 用户补充提示词。任务执行与历史恢复只读提交快照。

#### MA-R-03 输出比例继承

- 上传主体图是唯一宽高比来源，不使用模型默认 `1:1` 覆盖。
- 所有角度请求使用同一输入宽高比；返回后以最终文件实际像素校验。
- 比例不符不得标记成功或下载，不得用非等比拉伸修正；进入现有失败/单图重试流程。
- 本期只锁定比例，不新增固定像素尺寸；历史结果不追溯改图，继续编辑或重新提交时按源图重新固化。

### 6.4 数据、责任与异常

| 字段 | 类型 | 必填 | 规则 |
|---|---|---|---|
| `source_width` / `source_height` | 正整数 | 是 | 图片不可读取时不得提交 |
| `output_aspect_ratio` | 字符串 | 是 | 由源图计算；字段名建议，待技术确认；不可回退 `1:1` |
| `angle_snapshot` | 对象数组 | 是 | 保存方向 ID、显示名、角度、方位、英文描述和完整提示词 |
| `actual_width` / `actual_height` | 正整数 | 是 | 结果文件实际像素，用于成功校验 |

- 前端负责编辑与会话状态；任务服务负责源图/角度快照、请求参数和结果校验；AI 模型按参数生成，不承担页面状态。
- 角度空值/非数字恢复当前有效值或默认 `45°`；比例不符按现有单图失败处理；积分、历史和重试规则沿用平台现有逻辑。

### 6.5 验收与证据

| 编号 | 关联项 | 操作 | 预期结果 | 类型 |
|---|---|---|---|---|
| MA-AC-01 | MA-CHG-01、MA-R-01 | 检查 8 个方向并点击 | 四个固定方向无编辑；斜角主体选中，铅笔编辑 | 交互 |
| MA-AC-02 | MA-R-01 | 输入 `22`、`23`、负数、超过 `90` | 纠正为 `20°`、`25°`、`0°`、`90°` | 边界 |
| MA-AC-03 | MA-R-01 | 修改后取消、外部点击、`Escape` | 均不保存，选中状态不变 | 取消 |
| MA-AC-04 | MA-R-01 | 修改后恢复默认 | 四个斜角恢复 `45°`，已选数量不变 | 联动 |
| MA-AC-05 | MA-CHG-02、MA-R-02 | 编辑斜角和补充提示词后提交 | 快照完整；提交后页面修改不影响任务 | 数据/兼容 |
| MA-AC-06 | MA-CHG-03、MA-R-03 | 上传 `4:3` 图生成 2–8 个角度 | 每个成功结果实际比例均为 `4:3` | Bug 修复 |
| MA-AC-07 | MA-R-03 | 上传其他非 `1:1` 比例生成 | 所有成功结果继承输入比例 | 兼容 |
| MA-AC-08 | MA-R-03 | 模型返回比例不一致结果 | 不进入成功和下载，进入现有失败/重试 | 异常 |
| MA-AC-09 | MA-CHG-01/02 | 编辑多个斜角、恢复默认并提交 | 参数事件记录结构化角度变化；任务快照与生成结果按 `direction_id/result_index` 对应 | 埋点/联动 |
| MA-AC-10 | MA-CHG-03、MA-R-03 | 模拟返回比例不一致并重试成功 | 首次结果记录比例失败且不进入成功分子；重试结果使用独立 `result_id` 或版本关联，最终计数不重复 | 埋点/异常 |

- 原型/证据：`MultiAnglePage.jsx`、`multi-angle.js`、`multi-angle-editing.test.mjs`；比例问题来源为用户反馈，尚无修复完成证据。

### 6.6 埋点与效果衡量

#### 6.6.1 归属与事件

- 沿用 `tool_key=ai_multi_angle`。角度编辑是任务参数行为，只有后台 `task_created` 才计功能实际使用。
- 完整提示词不得进入分析事件；仅保存 `direction_id`、目标角度、实际方位角和是否自定义等结构化快照。任务业务快照可按第 6.3 节保存完整提示词，但应与分析事件隔离。

| 事件 | 上报端 | 触发/成功时机 | 本模块必填业务字段 | 去重/幂等 | 指标用途 |
|---|---|---|---|---|---|
| `local_upload_success` / `material_select_success` | 前端/上传服务 | 主体图上传或素材回填成功 | `input_type=source_image`、`source_width`、`source_height`、`source_aspect_ratio`、`asset_id` 或 `file_count` | 按 8.1 公共规则 | 输入比例和来源分布 |
| `parameter_change` | 前端 | 方向选中、斜角确认修改或恢复默认实际生效 | `param_key=direction_selected/angle_value/restore_default`、`direction_id`、`angle_value`、`previous_value`、`is_custom_angle` | `event_id` | 角度编辑使用率、方向偏好；不计任务使用 |
| `task_submit_click` | 前端 | 2–8 个方向及源图校验通过后点击生成 | `request_id`、`selected_direction_count`、`custom_angle_count`、`source_width`、`source_height`、`output_aspect_ratio`、`expected_result_count` | `event_id` | 提交意图与创建漏斗 |
| `task_created` / `task_create_failed` | 后端 | 角度与比例快照创建成功 / 创建失败 | 公共任务字段；成功增加 `selected_direction_count`、`custom_angle_count`、`source_width`、`source_height`、`output_aspect_ratio`；失败含 `error_code` | `task_id` / `request_id` | 实际使用、任务创建成功率、比例分布 |
| `task_status_change` / `task_finished` / `credit_settled` | 后端 | 状态变化、任务终态、积分结算完成 | 按 8.1 公共字段；`task_finished` 含成功/失败结果数 | 分别按公共规则 | 成功率、耗时、成本 |
| `result_created` | 后端 | 每个角度的最终文件完成像素读取和比例校验 | `result_id`、`task_id`、`result_index`、`image_role=angle`、`direction_id`、`angle_value`、`is_custom_angle`、`actual_width`、`actual_height`、`aspect_ratio_match`、`result_status`；不符时 `error_code=ASPECT_RATIO_MISMATCH` | `result_id`；返修版本需可追溯来源结果且不覆盖原事实 | 方向成功率、比例不符率、成功结果数 |
| `task_retry` | 前端/后端 | 用户对失败角度主动重试且执行创建成功 | `task_id`、`result_id`、`direction_id`、`retry_scope=single_result` | 重试任务/版本 ID | 单角度返修率 |
| `result_download_success` / `result_continue_edit_success` / `result_add_asset_success` / `result_approve_success` / `result_reject` | 前端/后端 | 对应动作实际成功 | 按 8.1 公共采纳字段，保留 `direction_id` | 按 `result_id` 区分行为次数和去重采纳 | 采纳、否定、资产沉淀 |

#### 6.6.2 指标、异常与验收

| 指标 | 计算口径 |
|---|---|
| 角度编辑使用率 | `custom_angle_count>0` 的 `task_created` 数 / AI 多角度任务数 |
| 各方向生成失败率 | 各 `direction_id` 的最终失败 `result_id` 数 / 该方向全部最终结果数 |
| 结果比例不符率 | `aspect_ratio_match=false` 的结果数 / 已完成像素校验的结果数 |
| 比例错误误放行数 | `aspect_ratio_match=false and result_status=SUCCESS` 的结果数；上线验收必须为 0 |
| 核心链路成功率 / 生成采纳率 | 按 8.1 公共任务与采纳口径，比例不符结果不得进入分子 |

- 源图不可读时前端阻止提交，仅记录上传/校验失败诊断，不产生 `task_created`。最终文件缺少宽高时按结果校验失败处理，必须记录 `failure_stage=result_validation`。
- 埋点验收至少覆盖默认角度、自定义角度、恢复默认、`4:3` 成功、非 `1:1` 成功、比例不符失败及单角度重试，逐条核对源比例、请求快照与最终文件尺寸。

## 7. 素材库 / 提示词库导航

### 7.1 目标、流程与规则

| 编号 | 变更内容 | 当前/目标状态 |
|---|---|---|
| NAV-CHG-01 | 顶部素材库、提示词库在新标签页打开 | 当前原标签页跳转，待开发 |
| NAV-CHG-02 | 原创作页不跳转、不刷新、不清空任务 | 待开发 |
| NAV-CHG-03 | 新标签页被阻止时不回退当前页跳转 | 待开发 |

#### NAV-R-01 新标签页与范围边界

- 仅调整顶部全局导航的素材库、提示词库；工作台内选择器继续使用现有弹窗。
- 点击后由浏览器在新标签页或窗口打开；原创作页 URL、输入、配置和任务状态不变。
- 新页面与原页面隔离窗口控制关系；浏览器阻止时原页面保持不变，不回退当前页。
- 资源库权限、审批、数据和页面功能沿用现有逻辑。

### 7.2 责任、验收与证据

- 前端导航负责打开策略和原页保护；资源库页面、任务服务、AI Skill、权限和数据均无本期变化。

| 编号 | 关联项 | 操作 | 预期结果 | 类型 |
|---|---|---|---|---|
| NAV-AC-01 | NAV-CHG-01/02、NAV-R-01 | 创作页有未提交图片配置，点击素材库 | 新标签页打开；原 URL、图片、配置不变 | 导航/反馈 |
| NAV-AC-02 | NAV-R-01 | 创作页有进行中任务，点击提示词库 | 新标签页打开；原任务继续展示和执行 | 导航/反馈 |
| NAV-AC-03 | NAV-CHG-03、NAV-R-01 | 浏览器阻止新标签页 | 原页保持当前状态，不回退跳转 | 异常 |
| NAV-AC-04 | NAV-CHG-01～03 | 分别成功打开素材库、提示词库并模拟浏览器阻止 | 点击、打开结果和目标页访问事件可由 `session_id/trace_id` 关联；任何事件均不计工具任务成功或采纳 | 埋点/口径 |

- 当前证据：`Topbar.jsx` 和 `navigation.js` 仍为普通站内链接，属于待修复现状。

### 7.3 埋点与效果衡量

#### 7.3.1 归属与事件

- 顶部导航使用 `nav_click`，通过 `nav_key/resource_key` 区分素材库和提示词库；它只表示入口点击，不计工具实际使用、任务成功或结果采纳。
- 正式旧埋点方案曾因当时无独立提示词库入口将相关行为并入 `ai_prompt`。本期已存在独立提示词库页面，顶部导航和目标页访问必须按实际 `target_path/page_path` 记录；工作台内模板选择继续使用 `prompt_template_selected`，不可照搬旧页面基线。

| 事件 | 上报端 | 触发/成功时机 | 必填业务字段 | 去重/幂等 | 指标用途 |
|---|---|---|---|---|---|
| `nav_click` | 前端 | 点击顶部素材库或提示词库，准备调用新标签页打开 | `nav_key`、`resource_key=materials/prompt_library`、`target_path`、`source_page`、`session_id`、`trace_id`、`open_target=new_tab` | `event_id` | 入口点击和来源页分布；不代表打开成功 |
| `resource_new_tab_open_result` | 前端 | 浏览器打开调用同步返回后 | `resource_key`、`target_path`、`trace_id`、`open_status=success/blocked/failed`；失败时 `error_code` | `trace_id` 仅保留一次最终结果 | 新标签页打开成功率、阻止率；本期专属新增事件 |
| `page_view` | 目标页前端 | 新标签页中的目标资源页面真实渲染完成 | `page_path`、`resource_key`、`session_id`；可带来源 `trace_id` | `event_id` | 目标页到达；不得由原页预先上报 |

#### 7.3.2 指标、异常与验收

| 指标 | 计算口径 |
|---|---|
| 新标签页打开成功率 | `open_status=success` 数 / `nav_click` 数，按 `resource_key` 分组 |
| 浏览器阻止率 | `open_status=blocked` 数 / `nav_click` 数 |
| 目标页到达率 | 可与来源 `trace_id` 关联的目标页 `page_view` 数 / `open_status=success` 数 |
| 原页状态保持失败数 | 自动化/异常监控发现点击后原页 URL、输入或任务状态丢失的次数；上线验收必须为 0，不以普通 `nav_click` 推断 |

- 工作台内素材选择器、提示词模板弹窗不记录顶部 `nav_click`；分别使用 `material_select_success`、`asset_reuse`、`prompt_template_selected`。
- 浏览器阻止新标签页时只记录 `open_status=blocked`，原页不得跳转。埋点失败不得触发降级跳转；由 `analytics_report_retry` 补偿且不重复累计。

## 8. 平台公共规则与跨模块影响

| 公共能力 | 使用模块 | 本期处理 |
|---|---|---|
| 商品选择 | AI 商详焕新、AI 买家秀、主体替换 | 统一使用第 5 章资格、回填与快照；各模块按自身流程消费 |
| 素材选择 | AI 商详焕新及既有工作台 | 沿用个人/团队/公共/本地素材选择、权限和图片队列规则 |
| 历史记录 | 所有生成模块 | 沿用平台现有创建、恢复、继续编辑和版本规则；只增加本期任务快照 |
| 权限 | 三个商品使用方及资源库 | 沿用现有账号和资源可见范围，服务端鉴权不得因新入口放宽 |
| 积分/计费 | AI 商详焕新、AI 买家秀、主体替换、AI 多角度 | 沿用现有首次生成、重试、微调、失败和退费规则，本期不新增价格或扣费时机 |
| 下载 | AI 商详焕新、AI 多角度 | 沿用现有命名和文件规则；只有成功结果可下载；点赞不作为商详下载前置 |
| 任务超时与并发 | 所有生成模块 | 沿用平台现有任务队列，不在本 PRD 编造数值；商详三次内部重试需由技术方案评估编排 |

### 8.1 公共埋点继承规则

本期埋点以《先马 AI 设计平台埋点需求 PRD V1.0》（2026-07-27）为基础，结合《埋点与效果衡量》功能地图和后续数据智能报表口径执行。各模块章节定义业务归属和专属字段，本节只定义所有模块必须一致的公共契约。

#### 8.1.1 事件分层与事实源

| 层级 | 事件 | 作用 | 是否进入核心事实指标 |
|---|---|---|---|
| 访问/意图 | `page_view`、`nav_click`、`tool_entry_click`、`parameter_change`、`task_submit_click` | 入口、配置和漏斗分析 | 否，不作为实际使用、成功、采纳或成本事实 |
| 输入成功 | `material_select_success`、`local_upload_success`、`prompt_template_selected`、商品选择器诊断事件 | 诊断输入来源和组件使用 | 否；素材核心复用需与任务创建绑定 |
| 任务事实 | `task_created`、`task_create_failed`、`task_status_change`、`task_cancelled`、`task_retry`、`task_finished` | 实际使用、状态、成功率和耗时 | 是，以后端任务事实为准 |
| 结果/结算事实 | `result_created`、`credit_settled` | 结果数量、质量、成本 | 是，以后端结果和积分事实为准 |
| 采纳事实 | `result_download_success`、`result_continue_edit_success`、`result_add_asset_success`、`result_approve_success`、`text_copy_success`、`text_export_success` | 结果实际进入后续业务 | 仅动作实际成功后进入 |
| 质量反馈 | `result_preview`、`result_reject` | 查看和否定分析 | 预览不计采纳；否定只进入否定率 |
| 历史/复用 | `history_continue_edit_success`、`asset_reuse`、`prompt_apply_to_tool_success` | 跨任务复用 | 成功事实可进入复用指标 |
| 数据质量 | `analytics_report_retry` | 埋点失败补偿 | 否，不进入业务指标 |

- 前端只记录访问、配置和提交意图；后端任务、结果、积分、历史和素材事实是最终统计口径。前后端冲突时不得用前端点击覆盖后端事实。
- `material_select_success` 只表示素材成功回填选择器；素材核心复用以任务创建成功并完成 `asset_id+task_id` 绑定后的 `asset_reuse` 或等价素材使用事实为准。
- 商详内部自动重试、模型候选和质检失败不得伪装成用户 `task_retry` 或成功结果。

#### 8.1.2 公共字段与关联

| 字段组 | 必填要求 | 规则 |
|---|---|---|
| 事件身份 | `event_id`、`event_name`、`event_time` | `event_id` 全局唯一；时间优先使用服务端接收/事实发生时间并明确时区 |
| 用户与组织 | `user_id`；可取时保存 `department_id_at_event`、`role_key_at_event` | 不使用姓名作主键；组织归属使用事件发生时快照，避免转部门后历史漂移 |
| 页面与功能 | `page_path`、`source_page`、`tool_key/module_key`、`session_id`、`trace_id` 按事件适用 | `tool_key` 使用 snake_case；公共组件同时带 `target_tool_key` |
| 请求与任务 | `request_id`、`task_id` | 无 `task_id` 的创建失败以 `request_id` 关联；成功创建后以 `task_id` 为主关联键 |
| 业务实体 | `result_id`、`history_id`、`credit_record_id`、`asset_id`、`product_id`、`confirmed_version_id` 按事实适用 | 必须通过 `task_id` 串联任务、结果、历史、积分和素材；商品快照由任务事实关联 |
| 状态与错误 | `task_status/result_status`；失败时 `error_code/failure_stage` | 状态、错误码和失败阶段使用受控枚举；展示文案不可作为统计字段 |
| 数量与耗时 | `expected_result_count`、`success_result_count`、`failed_result_count`、`duration_ms` | 任务终态必须满足结果计数校验；耗时非负且时间缺失需单独监控 |

字段名优先复用现有埋点、任务、结果、积分和素材结构。本文出现的新字段名为产品语义建议，开发不得改变含义；技术方案需输出实际字段映射。

#### 8.1.3 公共事实事件最低契约

| 事件 | 上报端与触发时机 | 最低必填字段 | 去重键 |
|---|---|---|---|
| `task_created` | 后端，任务及提交快照创建成功 | `task_id`、`user_id`、`tool_key`、`task_status`、`submit_time`；可关联时带 `request_id/expected_result_count/model_key` | `task_id` |
| `task_create_failed` | 后端，任务创建失败且无有效任务 | `request_id`、`user_id`、`tool_key`、`error_code` | `request_id` |
| `task_status_change` | 后端，任务状态真实变化 | `task_id`、`old_status`、`new_status`、`event_time`；失败时 `error_code/failure_stage` | 状态版本号；无版本时 `task_id+new_status+event_time` |
| `task_cancelled` | 前端/后端，取消或系统终止事实落定 | `task_id`、`user_id`、`tool_key`、`cancel_time` | `task_id+cancel_time` |
| `task_retry` | 前端/后端，用户主动重试执行已创建 | `task_id`、`user_id`、`tool_key`、`retry_from_task_id` 或来源结果 | 新重试任务 ID；原任务内版本重试按版本 ID |
| `task_finished` | 后端，任务进入最终态且结果计数落定 | `task_id`、`tool_key`、`task_status`、`duration_ms`、`success_result_count`、`failed_result_count`；失败时 `error_code` | `task_id` |
| `credit_settled` | 后端，扣减、退回或不扣费结算完成 | `task_id`、`settle_type`、`credit_cost`；有积分流水时 `credit_record_id` | `credit_record_id`；无流水时 `task_id+settle_type` |
| `result_created` | 后端，单结果最终事实形成 | `result_id`、`task_id`、`tool_key`、`result_type`、`result_status`；图片按需带 `result_index/image_role` | `result_id` |
| 成功采纳事件 | 前端/后端，对应下载、编辑、加素材、认可、复制或导出实际成功 | `event_id`、`user_id`、`result_id/source_id`、`tool_key`；图片/视频按需 `task_id` | 行为按 `event_id`；采纳结果按 `result_id+user_id` 聚合去重 |
| `result_reject` | 前端/后端，待调整/否定状态保存成功 | `event_id`、`user_id`、`result_id`、`tool_key`；可选 `reason_key` | 行为按 `event_id`，结果指标按 `result_id` 去重 |
| `asset_reuse` | 前端/后端，素材作为输入且与成功创建任务绑定 | `event_id`、`user_id`、`asset_id`、`target_tool_key`、`task_id` | `asset_id+target_tool_key+task_id` |
| `analytics_report_retry` | 前端/后端，对原失败事件补偿上报 | `event_id`、`original_event_id`、`retry_count` | `original_event_id` |

#### 8.1.4 采纳、去重与指标总口径

- 成功下载、成功进入继续编辑、成功加入素材库、认可/点赞保存成功、文本复制或导出成功计为采纳；仅预览、点击失败、待调整/否定不计采纳。
- 同一结果发生多个成功采纳动作时，行为次数分别统计；被采纳结果数按 `result_id` 去重，只增加一次采纳分子。整组下载应展开关联其中实际下载成功的结果，不能把失败结果计入采纳。
- 功能实际使用次数 = 后台成功创建的去重任务数；核心链路成功率 = 最终成功任务数 / 成功创建任务数；生成采纳率 = 有至少一次成功采纳动作的去重成功结果数 / 成功结果数。
- 结果否定率 = 去重否定结果数 / 成功结果数；平均处理时长只使用成功或部分成功且时间完整的任务。
- 人均生成成本、单任务成本、单成功任务成本、单有效生图产出成本分别以 `credit_settled` 的实际积分净消耗除以生图活跃用户、创建任务、成功任务、被采纳图片/视频结果。既有积分规则不因本期埋点而改变。
- 人工基准耗时暂无正式数据，本期只记录 AI 实际耗时，不得编造节省工时或自助率。

#### 8.1.5 异常、安全与数据生效

- 埋点上报必须异步且不得阻塞页面、任务、下载、编辑、反馈或积分主流程；失败时可缓存补偿，使用原 `event_id` 幂等，补偿次数记录 `analytics_report_retry`。
- 不记录图片真实 URL、文件内容、完整提示词、模型原始响应、商品事实全文、客户/订单/账号密钥或其他敏感原文。搜索仅记录是否搜索和字符长度。
- 历史数据不反向补造、不依据当前商品版本回填旧任务。指标从埋点正式生效且完成数据验收的时间点开始统计，看板需展示数据生效时间。
- 上线前由开发输出事件映射清单：`EXISTING`（现有事件字段足够）、`EXISTING_ENHANCE`（沿用事件但补字段/时机）、`NEW_THIS_PHASE`（本期新增）。没有实现证据时不得将 PRD 定义描述为已上线。

### 8.2 公共埋点验收

1. 每个前端提交事件能通过 `request_id/trace_id` 关联后端创建成功或失败事实；创建成功后全链路统一使用 `task_id`。
2. 每个结束任务可关联结果和积分；发生历史保存、继续编辑或加入素材库时，可进一步关联 `history_id/asset_id`。
3. 重复上报、页面刷新、网络补偿不重复增加核心任务、结果、积分和采纳分子。
4. 模拟前端和后端埋点上报失败，主业务仍可完成；补偿后指标不重复。
5. 检查数据样本中无原图 URL、完整提示词、搜索原文和其他敏感内容。
6. 按功能核对点击、任务创建、任务成功、结果和采纳各层事实；任何点击或预览都不得反向补算为任务创建、任务成功或结果采纳。

## 9. 需求追踪矩阵

| 变更 | 规则 | 验收 | 原型/证据 | 当前状态 |
|---|---|---|---|---|
| DR-CHG-01～02 | DR-R-01 | DR-AC-01/02 | 商详原型与专项测试 | 前端原型已定稿，真实服务待开发 |
| DR-CHG-03/10 | DR-R-04 | DR-AC-06/12 | `xianma_detail_refresh`、真实测试报告 | Skill 已验证，生产编排待开发 |
| DR-CHG-04/08 | DR-R-03、PP-R-01/02 | DR-AC-05、PP-AC-01/02 | 商详原型、公共选择器集成测试 | 前端原型已定稿，真实商品服务待开发 |
| DR-CHG-05 | DR-R-06 | DR-AC-07/10/17/19/20 | 商详原型与提示词契约 | 前端原型已定稿，AI 链路待开发 |
| DR-CHG-06/07 | DR-R-07 | DR-AC-08/09/14/15 | 商详原型与专项测试 | 原型已定稿，真实任务服务待开发 |
| DR-CHG-09 | DR-R-02/03 | DR-AC-03/04/05/11 | `xianma_detail_refresh`、真实测试报告 | Skill 已验证，生产编排待开发 |
| DR-CHG-11/12 | DR-R-08 | DR-AC-08/10/12/13 | `xianma_detail_refresh`、R-03 复测报告 | Skill 已验证，生产编排待开发 |
| DR-CHG-13 | DR-R-07/08 | DR-AC-16/18 | 商详原型、平台现有规则 | 保持现状并联调回归 |
| DR-CHG-01～13 埋点 | 2.13、8.1 | DR-AC-21/22、8.2 | 正式埋点 PRD、数据智能口径 | 事件实现状态待技术盘点 |
| BS-CHG-01～03 | BS-R-01 | BS-AC-01～05 | 买家秀原型与专项测试 | 原型已定稿，真实接口待开发 |
| BS 埋点 | 3.5、8.1 | BS-AC-04/05、8.2 | 正式埋点 PRD | 事件实现状态待技术盘点 |
| SR-CHG-01～03 | SR-R-01 | SR-AC-01～05 | 主体替换原型与集成测试 | 原型已定稿，真实接口待开发 |
| SR 埋点 | 4.5、8.1 | SR-AC-04/05、8.2 | 正式埋点 PRD | 事件实现状态待技术盘点 |
| PP-CHG-01～03 | PP-R-01～03 | PP-AC-01～06 | 公共选择器与集成测试 | 原型已定稿，公共服务待开发 |
| PP 埋点 | 5.6、8.1 | PP-AC-05/06、8.2 | 正式埋点 PRD | 组件诊断事件待技术盘点 |
| MA-CHG-01～02 | MA-R-01～02 | MA-AC-01～05/09 | 多角度原型与专项测试 | 原型已定稿，任务持久化待开发 |
| MA-CHG-03 | MA-R-03 | MA-AC-06～10 | 用户反馈 | 待真实链路修复 |
| MA 埋点 | 6.6、8.1 | MA-AC-09/10、8.2 | 正式埋点 PRD | 事件实现状态待技术盘点 |
| NAV-CHG-01～03 | NAV-R-01 | NAV-AC-01～04 | 当前导航代码、用户反馈 | 待开发 |
| NAV 埋点 | 7.3、8.1 | NAV-AC-04、8.2 | 正式埋点 PRD | 新标签页结果事件待技术盘点 |
| MN-CHG-01～04 | MN-R-01～05 | MN-AC-01～09/13 | `/materials` 上传弹窗、命名专项测试 | 本地前端原型已完成，真实识别服务待开发 |
| MN-CHG-05～06 | MN-R-01/04/06 | MN-AC-10/11/14/15 | 共享素材选择器、素材入库、卡片、详情、编辑与搜索代码 | 原型字段契约已实现，真实跨入口上传/查询服务待联调 |
| MN 埋点 | 12.13、8.1 | MN-AC-12/14、8.2 | 用户确认的指标口径 | 事件实现状态待技术盘点 |
| VP-CHG-01～04 | VP-R-01～05 | VP-AC-01～11 | 用户需求说明、AI 视频流与无限画布既有流程 | 预处理服务与模型接入待开发 |

## 10. 技术待确认与版本交付

### 10.1 技术待确认

| 编号 | 事项 | 责任方 | 产品边界 |
|---|---|---|---|
| TECH-01 | 商详具体模型路由、参考图传参和提示词适配 | AI/后端开发 | 不得改变双模式事实源和五项业务成功标准 |
| TECH-02 | Skill 内部最多 3 次自动重试与平台任务队列、超时、并发的编排 | 后端开发 | 不新增用户确认步骤，达到上限返回现有失败状态 |
| TECH-03 | 公共商品列表、服务端鉴权和 `product_snapshot` 复用现有接口/对象的方案 | 商品服务/后端 | 不扩大权限，提交时固化有效确认版本 |
| TECH-04 | 多角度输入比例传参、模型能力适配和最终文件像素校验位置 | AI/后端开发 | 比例不符不得进入成功，不允许非等比拉伸 |
| TECH-05 | 新标签页打开实现及浏览器阻止场景处理 | 前端开发 | 原标签页不得跳转或清空 |
| TECH-06 | 对照正式埋点方案盘点本期事件，逐项标记 `EXISTING / EXISTING_ENHANCE / NEW_THIS_PHASE`，输出事件名、实际上报端、字段映射、状态枚举、错误码、幂等键和数据生效时间 | 前后端/数据 | 不改变各模块指标与事实层级；点击/预览不得替代任务、结果或采纳事实 |
| TECH-07 | 确认埋点物理存储、异步补偿、任务/结果/积分/历史/素材关联和数据验收方式 | 后端/数据 | 必须以 `task_id` 串联核心事实，补偿不重复计数，埋点失败不阻塞主业务，历史数据不补造 |
| TECH-08 | 确定统一图片预处理服务/库、双线性缩放、格式保持、压缩质量策略及模型请求接入位置 | 前端/后端/AI | 三个指定视频模型使用同一业务规则；不得覆盖原图，不增加 AI 超分成本；处理失败按本章降级规则执行 |
| TECH-09 | 素材图片识别模型接入、结构化槽位校验、主动上传与工作台快捷入库字段映射、后台异步更新、同名序号并发原子分配、事件映射和识别超时策略 | 前端/素材服务/AI/数据 | 不改变 MN 状态、命名、失败回退、主动上传人工保护、快捷入库不阻塞和不扣积分规则；不得记录图片、文件名、URL或模型原始响应 |

产品侧待确认项：无。以上由开发在技术方案中确定，不改变本期产品范围。

### 10.2 联调范围与上线验收

- AI 商详焕新：前端工作台、任务服务、`xianma_detail_refresh`、模型服务、商品/素材、历史、积分、下载端到端联调；真实文件验证五项门禁和对应源图尺寸。
- 商品选择：三个工作台与真实商品列表、权限鉴权、有效确认版本、任务快照和历史恢复联调。
- AI 多角度：页面角度快照、生成请求、模型输出和服务端文件比例校验联调，重点覆盖 `4:3` 与其他非 `1:1` 输入。
- AI 视频素材预处理：AI 视频流和无限画布分别覆盖海螺 H3、Seedance 2、Seedance 2.5，验证小图放大、合规大图直传、格式保持、30MB 压缩、比例越界不裁剪、原图下载不变和预处理失败降级。
- 资源导航：有未提交输入和进行中任务时验证新标签页、原页状态保持及浏览器阻止场景。
- 素材图片自动命名：`/materials` 上传弹窗、素材上传服务、图片识别模型、类目映射、同名序号、素材查询/搜索和埋点端到端联调；使用 30 张代表图片完成 MN-AC-12，并回归其他入库入口不触发识别。
- 上线前核对平台现有权限、积分、历史和下载行为未被本期改动破坏；完成 8.2 公共埋点验收及各模块专项链路抽样，确认数据生效时间后再用于上线后复盘。

### 10.3 已知限制与回滚影响

- 商详不做历史相似度判断；模型具体效果需以真实联调素材验收，不在 PRD 承诺成功率或耗时。
- AI 多角度自定义角度是近似目标，存在页面已披露的 `±15°` 效果偏差；宽高比必须严格满足。
- 回滚 AI 商详入口或内部链路时不得影响既有批量改图；已提交任务与历史快照需保持可读。
- 回滚公共商品选择接入时应恢复各工作台原有手动流程，不删除已保存的商品快照。
- 回滚多角度斜角编辑时历史 `angle_snapshot` 仍需可读；比例修复不得回滚为允许比例错误结果成功。
- 回滚资源导航时不得以恢复原标签页跳转作为长期方案；具体技术回滚步骤由开发补充。
- 回滚视频预处理时可关闭入参适配开关，但不得删除原图或历史任务；回滚前后需保留模型调用日志中的原图与处理图关联，避免无法追溯。
- 素材图片自动命名当前处理 `/materials` 新上传图片和工作台勾选顺带入库的本地图片，不覆盖存量、音视频、AI 生成结果或历史结果；真实模型效果需以 MN-AC-12 验收。
- 回滚素材图片自动命名时关闭素材库上传前识别和工作台快捷入库后台识别，恢复原手动/原文件名入库流程；已入库素材及其最终名称、类目、标签和原文件名不回退、不删除。

### 10.4 配套交付物

| 交付物 | 状态 | 位置/说明 |
|---|---|---|
| 本期 PRD | 已完成 | 本文 V1.2，知识库正式源与仓库 `docs` 副本 |
| 定稿原型 | 已完成 | 商详、买家秀、主体替换、商品选择器、斜角编辑、素材库图片自动识别命名已定稿 |
| AI Skill / 提示词规范 | 已完成 | `.agents/skills/xianma_detail_refresh/`；本章定义产品契约 |
| 商详测试素材与报告 | 已完成现有验证 | 两组 4 张真实测试及 R-03 复测报告；不代表生产验收 |
| 验收矩阵 | 已完成 | 各模块 `*-AC-*` 与第 9 章追踪矩阵 |
| 素材命名测试素材与验收矩阵 | 规则已完成，真实素材待补充 | 纯函数与交互专项测试；30 张代表图片由联调阶段准备 |
| 技术方案 | 待开发补充 | 覆盖 TECH-01～09、接口/字段落地、事件现状映射、任务编排和回滚步骤 |
| 联调记录与上线清单 | 待开发完成后补充 | 真实接口、权限、积分、历史、结果文件和埋点证据 |

## 11. AI 视频素材尺寸预处理

### 11.1 背景、目标与范围

- 背景：部分用户上传的小尺寸图片（例如 `226×300`）不满足视频模型图片输入的最小尺寸要求，直接调用会失败；同类产品在上传阶段自动放大后可以正常生成。
- 目标：在图片上传或进入视频生成素材后、调用模型 API 前自动检测并适配图片尺寸，降低因尺寸不足导致的生成失败，同时保持用户原图可查看、可下载。
- 影响页面：AI 视频流（参考图、首帧图、首尾帧图等上传入口）和无限画布（画布中插入图片后作为视频生成素材）。
- 适用模型：海螺 H3、Seedance 2、Seedance 2.5。三者统一执行本章预处理规则。

### 11.2 本期变更

| 编号 | 变更内容 | 影响范围 |
|---|---|---|
| VP-CHG-01 | 新增模型调用前图片实际像素检测 | AI 视频流、无限画布视频生成入口 |
| VP-CHG-02 | 对宽或高小于 300px 的图片等比放大至短边 512px | 预处理服务、三种视频模型入参 |
| VP-CHG-03 | 放大后保持原格式；超过 30MB 时自动压缩至模型限制 | 图片处理与上传链路 |
| VP-CHG-04 | 处理图仅供模型调用，原图不覆盖；小图显示非阻塞提示 | 两个影响页面的缩略图/素材状态 |

### 11.3 触发时机与用户流程

1. 用户在 AI 视频流上传参考图、首帧图或首尾帧图，或在无限画布插入图片并选择视频生成功能。
2. 平台读取图片实际像素宽高、格式、文件大小和宽高比；读取失败时按 VP-R-05 处理。
3. 当前模型为海螺 H3、Seedance 2 或 Seedance 2.5 时执行尺寸判断；其他模型不触发本规则。
4. 若宽高均不小于 300px，保留原图作为模型输入，不显示放大提示。
5. 若宽或高小于 300px，使用双线性插值等比放大，使较短边达到 512px，较长边按比例同步放大并取整数像素。
6. 放大后仍保持原格式；若文件超过 30MB，在不改变像素尺寸和宽高比的前提下压缩质量至模型限制内。
7. 预处理图上传给模型，原图继续用于缩略图、预览、历史展示和用户下载。
8. 批量上传时逐张独立判断和处理，仅被放大的图片显示提示。

### 11.4 业务规则

#### VP-R-01 模型与输入场景

| 模型 | 图片输入场景 | 最小尺寸 | 单张大小上限 | 比例范围 |
|---|---|---|---|---|
| 海螺 H3 | 参考图（最多 9 张）、首帧图 | 宽高均 ≥ 300px | < 30MB | 0.4–2.5 |
| Seedance 2 | 首帧图、首尾帧图、参考图（最多 30 张） | 宽高均 ≥ 300px | < 30MB | 0.4–2.5 |
| Seedance 2.5 | 首帧图、首尾帧图、参考图（最多 30 张） | 宽高均 ≥ 300px | < 30MB | 0.4–2.5 |

模型展示名称以本表为准；实际 `model_key` 沿用模型管理配置，开发在技术方案中完成映射。

#### VP-R-02 尺寸适配

- 判断使用图片文件实际像素，不使用 CSS 展示尺寸或客户端缩略图尺寸。
- 宽高均 `≥300px`：不生成处理副本，模型直接使用原图。
- 宽或高 `<300px`：按 `scale=512/min(width,height)` 等比放大；例如 `226×300` 输出 `512×679`，`300×226` 输出 `679×512`。
- 处理后宽高均必须 `≥300px`，宽高比与原图一致；禁止裁剪、补边、拉伸变形或改变方向。
- 双线性插值为固定算法，不调用 AI 超分，不增加额外模型费用。

#### VP-R-03 格式与文件大小

- JPG、PNG、WEBP 处理后分别保持 JPG、PNG、WEBP；透明通道存在时不得因压缩意外丢失，具体编码参数由技术方案确定。
- 放大后文件超过 30MB 时，在保持格式、像素尺寸和宽高比的前提下逐步降低压缩质量，直到满足模型 `<30MB` 限制或达到技术方案定义的最低质量阈值。
- 若在最低质量阈值下仍无法满足大小上限，预处理按失败处理，不伪造合规状态；主流程按 VP-R-05 降级。

#### VP-R-04 比例处理

- 宽高比按 `width/height` 计算并保留原值。
- 比例在 `0.4–2.5` 范围内，按处理后文件调用模型。
- 比例超出范围时不裁剪、不补边、不改变比例，仍按原比例传给模型，由模型侧处理或返回错误。

#### VP-R-05 原图保护与失败降级

- 原图对象不可变；处理图使用独立临时引用或处理版本，不覆盖原文件，不替换用户下载/查看的源文件。
- 预处理失败（像素读取、缩放、编码、压缩或临时存储失败）不阻塞用户继续操作；系统记录结构化失败原因，并降级使用原图请求模型，由模型侧返回最终错误。
- 降级请求不得把预处理失败伪装成尺寸已合规；任务日志必须能区分 `preprocess_success`、`preprocess_skipped`、`preprocess_failed_fallback`。

### 11.5 交互提示

| 场景 | 页面表现 |
|---|---|
| 图片被放大 | 在对应图片缩略图旁显示“图片尺寸较小，已自动放大以适配模型要求” |
| 图片未被放大 | 不显示任何尺寸适配提示 |
| 批量上传 | 仅被放大的图片逐张显示提示，不在页面顶部重复提示 |
| 预处理失败并降级 | 不阻塞上传和配置；沿用平台现有任务/模型错误反馈，不新增强制确认 |

提示为非阻塞信息，不影响排序、删除、预览、继续编辑和提交操作。

### 11.6 数据、责任与埋点

| 字段 | 类型 | 必填 | 规则 |
|---|---|---|---|
| `source_width` / `source_height` | 正整数 | 是 | 原图实际像素；读取失败不可为空 |
| `processed_width` / `processed_height` | 正整数 | 预处理成功时是 | 未处理时与源图一致或按现有结构记录；不得用 CSS 尺寸替代 |
| `source_format` / `processed_format` | 枚举 | 是 | `jpg/png/webp`；格式保持时两者相同 |
| `source_size_bytes` / `processed_size_bytes` | 非负整数 | 是 | 记录处理前后大小；不记录文件内容 |
| `preprocess_action` | 枚举 | 是 | `skipped/scaled/compressed/scaled_and_compressed/failed_fallback` |
| `source_aspect_ratio` / `processed_aspect_ratio` | 数值 | 是 | 处理成功时两者相等；超范围仍保留原值 |
| `video_model_key` | 字符串 | 是 | 关联海螺 H3、Seedance 2、Seedance 2.5 实际配置 |

- 前端负责图片状态提示和原图展示；统一图片预处理服务负责检测、缩放、格式/大小处理和临时引用；视频任务服务负责在 API 调用前接入处理图并记录处理状态。
- 预处理事件建议沿用公共 `local_upload_success/material_select_success` 记录输入来源，并新增 `video_image_preprocess_finished`（字段含 `page_key`、`source_role`、`video_model_key`、上述处理字段、`preprocess_action`、`error_code`）。该事件用于诊断，不替代 `task_created/task_finished`。
- `task_created` 必须携带 `video_model_key`、`preprocess_action` 和处理图关联；`result_created/task_finished` 沿用平台任务事实，不因预处理增加新的成功口径。

### 11.7 验收标准

| 编号 | 关联项 | 前置条件/操作 | 预期结果 | 类型 |
|---|---|---|---|---|
| VP-AC-01 | VP-CHG-01/02、VP-R-01/02 | AI 视频流上传 `226×300` 图片，选择海螺 H3 | 生成请求使用 `512×679` 处理图，不因最小尺寸失败；原图仍为 `226×300` | 正常 |
| VP-AC-02 | VP-R-01/02 | 同一图片分别选择 Seedance 2、Seedance 2.5 | 两个模型均使用相同缩放规则和 `512×679` 比例 | 兼容 |
| VP-AC-03 | VP-R-01/02 | 无限画布插入 `226×300` 图片并调用视频生成 | 生成请求使用合规处理图；画布原素材仍可查看 | 正常 |
| VP-AC-04 | VP-R-02 | 上传 `800×600` 图片调用三个模型 | 不生成缩放副本，直接使用原图且不显示放大提示 | 边界 |
| VP-AC-05 | VP-R-02 | 上传宽或高小于 300px 的横图、竖图和正方图 | 每张处理后短边为 `512px`，宽高比与原图一致，宽高均 ≥300px | 边界 |
| VP-AC-06 | VP-R-03 | 上传 JPG、PNG、WEBP 小图并触发放大 | 处理后格式与原图一致；PNG 透明通道不因处理意外丢失 | 格式 |
| VP-AC-07 | VP-R-03 | 模拟放大后文件超过 30MB | 在不改变像素尺寸、比例和格式的前提下压缩至 `<30MB`；仍不可合规时进入失败降级 | 异常 |
| VP-AC-08 | VP-R-04 | 上传宽高比小于 0.4 或大于 2.5 的图片 | 不裁剪、不补边，按原比例传给模型；页面不伪造比例已修复 | 边界 |
| VP-AC-09 | VP-R-05 | 预处理服务在读取、缩放或压缩阶段失败 | 用户仍可继续配置；记录 `preprocess_failed_fallback`，使用原图请求并沿用模型错误反馈 | 异常 |
| VP-AC-10 | VP-R-05 | 处理后查看或下载原图 | 下载/查看文件仍为用户上传的原始尺寸和格式 | 兼容 |
| VP-AC-11 | VP-CHG-04 | 批量上传大小混合的多张图片 | 仅被放大的图片逐张显示提示，未处理图片不显示 | 交互 |

### 11.8 原型、开发状态与证据

- 当前 AI 视频流和无限画布已有图片输入/视频生成流程；本期新增预处理服务和模型入参接入，属于待开发能力。
- 当前无生产预处理实现或上线验证证据；本章验收需使用真实三个模型和两个影响页面完成端到端验证。

## 12. 素材库图片自动识别命名

### 12.1 问题、目标与当前基线

| 当前能力/问题 | 当前状态 | 本期目标 | 事实来源 |
|---|---|---|---|
| 素材名称录入 | `/materials` 上传后以原文件名去扩展名作为标题，批次共用类目和标签 | 图片上传前生成可编辑的名称、类目和标签建议，减少逐张整理成本 | 当前素材库原型；用户 2026-09-15 确认 |
| 图片识别 | 当前上传弹窗没有识别状态、建议或采纳动作 | 仅对新上传图片逐张异步识别，终态后允许入库 | 当前素材库原型；用户确认 |
| 其他文件与入口 | 同一弹窗支持视频、音频；工作台素材选择器支持本地图片勾选“同时加入个人素材”；AI 工具和历史记录可加入生成结果 | 视频、音频保持原行为；工作台本地图片顺带入库时自动识别，生成结果入库不重复识别 | 当前平台原型；用户 2026-09-15 确认 |
| 数据使用 | 卡片、详情、编辑和搜索读取素材最终标题、原文件名、类目与标签 | 采纳或人工编辑后的最终字段继续被既有消费方直接使用 | `MaterialsClient.jsx`；用户确认 |

本模块目标是缩短新图片入库整理时间、提高名称和标签可检索性，并通过 `naming_source` 为后续效果评估提供审计口径。当前没有人工整理时长基线，效率收益在真实埋点上线后采集，不在本版虚构节省工时。

### 12.2 本期变更

| 编号 | 变更内容 | 影响页面/流程 | 事实来源 |
|---|---|---|---|
| MN-CHG-01 | 新上传图片进入逐张异步识别，终态前禁用上传 | `/materials` 上传弹窗 | 用户确认 |
| MN-CHG-02 | 每张图片展示缩略图、原文件名、状态、建议名称、类目、标签和单张采纳 | 上传文件列表 | 用户确认 |
| MN-CHG-03 | 增加全部采纳，并保护失败项和人工修改项 | 上传文件列表顶部 | 用户确认 |
| MN-CHG-04 | 删除图片批量默认类目/标签；每张图片只保留一套最终字段，视频和音频继续使用统一类目/标签 | 上传批次表单 | 用户 2026-09-15 确认 |
| MN-CHG-05 | 批量上传支持每个文件携带最终标题、类目、标签与命名来源 | 上传入库语义 | 用户确认 |
| MN-CHG-06 | 工作台本地图片勾选“同时加入个人素材”时后台自动应用识别结果；卡片、详情、编辑、搜索和素材选择器消费最终字段 | 共享素材选择器、素材库及消费页面 | 用户 2026-09-15 确认；当前原型 |

### 12.3 用户、入口与前置条件

- **用户与权限：** 沿用素材库现有上传权限、素材范围、个人分组、团队可见组织、审批和共享规则。本期不新增角色或授权。
- **页面入口：** ① 素材库 `/materials` → “上传素材”；② 各工作台共享素材选择器 → “本地上传” → 勾选“同时加入个人素材”。顶部导航新标签页规则与本模块并行生效。
- **输入：** 沿用现有图片、视频、音频选择及上传校验；`/materials` 图片进入可采纳识别，工作台只有本地图片且明确勾选入库时进入自动识别。
- **公共字段：** 素材范围、个人分组和统一备注仍为批次公共字段，不进入图片识别输入。

### 12.4 用户流程

1. 用户打开 `/materials` 上传弹窗并选择一个或多个文件。
2. 系统为每个文件建立独立上传草稿；图片依次进入 `PENDING → PROCESSING`，视频和音频不进入识别状态机。
3. 单张图片识别成功后进入 `READY`，展示建议名称、建议类目和建议标签；识别失败进入 `FAILED`，保留原文件名去扩展名生成的名称、默认“通用”类目和空标签。
4. 用户可对成功图片点击“采纳”，或点击“全部采纳”。采纳同时写入该图片草稿的名称、类目和标签。
5. 用户可编辑任一图片的最终名称、类目或标签；发生编辑后该图片标记为人工修改，“全部采纳”不得覆盖。
6. 当本批次所有图片均进入 `READY` 或 `FAILED` 后，上传按钮恢复可用；用户确认素材范围、个人分组和统一备注后上传。混入视频或音频时可另行设置其统一类目和标签。
7. 系统按每个文件的最终字段入库；素材卡片、详情、编辑、搜索和后续素材选择读取入库结果。
8. 用户移除单个文件或关闭弹窗时，系统取消对应草稿；迟到识别结果不得写回已移除文件、新批次或已关闭弹窗。

工作台快捷入库流程：

1. 用户在任一复用共享素材选择器的工作台切换到“本地上传”，选择图片并勾选“同时加入个人素材”。
2. 用户确认选择后，原图片立即回填当前工作台；当前任务不等待素材命名识别。
3. 素材服务为勾选入库的图片创建个人素材并异步识别；成功后直接应用名称、类目和标签，记录 `naming_source=AI_AUTO`。
4. 识别失败时保留原文件名生成的名称、默认“通用”类目和空标签；用户后续可在素材库编辑。
5. 用户未勾选入库时，只回填当前工作台，不创建素材、不触发命名识别。AI 生成结果或历史结果的“加入素材库”继续沿用其结果名称，不进入本流程。

### 12.5 页面交互与用户文案

| 页面/区域 | 控件或内容 | 触发条件 | 用户操作 | 系统反馈 | 后续状态 |
|---|---|---|---|---|---|
| 上传区 | 文件选择 | 弹窗打开 | 选择图片/视频/音频 | 建立文件草稿；图片显示等待识别 | 图片进入 `PENDING` |
| 图片文件行 | 缩略图、原文件名、大小、状态 | 已选择图片 | 查看或移除 | 状态显示“等待识别 / 识别中 / 识别完成 / 未识别” | 移除后结果作废 |
| 图片建议区 | 建议名称、类目、标签、“采纳” | 状态为 `READY` | 单张采纳 | 三个建议字段同时成为当前值 | `naming_source=AI_SUGGESTION` |
| 文件列表顶部 | “全部采纳” | 至少一张成功且未人工修改、未采纳图片 | 批量采纳 | 仅更新符合条件的图片，并显示可采纳数量 | 失败项、人工修改项不变 |
| 图片当前字段 | 名称、类目、标签 | 已选择图片 | 逐项编辑 | 当前值立即更新 | `manually_edited=true`；`naming_source=MANUAL` |
| 批次表单 | 视频/音频统一类目、统一标签 | 已选择视频或音频 | 修改统一值 | 只更新视频和音频 | 图片字段不受影响；纯图片批次不展示 |
| 弹窗底部 | 上传按钮 | 存在文件且权限字段有效 | 上传 | 任一图片识别未终态时显示“图片识别中”并禁用 | 全部终态后可上传 |
| 工作台本地上传 | “同时加入个人素材”及自动识别说明 | 来源为本地上传 | 勾选后确认选择 | 图片立即回填工作台，入库命名后台执行 | 不阻塞当前任务；成功来源为 `AI_AUTO` |

本期不显示置信度数值、黄红分级、积分消耗、重试按钮、后台规则配置或模型选择。

### 12.6 业务规则

#### MN-R-01 识别范围与触发

- **关联变更：** MN-CHG-01/06。
- `/materials` 上传弹窗中新选择且 MIME 类型为图片的文件触发可采纳识别；视频、音频不触发。
- 工作台共享素材选择器中的本地图片，只有用户勾选“同时加入个人素材”并确认选择后，才随个人素材入库触发后台识别并自动应用；当前工作台不等待识别结果。
- AI 工具生成结果、历史记录中的“加入素材库”不触发识别，也不修改其现有结果名称。
- 存量素材不补识别、不自动重命名；重新编辑存量素材继续沿用既有编辑流程。
- 识别使用平台批准的图片识别模型，不扣用户积分。

#### MN-R-02 建议采纳与人工保护

- **关联变更：** MN-CHG-02/03/04。
- 单张采纳同时应用建议名称、建议类目和建议标签；采纳后仍允许逐项编辑。
- 任一字段被用户编辑后，该图片进入人工修改语义；“全部采纳”只处理 `READY && manually_edited=false && naming_source!=AI_SUGGESTION` 的图片。
- 用户主动再次点击单张“采纳”可用完整建议覆盖当前人工值，并恢复 `AI_SUGGESTION` 来源；该动作是明确的单图覆盖意图。
- 识别失败图片没有可采纳建议，不被“全部采纳”覆盖。

#### MN-R-03 结构化命名

- **关联变更：** MN-CHG-02/05。
- AI 只返回产品主体、人物、场景、姿态和建议类目槽位，不直接自由生成完整标题。产品主体必填；人物、场景、姿态为可选有效槽位。
- `无 / 无人物 / 其他 / 未知 / 不适用 / none / null` 等无效值不进入名称和标签。
- 名称按“产品主体 → 人物 → 场景 → 姿态 → 序号”连接；序号从当前批次和素材库已有最终名称中取同名前缀的下一个可用值。
- 序号至少两位，从 `01` 开始；超过 `99` 后自然扩展为三位及以上，不回绕、不复用。
- 组合名称超过 20 字时，依次删除姿态、人物、场景，始终保留产品主体和序号。若产品主体与序号本身已超过 20 字，不截断产品主体；该情况由用户在上传前人工调整。
- 被名称缩短规则删除的有效槽位仍可进入标签。

#### MN-R-04 类目、标签与默认值

- **关联变更：** MN-CHG-02/04/05。
- 建议类目必须映射到素材库现有固定枚举；“地垫”暂映射为“地毯类”。
- “未分类”只用于历史空值展示，不新增为上传可选类目；无法映射时建议“通用”。
- 建议标签从有效人物、场景和姿态槽位生成，按出现顺序去重，最多 5 个。
- 每张图片只保存并展示一套最终名称、类目和标签；图片上传弹窗不提供批量默认类目或标签。
- `/materials` 未采纳或识别失败图片默认使用“通用”类目和空标签，用户可逐张编辑；已采纳图片使用建议值。
- 视频和音频继续使用现有统一类目和统一标签；混合上传时这些统一值只作用于视频和音频，不覆盖图片。
- 工作台顺带入库识别成功时直接使用建议类目和标签；失败时使用“通用”类目和空标签。
- 原始文件名继续写入现有 `filename`；识别结果和原始文件名不得写入或覆盖统一备注。

#### MN-R-05 异步状态、失败与中断

- **关联变更：** MN-CHG-01/03/05。
- 图片识别状态固定为 `PENDING / PROCESSING / READY / FAILED`。模型观察文本、置信度和原始响应不持久化。
- 任一图片仍为 `PENDING` 或 `PROCESSING` 时，上传按钮禁用；所有图片进入 `READY` 或 `FAILED` 后允许上传。
- `/materials` 单图识别失败直接进入 `FAILED`，不阻断其他图片，不提供用户重试按钮；保留原文件名生成的当前名称、默认“通用”类目和空标签。
- 工作台顺带入库识别在后台执行，不影响图片回填或当前任务提交；成功后自动更新素材字段，失败只保留回退字段。
- 删除文件、重新选择一批文件或关闭弹窗后，旧任务结果均失效；前端和服务端均不得按列表下标回写，必须按本次上传草稿唯一标识校验。
- 本期上传前识别草稿只存在于当前弹窗会话，离开后不恢复；已完成入库的素材不受弹窗关闭影响。

#### MN-R-06 跨页面消费与兼容

- **关联变更：** MN-CHG-05/06。
- 素材卡片、详情和编辑页继续直接展示最终 `title/category/tags`，无需新增识别控件。
- 素材库搜索继续检索标题、原文件名、类目和标签；上传完成后最终字段应立即可搜索和筛选。
- 素材选择器沿用同一素材查询服务；生产接入后，工作台顺带入库的后台识别结果自然展示为新名称和标签。当前前端原型只验证共享入口和入库元数据契约，不伪造跨路由生产持久化。
- 素材审批、权限管理、积分、历史记录、系统设置、商品学习和视频/音频上传保持现状；AI 生成结果加入素材库不重复识别。

### 12.7 AI 能力契约

| 契约项 | 要求 |
|---|---|
| 输入与事实源 | 单张新上传图片；素材范围、用户、组织、文件名、URL、备注不作为模型命名事实输入 |
| 参考优先级 | 图片可观察产品主体优先；人物、场景、姿态只在可明确识别时返回；无法确定时返回空槽位 |
| AI 处理责任 | 识别并返回结构化槽位；不负责自由标题生成、序号分配、权限、审批或入库 |
| 平台处理责任 | 校验槽位、过滤无效值、映射类目、生成标签、缩短名称、分配序号、管理状态并提交最终字段 |
| 输出 | `product/person/scene/pose/category` 结构化槽位或识别失败；实际接口字段名由技术方案映射 |
| 业务成功标准 | 产品主体非空且结构可解析；平台完成类目映射和唯一序号后，图片进入 `READY` |
| 质量门禁 | 产品主体不得为空；输出不得包含置信度展示、观察文本或非固定类目；30 张代表图片联调时产品主体准确率不低于 80% |
| 重试与停止 | 本期弹窗不提供重试；单次识别返回不可用、接口失败或解析失败即进入 `FAILED`，不阻断上传 |
| 失败返回 | 不生成建议；保留原文件名、默认“通用”类目和空标签；主动上传允许编辑并继续上传，快捷入库不影响当前任务 |

真实模型联调使用 30 张经授权的代表图片，覆盖人物/无人物、白底/场景图及主要类目。样本只用于本次质量验收，不进入埋点或对外服务；失败图片必须 100% 保留原文件名且不被“全部采纳”覆盖。

### 12.8 状态、边界与异常

| 状态 | 枚举标识 | 进入条件 | 页面表现 | 可执行操作 | 退出条件 |
|---|---|---|---|---|---|
| 等待识别 | `PENDING` | 新图片草稿建立 | 显示“等待识别” | 移除、关闭 | 开始识别或草稿失效 |
| 识别中 | `PROCESSING` | 识别请求已开始 | 动态图标与“识别中”；上传禁用 | 移除、关闭 | 成功、失败或草稿失效 |
| 识别完成 | `READY` | 槽位通过业务成功门禁 | 展示完整建议与采纳动作 | 采纳、编辑、移除、上传 | 草稿失效或入库 |
| 未识别 | `FAILED` | 请求、解析或产品主体识别失败 | 显示“未识别”和回退字段 | 编辑、移除、上传 | 草稿失效或入库 |

| 边界/异常 | 处理规则 | 用户反馈 | 数据影响 |
|---|---|---|---|
| 图片、视频、音频混合选择 | 仅图片进入状态机；视频/音频使用其统一类目和标签 | 视频/音频标记“不参与识别” | 不新增音视频识别字段，不覆盖图片字段 |
| 部分图片失败 | 成功项可采纳，失败项保留回退值；全批达到终态后可上传 | 逐项显示状态 | 批次不进入整体失败 |
| 人工编辑后点击全部采纳 | 跳过人工修改图片 | 人工值保持不变 | 保留 `MANUAL` |
| 移除正在识别的图片 | 立即移除草稿并忽略迟到结果 | 文件行消失 | 不入库、不计上传成功 |
| 关闭后重新打开 | 上批草稿与识别结果不恢复 | 新弹窗为空 | 不产生素材记录 |
| 工作台勾选快捷入库 | 图片先回填当前任务，素材命名后台处理 | 显示“确认后自动识别名称、类目和标签，不影响当前任务” | 成功自动更新素材；失败保留回退字段 |
| 工作台未勾选快捷入库 | 不创建个人素材、不触发识别 | 无额外提示 | 仅当前任务使用本地图片 |
| AI 生成/历史结果加入素材库 | 沿用结果已有名称和上下文 | 沿用现有成功反馈 | 不触发重复识别 |
| 同名前缀已存在 99 个 | 下一个序号自然扩展为 `100` | 建议名称显示三位序号 | 不覆盖已有素材 |

### 12.9 数据、接口语义与历史兼容

以下为产品字段语义；实际接口、数据库字段名和长度限制由技术方案映射，不在 PRD 编造物理结构。

| 对象 | 字段 | 类型/枚举 | 必填 | 规则/默认 | 持久化与兼容 |
|---|---|---|---|---|---|
| 上传草稿 | `draft_id` | 字符串 | 是 | 本次弹窗内唯一，不使用列表下标 | 上传前临时；关闭或移除后失效 |
| 上传草稿 | `recognition_status` | `PENDING/PROCESSING/READY/FAILED` | 图片是 | 图片初始 `PENDING`；音视频为空 | 入库后不要求作为素材业务状态展示 |
| 上传草稿 | `suggestion` | 对象/空 | 否 | 成功含建议名称、类目、标签和结构化槽位；失败为空 | 不持久化模型原始响应 |
| 单文件入库 | `title` | 字符串 | 是 | 当前最终名称；沿用现有标题校验 | 历史素材不回填、不改名 |
| 单文件入库 | `category` | 固定枚举 | 是 | 现有类目；“未分类”不可选 | 沿用现有素材字段 |
| 单文件入库 | `tags` | 字符串数组 | 否 | 建议最多 5 个；人工标签沿用现有校验 | 沿用现有素材字段 |
| 单文件入库 | `naming_source` | `ORIGINAL/AI_SUGGESTION/AI_AUTO/MANUAL` | 是 | 未采纳/失败为 `ORIGINAL`；主动采纳为 `AI_SUGGESTION`；快捷入库自动应用为 `AI_AUTO`；人工编辑为 `MANUAL` | 新素材新增审计语义；历史素材按无值兼容 |
| 单文件入库 | `filename` | 字符串 | 是 | 原始文件名，识别不得覆盖 | 沿用现有素材字段 |
| 批次公共字段 | `scope/personal_group/remark/visible_org_ids` | 沿用现有结构 | 按现有规则 | 全批公共，不进入识别 | 权限、审批、共享和备注语义不变 |

批量上传接口需支持每个文件分别携带 `title/category/tags/naming_source`，范围、个人分组、备注和可见组织继续使用批次公共字段。真实接口字段映射、同名并发原子分配和服务端校验由 TECH-09 明确；服务端必须作为最终序号唯一性事实源，前端建议序号不能替代入库校验。

### 12.10 责任边界与公共能力影响

| 责任方/能力 | 本模块责任或对接方式 | 本期变化 |
|---|---|---|
| 前端 | 管理主动上传草稿、预览、识别状态、逐张/全部采纳、人工编辑和迟到结果保护；共享选择器传递快捷入库意图 | 是；当前已完成本地原型 |
| 素材/上传服务 | 接收主动上传最终字段；快捷入库先创建个人素材并异步更新自动识别字段；校验固定类目、原子分配/确认同名序号并保存 `naming_source` | 是；待技术方案与开发 |
| AI Skill/模型链路 | 基于单张图片返回结构化槽位，不接收或记录无关敏感字段 | 是；真实链路待开发 |
| 素材查询与搜索 | 继续读取最终标题、原文件名、类目和标签 | 沿用现有能力，需联调回归 |
| 权限/审批/共享 | 沿用素材库现有规则 | 无变化 |
| 积分 | 图片识别不扣积分 | 无扣费接入 |
| 管理数据页 | 本期不改 UI；数据层提供指标事实 | UI 无变化，埋点待开发 |

### 12.11 验收标准

| 编号 | 关联变更/规则 | 前置条件与操作 | 预期结果 | 类型 |
|---|---|---|---|---|
| MN-AC-01 | MN-CHG-01/02、MN-R-01/05 | 在 `/materials` 选择 3 张图片 | 三张依次显示等待、识别中和各自终态；任一未终态时上传禁用 | 正常 |
| MN-AC-02 | MN-CHG-02、MN-R-02 | 对一张 `READY` 图片点击“采纳” | 名称、类目、标签同时更新为建议值，来源为 `AI_SUGGESTION` | 正常 |
| MN-AC-03 | MN-CHG-03、MN-R-02 | 一张成功未改、一张成功已人工修改、一张失败，点击“全部采纳” | 只更新成功未改图片；人工值和失败回退值不变 | 边界 |
| MN-AC-04 | MN-CHG-04、MN-R-04 | 分别选择纯图片批次及图片、视频、音频混合批次 | 纯图片不展示批量默认字段；混合批次只展示视频/音频统一类目和标签，修改后不覆盖任何图片 | 兼容 |
| MN-AC-05 | MN-R-03/04 | 使用人物为空、场景明确、姿态为“其他”的图片 | 名称和标签不含“无人物/其他”；建议类目属于固定枚举 | 边界 |
| MN-AC-06 | MN-R-03 | 构造超过 20 字的四槽位结果 | 按姿态、人物、场景顺序缩短；产品主体和序号保留，删除信息仍在标签 | 边界 |
| MN-AC-07 | MN-R-03/04 | 识别地垫图片并让同名前缀已有 `01/02/99` | 类目为“地毯类”；名称使用下一个可用序号，超过 99 自然扩展 | 规则 |
| MN-AC-08 | MN-R-05 | 模拟单张识别失败 | 显示“未识别”，保留原文件名、默认“通用”类目和空标签；全批终态后仍可上传 | 异常 |
| MN-AC-09 | MN-R-05 | 识别中移除文件，或关闭后重新打开并等待旧请求返回 | 旧结果不写回当前列表或新批次，不产生错误素材 | 中断 |
| MN-AC-10 | MN-CHG-06、MN-R-01/05/06 | 在 AI 买家秀等工作台本地上传图片，勾选“同时加入个人素材”后确认选择 | 图片立即回填当前工作台；个人素材后台自动应用名称、类目和标签，来源为 `AI_AUTO`；识别失败不阻塞任务并保留回退字段 | 联动 |
| MN-AC-11 | MN-CHG-05/06、MN-R-06 | 采纳后上传，再查看卡片、详情、编辑、搜索和类目/标签筛选 | 各处显示并可检索最终字段；素材对象仍保留原 `filename`，统一备注不被识别结果覆盖 | 联动 |
| MN-AC-12 | MN-R-01/05 | 使用 30 张代表图片真实联调 | 产品主体准确率不低于 80%；失败图片 100% 保留原文件名且不被全部采纳覆盖 | 质量 |
| MN-AC-13 | MN-CHG-01/02 | 在桌面、1280px、1024px和390px检查弹窗，并测试 Esc、遮罩和关闭按钮 | 无横向溢出；头尾操作区可见；文件列表内部滚动；三种关闭方式有效 | 响应式 |
| MN-AC-14 | MN-R-06 | 回归素材权限、团队/公共审批、积分、历史和管理设置 | 权限与审批结果不变；识别不生成积分流水；管理数据页无新增 UI | 兼容 |
| MN-AC-15 | MN-R-01/06 | 在工作台不勾选“同时加入个人素材”，再将 AI 生成结果或历史结果加入素材库 | 未勾选的本地图片不创建素材、不识别；生成/历史结果沿用原名称且不重复识别 | 边界 |

### 12.12 原型、开发状态与证据

| 内容 | 状态 | 证据 | 尚未完成 |
|---|---|---|---|
| 页面交互原型 | 已完成素材库主动上传及共享工作台快捷入库入口的本地实现 | `/materials`；`MaterialsClient.jsx`；`AssetPickerModal.jsx` | 真实上传、跨入口素材服务与模型接入 |
| 命名演示与纯函数 | 已完成脱敏确定性演示和主动/自动两种命名来源契约 | `src/data/demo/materials.js`；`tests/material-auto-naming.test.mjs` | 生产规则服务化与并发校验 |
| 真实模型质量 | 待联调 | MN-AC-12 的 30 张代表图片验收 | 模型选型、样本、报告 |
| 跨页面消费 | 当前前端原型依赖页面内数据；卡片、详情与搜索联动已验证 | 素材卡片、详情、编辑、搜索代码 | 真实素材查询服务联调 |

本地原型证明交互与字段语义，不代表真实模型、上传服务、生产持久化、埋点、部署或上线完成。

### 12.13 埋点与效果衡量

本期管理数据页不增加 UI。事件名为产品语义建议，开发需在事件映射清单中标记实际复用或新增关系；埋点失败不得阻断识别和上传。

| 目标 | 事件/指标 | 口径 | 当前基线/目标 | 复盘方式 |
|---|---|---|---|---|
| 识别质量 | 图片识别成功率 | `READY 图片数 / (READY + FAILED 图片数)`；按进入识别终态的图片去重 | 上线后采集 | 按类目、图片类型复盘，不记录图片原文 |
| 建议有效性 | 建议采纳率 | 最终 `naming_source=AI_SUGGESTION` 的已上传图片数 / 已上传且识别为 `READY` 的图片数 | 上线后采集 | 周期复盘采纳与失败分布 |
| 主动上传效率 | 全部采纳使用率 | `/materials` 触发“全部采纳”的上传批次数 / 至少有 2 张可采纳图片的上传批次数 | 上线后采集 | 分析主动上传批量采纳价值 |
| 快捷入库覆盖 | 自动命名成功率 | 工作台快捷入库最终 `naming_source=AI_AUTO` 的图片数 / 勾选快捷入库的本地图片数 | 上线后采集 | 按入口与类目复盘，不记录图片或文件名 |
| 人工介入 | 人工修改率 | 最终 `naming_source=MANUAL` 的已上传图片数 / 已上传且识别为 `READY` 的图片数 | 上线后采集 | 结合类目定位规则优化方向 |
| 性能 | 平均识别耗时 | 每张图片从开始识别到进入 `READY/FAILED` 的耗时总和 / 终态图片数 | 上线后采集 | 按成功/失败分组监控 |

最小事件语义包括 `material_image_recognition_finished`、`material_naming_suggestion_adopted`、`material_naming_adopt_all_clicked`、`material_quick_save_requested` 和现有上传成功事实。只记录匿名草稿/批次标识、入口、状态、耗时、类目枚举、槽位是否存在、`naming_source` 和数量；不得记录图片、文件名、URL、备注、识别文本槽位值或模型原始响应。

## 13. 事实与状态说明

- 本文档是本期 V1.2 开发需求基线，不等于技术评审、真实模型/服务开发、部署或上线完成。
- V1.2 在 V1.1 基线上调整素材库图片字段并扩展工作台本地图片快捷入库识别；其余已确认模块范围与规则保持不变。
- 调用 `xianma_detail_refresh` Skill 即视为用户授权该任务所需的素材处理、模型调用、结果落盘和测试，不再额外执行外部模型服务授权检查；该规则不改变公司资料保密和最小范围使用要求。
- 代码仓库用于判断当前实现与验证状态；知识库 Markdown 是正式产品规则和 PRD 事实源。