flnxi-Wu/docs/user-guide/template-system-guide.md

# 自定义上传模板系统 - 用户手册

## 目录

1. [系统概述](#系统概述)
2. [如何创建自定义模板](#如何创建自定义模板)
3. [如何使用分类管理](#如何使用分类管理)
4. [常见问题解答](#常见问题解答)

---

## 系统概述

### 什么是自定义上传模板？

自定义上传模板系统允许管理员根据不同类型的素材创建专属的上传表单。每个模板可以定义：

- **字段配置**：决定用户上传时需要填写哪些信息
- **字段类型**：文本、下拉选择、日期等多种类型
- **验证规则**：必填、格式验证等
- **显示配置**：字段布局、分组等

### 为什么需要自定义模板？

不同类型的素材需要不同的元数据：

- **3DMAX素材**：需要记录渲染器、渲染时间等
- **PSD素材**：需要记录颜色模式、分辨率等
- **视频素材**：需要记录时长、格式等

自定义模板让您可以为每种素材类型创建最合适的上传表单。

### 内置模板 vs 自定义模板

**内置模板**
- 系统预设的6种常用模板
- 不可修改，但可以基于它们创建自定义模板
- 包括：3DMAX、PSD、AI工作流、视频、模特、其他

**自定义模板**
- 管理员创建的模板
- 可以自由修改字段配置
- 可以设置为草稿、启用或归档状态

---

## 如何创建自定义模板

### 步骤1：进入模板管理页面

1. 登录管理后台
2. 点击左侧菜单的「模板管理」
3. 您会看到内置模板和自定义模板列表

### 步骤2：选择起始模板

**方式一：从内置模板创建**

1. 在内置模板区域，找到最接近您需求的模板
2. 点击「预览」查看模板效果
3. 点击「基于此模板创建」开始自定义

**方式二：从空白创建**

1. 点击页面右上角的「新建模板」按钮
2. 系统会创建一个包含基础字段的空白模板

### 步骤3：配置基本信息

在模板编辑器中，填写以下基本信息：

**模板名称**
- 建议格式：`[素材类型] - [用途说明]`
- 示例：`3DMAX素材模板 - 家具类`

**模板描述**
- 简要说明模板的用途和适用场景
- 示例：`适用于家具类3D模型素材，包含品牌、系列等详细信息`

**素材类型**
- 选择素材的主要类型
- 可选：3DMAX、PSD、AI工作流、视频、模特、其他

**素材大类**
- IMAGE：图片类素材
- VIDEO：视频类素材
- OTHER：其他类型

**模板状态**
- 草稿：仅管理员可见，用于测试
- 启用：用户可以使用此模板上传素材
- 归档：不再使用，但保留历史数据

### 步骤4：配置字段

#### 4.1 添加字段

点击「添加字段」按钮，可以选择：

**标准字段**（推荐）
- 系统预定义的常用字段
- 包括：SPU型号、品牌名称、系列名称、渲染器等
- 选择标准字段会自动填充字段配置

**自定义字段**
- 完全自定义的字段
- 需要手动配置所有属性

#### 4.2 字段配置项

**字段键名** （必填）
- 用于存储数据的唯一标识符
- 规则：
  - 必须以字母开头
  - 只能包含字母、数字、下划线
  - 长度不超过50个字符
  - 在同一模板内必须唯一
- 示例：`productModel`、`brandName`、`renderTime`

**显示名称** （必填）
- 用户看到的字段标签
- 示例：`商品型号`、`品牌名称`、`渲染耗时`

**字段类型** （必填）
- `文本`：单行文本输入
- `多行文本`：多行文本输入
- `数字`：数字输入
- `下拉选择`：从预设选项中选择
- `复选框`：是/否选择
- `单选`：从多个选项中选择一个
- `日期`：日期选择器
- `仅大写+字母`：自动转换为大写的字母输入

**布局宽度**
- `整行`：字段占据整行宽度
- `半行`：字段占据半行宽度（可与其他半行字段并排）

**字段选项**（仅下拉选择和单选类型）

支持两种输入格式：

**格式1：每行一个选项**
```
选项1
选项2
选项3
```

**格式2：JSON数组**
```json
["选项1", "选项2", "选项3"]
```

系统会自动：
- 清洗和规范化选项值
- 去除重复选项
- 展开嵌套数组（如 `[["A", "B"], "C"]` 会展开为 `["A", "B", "C"]`）

**字段属性**
- ☑️ **必填**：用户必须填写此字段才能提交
- ☑️ **可搜索**：此字段的内容可以被搜索
- ☑️ **添加到分类**（仅下拉选择类型）：将此字段添加到分类管理系统

#### 4.3 字段操作

**调整顺序**
- 点击字段卡片上的上/下箭头按钮
- 或者拖拽字段卡片左侧的拖拽手柄

**复制字段**
- 点击字段卡片上的复制按钮
- 系统会创建一个相同配置的新字段
- 新字段的键名会自动添加 `_copy` 后缀

**删除字段**
- 点击字段卡片上的删除按钮
- 系统会显示确认对话框
- 注意：删除字段后，已上传素材的该字段数据将无法显示

### 步骤5：预览和保存

**预览模板**
- 右侧面板实时显示模板的上传表单效果
- 可以看到字段的实际布局和样式

**保存模板**
1. 检查所有字段配置是否正确
2. 点击底部的「保存」按钮
3. 系统会验证：
   - 模板名称不能为空
   - 至少包含一个字段
   - 所有字段键名格式正确且唯一
4. 保存成功后，模板会出现在自定义模板列表中

### 步骤6：启用模板

1. 在模板列表中找到刚创建的模板
2. 如果状态是「草稿」，点击「启用」按钮
3. 启用后，用户在上传素材时可以选择此模板

---

## 如何使用分类管理

### 什么是分类管理？

分类管理系统统一管理所有模板中标记为「添加到分类」的下拉选择字段。它的作用是：

- **统一选项**：确保不同模板中相同字段的选项一致
- **首页筛选**：启用的分类字段会显示在首页作为筛选条件
- **集中维护**：在一个地方管理所有分类选项

### 哪些字段会进入分类管理？

当您在模板中创建下拉选择字段并勾选「添加到分类」时，该字段会自动同步到分类管理系统。

**常见的分类字段：**
- 使用店铺（categoryName）
- 场景类别（sceneName）
- 渲染器（renderer）
- 品牌名称（brandName）
- 系列名称（seriesName）
- 材质/工艺（materialTexture）

### 如何管理分类选项？

#### 方式一：在模板中管理

1. 编辑包含该字段的模板
2. 修改字段的选项列表
3. 保存模板
4. 系统会自动同步到字段池和其他使用该字段的模板

#### 方式二：在分类管理页面管理

1. 进入「分类管理」页面
2. 找到要管理的字段
3. 可以进行以下操作：
   - 添加新选项
   - 删除选项
   - 重命名选项
   - 调整选项顺序
   - 启用/禁用字段作为首页筛选

### 分类字段的同步机制

**自动同步**
- 创建或更新模板时，标记为「添加到分类」的字段会自动同步到字段池
- 字段池中的选项会合并所有模板中该字段的选项
- 去重和规范化处理确保选项的一致性

**同步失败重试**
- 如果同步失败，系统会自动重试3次
- 使用指数退避策略（1秒、2秒、4秒）
- 所有同步操作都有详细的日志记录

---

## 常见问题解答

### Q1: 为什么我的字段键名无法保存？

**A:** 字段键名必须符合以下规则：
- 必须以字母开头
- 只能包含字母、数字、下划线
- 长度不超过50个字符
- 在同一模板内必须唯一

**常见错误：**
- ❌ `123model`（以数字开头）
- ❌ `product-model`（包含连字符）
- ❌ `产品型号`（包含中文）
- ✅ `productModel`（正确）
- ✅ `product_model`（正确）

### Q2: 如何修改已启用的模板？

**A:** 可以直接修改已启用的模板，但需要注意：

1. **添加字段**：安全，不影响已上传的素材
2. **修改字段配置**：
   - 修改显示名称：安全
   - 修改字段类型：可能导致数据显示异常
   - 修改字段键名：会导致已上传素材的该字段数据无法显示
3. **删除字段**：已上传素材的该字段数据将无法显示

**建议：**
- 重要修改前先设置为草稿状态
- 在测试环境验证修改效果
- 考虑创建新版本模板而不是修改现有模板

### Q3: 模板版本冲突怎么办？

**A:** 当多人同时编辑同一模板时，可能出现版本冲突。

**解决方法：**
1. 刷新页面获取最新版本
2. 重新进行您的修改
3. 保存时系统会使用最新的版本号

**预防措施：**
- 编辑前先刷新页面确保是最新版本
- 避免多人同时编辑同一模板
- 重要修改前通知团队成员

### Q4: 如何删除正在使用的模板？

**A:** 系统不允许直接删除正在使用的模板。

**解决方法：**
1. 创建新模板替代旧模板
2. 将使用旧模板的素材迁移到新模板（需要开发支持）
3. 确认没有素材使用旧模板后再删除

**替代方案：**
- 将模板状态设置为「归档」
- 归档的模板不会显示在用户的模板选择列表中
- 但已使用该模板的素材仍然可以正常显示

### Q5: 下拉选择字段的选项太多怎么办？

**A:** 有几种优化方案：

1. **分组选项**：使用字段分组功能（高级配置）
2. **使用搜索**：前端会自动为选项多的下拉框添加搜索功能
3. **拆分字段**：将一个大字段拆分为多个小字段
   - 例如：`品牌` → `品牌类别` + `具体品牌`

### Q6: 如何让字段在首页显示为筛选条件？

**A:** 需要满足以下条件：

1. 字段类型必须是「下拉选择」
2. 勾选「添加到分类」
3. 在分类管理页面启用该字段为筛选字段
4. 设置筛选字段的显示顺序

**注意：**
- 首页筛选字段建议不超过8个
- 选项太多的字段不适合作为筛选条件

### Q7: 字段填写率低怎么办？

**A:** 在模板详情页可以看到每个字段的填写率统计。

**填写率低的原因：**
1. 字段不是必填，用户选择跳过
2. 字段对某些素材不适用
3. 用户不理解字段的含义

**改进建议：**
1. 重要字段设置为必填
2. 添加字段说明（使用 validations 配置）
3. 考虑删除填写率长期低于30%的字段
4. 优化字段标签，使其更易理解

### Q8: 如何批量更新素材的模板？

**A:** 目前系统不支持批量更新素材的模板。

**替代方案：**
1. 修改现有模板而不是创建新模板
2. 联系开发团队使用数据库脚本批量更新

### Q9: 模板可以导入导出吗？

**A:** 目前系统不支持模板的导入导出功能。

**替代方案：**
1. 使用「复制模板」功能创建副本
2. 联系开发团队如需在不同环境间迁移模板

### Q10: 如何测试新模板？

**A:** 建议的测试流程：

1. **创建草稿模板**
   - 状态设置为「草稿」
   - 只有管理员可以看到

2. **使用预览功能**
   - 在模板编辑器中查看实时预览
   - 检查字段布局和样式

3. **测试上传**
   - 使用管理员账号测试上传素材
   - 验证所有字段都能正常填写和保存

4. **检查数据**
   - 查看上传的素材详情
   - 确认所有字段数据正确显示

5. **启用模板**
   - 测试通过后将状态改为「启用」
   - 通知用户可以使用新模板

---

## 获取帮助

如果您在使用过程中遇到问题：

1. **查看本手册**：大多数常见问题都有解答
2. **查看API文档**：`docs/api/template-system-api.md`
3. **联系技术支持**：提供详细的问题描述和截图
4. **查看系统日志**：管理员可以查看详细的操作日志

---

## 附录：字段类型详解

### 文本（text）
- 单行文本输入
- 适用于：型号、名称、简短描述等
- 可配置最大长度验证

### 多行文本（textarea）
- 多行文本输入
- 适用于：详细描述、备注等
- 支持换行

### 数字（number）
- 数字输入
- 适用于：数量、尺寸、价格等
- 可配置范围验证（最小值、最大值）

### 下拉选择（select）
- 从预设选项中选择一个
- 适用于：分类、状态、规格等
- 必须配置选项列表
- 可添加到分类管理

### 复选框（checkbox）
- 是/否选择
- 适用于：是否包含某功能、是否符合某标准等
- 返回 true/false

### 单选（radio）
- 从多个选项中选择一个
- 适用于：互斥的选项
- 必须配置选项列表
- 与下拉选择类似，但UI不同

### 日期（date）
- 日期选择器
- 适用于：创建日期、截止日期等
- 返回标准日期格式

### 仅大写+字母（uppercase）
- 自动转换为大写的字母输入
- 适用于：代码、编号等
- 只允许输入字母，自动转换为大写

---

**文档版本**: 1.0  
**最后更新**: 2024-12-13  
**维护者**: FLNXI开发团队