6.5 KiB
上传模板系统用户手册
更新时间：2026-05-28
本文档面向管理员，说明当前后台模板系统的真实使用方式。模板管理入口在主应用后台 /admin 中，不存在单独的 /admin/templates 路由。
1. 系统概述
上传模板决定用户上传素材时需要填写哪些元数据。每个模板可以配置：
- 字段名称、字段类型、必填状态
- 字段布局、选项、搜索属性
- 是否同步到分类管理
- 素材类型和素材大类
- 草稿、启用、归档状态
当前素材大类包括：
IMAGE：图片、3DMAX、PSD、模特等图片类素材VIDEO：视频素材AUDIO：音频素材OTHER：其他素材
2. 预制模板与自定义模板
后台里看到的“预制模板”来自 lib/upload-template-presets.ts，由代码生成，可启用/禁用，也可作为创建自定义模板的参考。
当前预制模板包括：
- 3DMAX
- PSD
- AI 工作流
- 音频
- 视频
- 模特
- 其他
自定义模板由管理员创建和维护。创建、更新、删除、迁移自定义模板需要当前许可证允许 customTemplates 能力。
3. 创建自定义模板
- 登录后台
/admin。 - 进入模板管理区域。
- 选择从预制模板复制，或新建一个空白模板。
- 填写模板名称、描述、素材类型、素材大类。
- 配置字段。
- 保存为草稿或启用状态。
建议：
- 新模板先用草稿状态验证。
- 已投入使用的模板不要直接改字段 key、字段类型、素材类型或素材大类。
- 需要大改时，优先新建模板，再迁移素材。
- 迁移前先查看迁移预览，确认哪些字段会成为新模板当前字段、哪些旧字段会进入备份区；系统会尽量保留旧字段备份，但管理员仍要确认字段设计是否合适。
4. 字段配置
常用字段类型：
| 类型 | 用途 |
|---|---|
text |
单行文本 |
textarea |
多行文本 |
number |
数字 |
select |
下拉选择 |
checkbox |
勾选项 |
radio |
单选项 |
date |
日期 |
uppercase |
大写字母类输入 |
字段 key 的当前后端强校验是：
- 不能为空
- 同一模板内不能重复
团队使用建议仍然是：
- 用英文、数字、下划线
- 不用中文、空格、短横线
- 不随意修改已上线字段 key
原因是字段 key 会影响搜索、历史数据展示、分类同步、导出和后续脚本处理。
5. 字段选项
下拉和单选字段可以配置静态选项。当前系统支持数组或文本配置，保存时会做基础规范化。
如果字段勾选“添加到分类”，保存模板后会同步到字段池和分类管理。
6. 分类管理
分类管理用于集中维护可筛选字段及其选项。
当前真实接口包括：
GET /api/category-fieldsPATCH /api/category-fieldsPUT /api/category-fieldsGET /api/template-categoriesGET /api/template-categories/:fieldKeyPUT /api/template-categories/:fieldKey
使用建议：
- 只把稳定的下拉字段加入分类管理。
- 首页筛选字段不要过多。
- 选项特别多或经常变化的字段，不适合作为首页筛选。
常见分类字段：
- 使用店铺
categoryName - 场景类别
sceneName - 渲染器
renderer - 品牌名称
brandName - 系列名称
seriesName - 材质/工艺
materialTexture
7. 模板版本与结构保护
模板更新有版本控制。多人同时编辑同一模板时，如果版本不一致，保存会返回版本冲突。
模板已有素材使用时，当前后端会阻止这些破坏性结构变更：
- 修改素材类型
- 修改素材大类
- 删除已有字段
- 修改已有字段 key
- 修改已有字段类型
这些限制是为了避免历史素材字段无法展示或语义错乱。
8. 字段填写率
管理员查看单个模板详情时，可以看到字段填写率统计。
说明：
- 这是后台模板详情里的统计能力。
- 它用于判断字段是否真的被使用。
- 长期低填写率字段，应考虑改成非必填、改名、补说明，或在新模板中移除。
9. 字段条件显示
模板字段可以配置显示条件。当前上传和编辑都会按条件处理：
- 条件不满足的字段不会显示，也不会要求必填。
- 上传素材时，隐藏字段不会写入本次素材数据。
- 编辑素材时，隐藏字段不会参与本次保存覆盖；历史旧值默认保留，避免误删。
- 条件依赖字段变化后，相关字段会立即显示或隐藏。
建议只给稳定、容易理解的字段配置条件。保存模板时，系统会阻止引用不存在字段、自引用和循环依赖；复杂条件或多层依赖过多时，仍建议先用测试素材验证一遍，避免普通用户填写时摸不清规则。
10. 常见问题
为什么普通用户看不到某个模板？
优先检查：
- 模板是否为
active - 预制模板是否被禁用
- 是否是管理员草稿模板
为什么保存自定义模板提示许可证未包含？
说明当前许可证没有开启 customTemplates。请联系管理员确认当前授权范围，必要时激活包含自定义模板能力的许可证。
能不能删除正在使用的模板？
不能。已有素材使用该模板时，删除会被阻止。建议归档旧模板或新建模板后迁移素材。
新建模板后迁移素材时，系统会事务化处理；失败时不会只迁移一部分素材。目标模板不接收的旧字段会保留到备份区，方便后续追溯。
正式迁移前应先查看迁移预览。预览会显示可迁移素材数量、目标模板当前字段、会进入备份区的旧字段，以及最多 10 条受影响素材样例。预览不会写数据库，适合管理员确认字段设计后再执行迁移。
字段 key 能不能改？
未使用前可以谨慎改。模板已有素材后不建议改，当前后端也会拦截已有素材模板的字段 key 变更。
模板能导入导出吗？
当前主应用没有正式的模板导入/导出功能。跨环境迁移需单独设计脚本或通过数据库/迁移流程处理。
字段池有没有独立 API？
当前没有 /api/field-pool 或 /api/admin/field-pool/sync 路由。字段池同步是内部实现：模板保存会自动同步；分类管理页读取不会自动写库，需要最高权限账号在后台分类管理里点击“同步字段”维护动作。
11. 相关文档
docs/api/模板系统API文档.mddocs/README.mddocs/许可证服务接入说明.md