# 模板新建页素材数据源切换最小设计

## 背景

当前主仓库 `main` 分支上的 [TemplateFormPage.tsx](file:///Users/yuchen/Documents/hairstylist/frontend/src/pages/dashboard/templates/TemplateFormPage.tsx) 仍然使用本地静态素材：

- `选择AI模特`
- `选择服装`
- `选择背景`

这三块目前通过 `getHairstyleTemplateAssetsByCategory()` 从本地 `hairstyleTemplateAssets` 读取，而不是从服务端的 `config` 表读取。

用户本次要求只做最小改动：

- 只替换这三个区块的数据来源
- 其他页面结构和旧提交流程先不改
- 接口失败时不回退本地静态数据

## 目标

- 让模板新建页中的模特、服装、背景三组素材改为从服务端配置接口读取
- 前端展示仍保持现有卡片式 UI，不做结构重写
- 如果配置接口失败或返回为空，页面明确显示异常状态，并阻止继续提交

## 非目标

- 不改当前 `TemplateFormPage` 的其余表单结构
- 不改当前提交接口 `createTemplateAndStartGeneration()`
- 不在这次改动中接入模板制作任务页
- 不保留本地静态素材作为降级兜底

## 推荐方案

采用最小替换方案：

1. 在前端模板 API 层新增一个读取模板素材的方法
2. 页面初始化时请求服务端素材接口
3. 将返回结果映射为当前页面已有卡片 UI 所需的数据结构
4. 删除页面对本地 `hairstyleTemplateAssets` 的依赖
5. 当素材未加载成功时，显示错误提示并禁用提交按钮

这样可以只清理用户明确指出的旧逻辑，不扩大到整条模板创建链路。

## 接口与数据约定

前端读取服务端模板素材接口，返回三组数据：

- `models`
- `clothes`
- `backgrounds`

每个选项至少包含：

- `id`
- `name`
- `url`
- `configKey`

服务端数据来源约定如下：

- `config_group = 'ai-model'` -> `models`
- `config_group = 'clothing'` -> `clothes`
- `config_group = 'background'` -> `backgrounds`

前端页面映射规则如下：

- `id` 直接作为选中值
- `name` 映射为卡片标题
- `url` 映射为当前卡片图片地址

## 页面行为

### 1. 初始化加载

页面挂载时请求一次模板素材接口。

成功时：

- 将三组接口结果写入本地状态
- 默认选中每组的第一项

失败时：

- 不回退到本地静态素材
- 显示“素材加载失败”类提示
- 禁用顶部和底部的提交按钮

### 2. 空数据处理

如果接口返回成功但某一组为空，也视为“资源未准备完成”：

- 显示提示文案
- 页面不崩溃
- 禁用提交按钮

### 3. 提交流程

本次不改旧提交流程，只替换素材来源。

因此提交时仍然：

- 上传参考图
- 读取当前选中的模特、服装、背景 URL
- 调用现有 `createTemplateAndStartGeneration()`

也就是说，提交 payload 中使用的三组 URL 仍来自当前选中的服务端配置素材，而不是本地静态素材。

## 影响文件

- 修改 [TemplateFormPage.tsx](file:///Users/yuchen/Documents/hairstylist/frontend/src/pages/dashboard/templates/TemplateFormPage.tsx)
  - 删除对 `hairstyleTemplateAssets` 的依赖
  - 新增页面级素材加载状态、错误状态和接口映射
- 修改 [templates.ts](file:///Users/yuchen/Documents/hairstylist/frontend/src/services/api/templates.ts)
  - 新增读取模板素材的 API 方法
- 修改 [contracts.ts](file:///Users/yuchen/Documents/hairstylist/frontend/src/services/api/contracts.ts)
  - 新增模板素材类型定义
- 可选修改 [translation.json](file:///Users/yuchen/Documents/hairstylist/frontend/src/i18n/locales/zh/translation.json) / [translation.json](file:///Users/yuchen/Documents/hairstylist/frontend/src/i18n/locales/ja/translation.json)
  - 如果现有提示文案不够准确，则补充“素材加载失败”相关文案

## 测试策略

本次测试只覆盖真实回归风险：

1. 页面能从接口读取三组素材并渲染
2. 页面不再依赖本地 `hairstyleTemplateAssets`
3. 接口失败时显示错误提示并禁用提交
4. 选择素材后提交时使用接口返回的 URL

不增加与本次目标无关的重构测试。

## 风险与边界

- 因为当前页面仍保留旧提交接口，所以这次只是“清理三组素材来源”，不是整页真实链路切换
- 如果后续要切到模板制作任务流，应在下一次改动中再统一收敛 `TemplateFormPage`
- 本次明确不做静态兜底，因此如果服务端配置没准备好，页面将无法提交，这是符合用户当前要求的