|
|
@@ -0,0 +1,198 @@
|
|
|
+# 顾客详情页 AI 模拟结果卡片流设计
|
|
|
+
|
|
|
+## 目标
|
|
|
+
|
|
|
+在顾客详情页的“过往照片和AI发型模拟”区块中，替换当前未开发占位卡片，展示该顾客历史 AI 发型模拟生成结果。每一张生成图对应一张卡片，按创建时间倒序展示，点击卡片进入对应任务详情页。
|
|
|
+
|
|
|
+## 背景
|
|
|
+
|
|
|
+- 当前顾客详情页中，“过往照片和AI发型模拟”区块仍是静态占位，不承载真实业务结果。
|
|
|
+- AI 发型模拟主流程已经具备创建任务、查询任务详情、展示子任务结果图的能力。
|
|
|
+- 用户要求在顾客详情页直接看到“刚刚任务的结果”，并明确要求：
|
|
|
+ - 一个图片就是一个任务卡片
|
|
|
+ - 按时间顺序全部展示
|
|
|
+ - 点击图片卡片进入对应任务详情页
|
|
|
+ - 排序采用最新在前
|
|
|
+
|
|
|
+## 范围
|
|
|
+
|
|
|
+### 本次包含
|
|
|
+
|
|
|
+- 新增顾客维度的 AI 模拟结果卡片列表接口
|
|
|
+- 顾客详情页接入真实结果卡片流
|
|
|
+- 每张生成图展开为一张独立卡片
|
|
|
+- 点击卡片跳转到对应模拟任务详情页
|
|
|
+- 空状态展示
|
|
|
+
|
|
|
+### 本次不包含
|
|
|
+
|
|
|
+- 分页
|
|
|
+- 筛选
|
|
|
+- 失败任务和处理中任务的卡片展示
|
|
|
+- 在顾客详情页直接轮询任务状态
|
|
|
+- 任务详情页结构变更
|
|
|
+
|
|
|
+## 交互设计
|
|
|
+
|
|
|
+### 区块位置
|
|
|
+
|
|
|
+继续使用顾客详情页现有“过往照片和AI发型模拟”区块，不改变整体页面骨架、标题和右上角“AI发型模拟”入口按钮位置。
|
|
|
+
|
|
|
+### 卡片规则
|
|
|
+
|
|
|
+- 一张生成图展开为一张卡片
|
|
|
+- 一个任务下如果有多张生成图，则展开成多张卡片
|
|
|
+- 同一个 `simulationId` 下出现多张卡片属于预期行为
|
|
|
+- 卡片至少展示：
|
|
|
+ - 生成图
|
|
|
+ - 模板名称
|
|
|
+ - 生成时间
|
|
|
+
|
|
|
+### 点击行为
|
|
|
+
|
|
|
+- 点击任意卡片，跳转至 `/:locale/simulation/result/:simulationId`
|
|
|
+- 不跳到子任务维度页面，继续复用现有任务详情页
|
|
|
+
|
|
|
+### 排序
|
|
|
+
|
|
|
+- 按模拟任务创建时间倒序排列
|
|
|
+- 最新的结果卡片排在最前面
|
|
|
+
|
|
|
+### 空状态
|
|
|
+
|
|
|
+- 当顾客还没有任何成功生成的 AI 模拟结果时，不显示假卡片
|
|
|
+- 使用清晰的空状态文案提示当前暂无 AI 模拟结果
|
|
|
+
|
|
|
+## 后端设计
|
|
|
+
|
|
|
+### 新接口
|
|
|
+
|
|
|
+- 路由：`GET /api/v1/simulations/customer/:customerId/gallery`
|
|
|
+- 权限：仅允许当前登录发型师查看自己名下顾客的数据
|
|
|
+
|
|
|
+### 返回结构
|
|
|
+
|
|
|
+返回扁平化卡片列表，而不是主任务嵌套结构。每条记录代表一张生成图卡片。
|
|
|
+
|
|
|
+建议 DTO：
|
|
|
+
|
|
|
+```ts
|
|
|
+export type CustomerSimulationGalleryItemDto = {
|
|
|
+ simulationId: string;
|
|
|
+ taskId: string;
|
|
|
+ imageUrl: string;
|
|
|
+ templateName: string;
|
|
|
+ createdAt: string;
|
|
|
+ taskStatus: 'SUCCESSES';
|
|
|
+};
|
|
|
+```
|
|
|
+
|
|
|
+响应示例：
|
|
|
+
|
|
|
+```json
|
|
|
+{
|
|
|
+ "items": [
|
|
|
+ {
|
|
|
+ "simulationId": "91",
|
|
|
+ "taskId": "task-11",
|
|
|
+ "imageUrl": "https://cdn.example.com/result-1.png",
|
|
|
+ "templateName": "Layer Bob",
|
|
|
+ "createdAt": "2026-06-28T09:00:00.000Z",
|
|
|
+ "taskStatus": "SUCCESSES"
|
|
|
+ }
|
|
|
+ ]
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 查询规则
|
|
|
+
|
|
|
+- 只查询当前发型师名下的顾客
|
|
|
+- 只查询该顾客关联的 `ai_hair_simulation`
|
|
|
+- 只展开 `ai_hair_simulation_task` 中 `task_status = 'SUCCESSES'` 的任务
|
|
|
+- 从 `result_images` 中展开真实图片列表
|
|
|
+- 每张图片映射为一条扁平记录
|
|
|
+- 按所属模拟任务 `create_time` 倒序输出
|
|
|
+
|
|
|
+### 数据来源
|
|
|
+
|
|
|
+- 主表：`ai_hair_simulation`
|
|
|
+- 子表：`ai_hair_simulation_task`
|
|
|
+- 模板名来自 `hair_template.template_name`
|
|
|
+
|
|
|
+### 安全约束
|
|
|
+
|
|
|
+- 必须校验 `customerId` 属于当前发型师
|
|
|
+- 不允许跨发型师读取顾客结果
|
|
|
+
|
|
|
+## 前端设计
|
|
|
+
|
|
|
+### API 层
|
|
|
+
|
|
|
+在 `frontend/src/services/api/simulations.ts` 中新增顾客详情页所需的 gallery 查询方法，并在 `contracts.ts` 中补齐对应类型。
|
|
|
+
|
|
|
+建议签名：
|
|
|
+
|
|
|
+```ts
|
|
|
+export async function listCustomerSimulationGallery(
|
|
|
+ customerId: string,
|
|
|
+): Promise<{ items: CustomerSimulationGalleryItem[] }>
|
|
|
+```
|
|
|
+
|
|
|
+### 顾客详情页
|
|
|
+
|
|
|
+在 `CustomerDetailPage.tsx` 中替换原有 `photoPlaceholders` 占位卡片渲染逻辑：
|
|
|
+
|
|
|
+- 页面加载后并行请求：
|
|
|
+ - 顾客详情
|
|
|
+ - 顾客 AI 模拟结果卡片列表
|
|
|
+- 卡片区改为真实图片网格
|
|
|
+- 每张卡片使用 `Link`
|
|
|
+- 跳转目标为 `path(\`/simulation/result/${simulationId}\`)`
|
|
|
+
|
|
|
+### 展示字段
|
|
|
+
|
|
|
+每张卡片展示：
|
|
|
+
|
|
|
+- 主图：`imageUrl`
|
|
|
+- 标题：`templateName`
|
|
|
+- 辅助时间：`createdAt` 的格式化日期时间
|
|
|
+
|
|
|
+## 边界与异常
|
|
|
+
|
|
|
+- 如果接口失败：
|
|
|
+ - 顾客详情主体仍按现有策略处理
|
|
|
+ - AI 模拟图片区块显示错误或空状态，而不是整页崩溃
|
|
|
+- 如果某个成功任务的 `result_images` 为空数组：
|
|
|
+ - 该任务不生成卡片
|
|
|
+- 如果模板被删除：
|
|
|
+ - 模板名称允许回退为默认文案，但不阻塞图片展示
|
|
|
+
|
|
|
+## 测试策略
|
|
|
+
|
|
|
+### 后端
|
|
|
+
|
|
|
+- service 单测：
|
|
|
+ - 顾客归属校验
|
|
|
+ - 仅展开成功任务
|
|
|
+ - 一个任务多图展开为多条记录
|
|
|
+ - 倒序输出
|
|
|
+- e2e：
|
|
|
+ - 返回当前顾客 gallery
|
|
|
+ - 非本人顾客不可访问
|
|
|
+
|
|
|
+### 前端
|
|
|
+
|
|
|
+- API 测试：
|
|
|
+ - 请求路径正确
|
|
|
+- 页面测试：
|
|
|
+ - 成功渲染真实卡片
|
|
|
+ - 空状态渲染
|
|
|
+ - 点击卡片跳转到结果详情页
|
|
|
+
|
|
|
+## 验收标准
|
|
|
+
|
|
|
+- 顾客详情页“过往照片和AI发型模拟”区块展示真实 AI 模拟结果卡片
|
|
|
+- 一张生成图对应一张卡片
|
|
|
+- 最新结果排在最前
|
|
|
+- 点击卡片进入对应任务详情页
|
|
|
+- 页面整体 UI 骨架不被破坏
|
ChenYu