flnxi-Wu/.kiro/specs/template-system-optimization/requirements.md

# 自定义上传模板系统优化需求文档

## 介绍

本文档定义了对FLNXI素材库自定义上传模板系统的优化需求。

**核心价值**：自定义上传模板系统是整个FLNXI素材库的核心基础设施，它决定了：
- 用户如何上传素材（表单结构）
- 素材包含哪些元数据（字段定义）
- 如何分类和检索素材（字段池集成）
- 如何共享和展示素材（字段显示配置）

作为"上传-保存-共享"工作流的起点，模板系统的稳定性和灵活性直接影响整个系统的可用性。当前系统已经实现了基础功能，但需要进一步优化以提高稳定性、可靠性和用户体验，确保它能够支撑各种复杂的业务场景。

## 术语表

- **自定义模板 (Custom Template)**: 管理员创建的上传模板，存储在数据库中
- **内置模板 (Builtin Template)**: 系统预设的模板，动态生成，不存储在数据库中
- **模板字段 (Template Field)**: 模板中定义的表单字段，如文本框、下拉框等
- **字段池 (Field Pool)**: 集中管理所有模板字段及其选项的系统
- **模板验证 (Template Validation)**: 验证模板ID是否有效的过程
- **字段同步 (Field Sync)**: 将模板字段同步到字段池的过程

## 需求

### 需求 1: 模板验证增强

**用户故事**: 作为系统开发者，我希望模板验证逻辑能够正确区分内置模板和自定义模板，以便用户可以使用任何有效的模板上传素材。

#### 验收标准

1. WHEN 用户使用内置模板ID（以 `builtin-` 开头）上传素材 THEN 系统应验证模板key是否在预设列表中
2. WHEN 用户使用自定义模板ID上传素材 THEN 系统应从数据库查询验证模板是否存在
3. WHEN 模板验证失败 THEN 系统应返回清晰的错误信息，说明是内置模板无效还是自定义模板不存在
4. WHEN 模板ID为空或null THEN 系统应允许上传（向后兼容旧数据）

### 需求 2: 自定义模板字段处理

**用户故事**: 作为管理员，我希望创建的自定义模板字段能够正确保存和读取，以便用户上传时能看到正确的表单字段。

#### 验收标准

1. WHEN 管理员创建自定义模板并添加字段 THEN 系统应正确保存所有字段属性（key, label, type, required等）
2. WHEN 用户选择自定义模板上传素材 THEN 系统应正确读取并显示所有模板字段
3. WHEN 用户填写自定义模板字段并提交 THEN 系统应正确保存字段值到 metadata 或对应的数据库字段
4. WHEN 自定义模板字段类型为 select THEN 系统应正确解析和显示选项列表
5. WHEN 自定义模板字段设置为必填 THEN 系统应在提交前验证该字段不为空

### 需求 3: 模板字段同步优化

**用户故事**: 作为管理员，我希望模板字段能够自动同步到字段池，以便在分类管理中使用这些字段。

#### 验收标准

1. WHEN 管理员创建或更新模板并勾选字段的 `addToCategory` THEN 系统应自动将该字段同步到字段池
2. WHEN 管理员删除模板 THEN 系统应清理该模板相关的字段池数据（如果没有其他模板使用）
3. WHEN 多个模板使用相同的字段key THEN 系统应合并这些字段的选项
4. WHEN 字段选项包含脏数据（如 `[[[xxx]]]`） THEN 系统应自动清洗并规范化选项值

### 需求 4: 模板版本控制

**用户故事**: 作为管理员，我希望在编辑模板时能够检测并发冲突，以避免覆盖其他管理员的修改。

#### 验收标准

1. WHEN 管理员打开模板编辑页面 THEN 系统应记录当前模板版本号
2. WHEN 管理员保存模板 THEN 系统应检查版本号是否与数据库一致
3. WHEN 版本号不一致 THEN 系统应拒绝保存并提示"模板已被其他人修改，请刷新后重试"
4. WHEN 保存成功 THEN 系统应自动递增版本号

### 需求 5: 模板数据完整性

**用户故事**: 作为系统开发者，我希望模板数据始终保持完整性，以避免数据损坏导致的系统错误。

#### 验收标准

1. WHEN 创建或更新模板 THEN 系统应验证所有必填字段（name, materialType, materialKind）
2. WHEN 模板字段的 key 重复 THEN 系统应拒绝保存并提示错误
3. WHEN 模板字段的 optionsStatic 为数组 THEN 系统应自动转换为JSON字符串
4. WHEN 模板的 materialKind 不在允许列表中 THEN 系统应使用默认值 'IMAGE'
5. WHEN 删除模板时有素材正在使用 THEN 系统应警告管理员（但允许删除，素材的 templateId 会变为 null）

### 需求 6: 错误处理和日志

**用户故事**: 作为系统开发者，我希望模板相关操作有完善的错误处理和日志记录，以便快速定位和解决问题。

#### 验收标准

1. WHEN 模板操作发生错误 THEN 系统应记录详细的错误日志（包括错误类型、堆栈、请求数据）
2. WHEN Prisma 返回特定错误代码 THEN 系统应返回用户友好的错误信息
3. WHEN 字段池同步失败 THEN 系统应记录错误但不影响模板保存
4. WHEN 模板验证失败 THEN 系统应返回清晰的错误信息，包含失败原因和建议操作

### 需求 7: 性能优化

**用户故事**: 作为用户，我希望模板加载和保存速度快，以提高工作效率。

#### 验收标准

1. WHEN 获取模板列表 THEN 系统应在 500ms 内返回结果
2. WHEN 保存模板 THEN 系统应在 2秒 内完成（包括字段池同步）
3. WHEN 模板包含大量字段（>20个） THEN 系统应使用事务批量处理，避免多次数据库往返
4. WHEN 字段池同步 THEN 系统应使用批量操作，避免逐个字段处理

### 需求 8: 向后兼容性

**用户故事**: 作为系统维护者，我希望新的优化不会破坏现有功能，以确保系统稳定运行。

#### 验收标准

1. WHEN 旧素材没有 templateId THEN 系统应正常显示和编辑
2. WHEN 旧素材的 templateId 指向已删除的模板 THEN 系统应正常显示（templateId 为 null）
3. WHEN 旧模板没有 materialKind 字段 THEN 系统应使用默认值 'IMAGE'
4. WHEN 旧模板字段没有 addToCategory 属性 THEN 系统应默认为 false

### 需求 9: 模板字段类型支持

**用户故事**: 作为管理员，我希望能够创建多种类型的字段，以满足不同素材的元数据需求。

#### 验收标准

1. WHEN 管理员创建 text 类型字段 THEN 用户上传时应看到单行文本输入框
2. WHEN 管理员创建 textarea 类型字段 THEN 用户上传时应看到多行文本输入框
3. WHEN 管理员创建 select 类型字段 THEN 用户上传时应看到下拉选择框，并能看到所有选项
4. WHEN 管理员创建 number 类型字段 THEN 用户上传时应看到数字输入框，只能输入数字
5. WHEN 管理员创建 date 类型字段 THEN 用户上传时应看到日期选择器
6. WHEN 管理员创建 checkbox 类型字段 THEN 用户上传时应看到复选框
7. WHEN 管理员创建 file 类型字段 THEN 用户上传时应看到文件上传按钮
8. WHEN 管理员创建 image 类型字段 THEN 用户上传时应看到图片上传按钮，并支持预览

### 需求 10: 模板字段验证规则

**用户故事**: 作为管理员，我希望能够为字段设置验证规则，以确保用户输入的数据符合要求。

#### 验收标准

1. WHEN 管理员设置字段为必填 THEN 用户提交时该字段不能为空
2. WHEN 管理员为 text 字段设置最大长度 THEN 用户输入超过长度时应提示错误
3. WHEN 管理员为 number 字段设置最小值和最大值 THEN 用户输入超出范围时应提示错误
4. WHEN 管理员为字段设置正则表达式验证 THEN 用户输入不匹配时应提示错误
5. WHEN 验证失败 THEN 系统应显示清晰的错误提示，说明哪个字段不符合要求

### 需求 11: 模板字段布局配置

**用户故事**: 作为管理员，我希望能够配置字段的布局，以优化上传表单的用户体验。

#### 验收标准

1. WHEN 管理员设置字段布局为 'full' THEN 该字段应占据整行
2. WHEN 管理员设置字段布局为 'half' THEN 该字段应占据半行，可与其他半行字段并排显示
3. WHEN 管理员拖拽调整字段顺序 THEN 上传表单应按新顺序显示字段
4. WHEN 管理员设置字段为只读 THEN 用户上传时该字段应显示但不可编辑
5. WHEN 管理员设置字段的显示条件 THEN 只有满足条件时该字段才显示

### 需求 12: 模板与素材的关联

**用户故事**: 作为用户，我希望能够看到素材使用的模板，以便了解素材的元数据结构。

#### 验收标准

1. WHEN 用户查看素材详情 THEN 系统应显示该素材使用的模板名称
2. WHEN 用户编辑素材 THEN 系统应根据模板动态生成编辑表单
3. WHEN 素材的模板被删除 THEN 素材应仍然可以查看和编辑（使用通用表单）
4. WHEN 用户筛选素材 THEN 系统应支持按模板类型筛选
5. WHEN 管理员查看模板 THEN 系统应显示使用该模板的素材数量

### 需求 13: 模板导入导出

**用户故事**: 作为管理员，我希望能够导入导出模板配置，以便在不同环境间迁移或备份模板。

#### 验收标准

1. WHEN 管理员导出模板 THEN 系统应生成包含所有字段配置的 JSON 文件
2. WHEN 管理员导入模板 THEN 系统应验证 JSON 格式并创建新模板
3. WHEN 导入的模板名称已存在 THEN 系统应提示管理员选择覆盖或重命名
4. WHEN 导入的模板包含无效字段类型 THEN 系统应拒绝导入并提示错误
5. WHEN 导出多个模板 THEN 系统应支持批量导出为单个 JSON 文件

### 需求 14: 模板使用统计

**用户故事**: 作为管理员，我希望能够查看模板的使用情况，以便优化模板配置。

#### 验收标准

1. WHEN 管理员查看模板列表 THEN 系统应显示每个模板的使用次数
2. WHEN 管理员查看模板详情 THEN 系统应显示最近使用该模板上传的素材列表
3. WHEN 管理员查看模板统计 THEN 系统应显示每个字段的填写率
4. WHEN 某个字段填写率很低 THEN 系统应建议管理员考虑将其设为可选或删除
5. WHEN 模板长期未使用 THEN 系统应建议管理员归档该模板

### 需求 15: 模板权限控制

**用户故事**: 作为超级管理员，我希望能够控制哪些管理员可以创建和修改模板，以确保模板配置的安全性。

#### 验收标准

1. WHEN 普通用户访问模板管理页面 THEN 系统应拒绝访问并提示权限不足
2. WHEN 管理员访问模板管理页面 THEN 系统应允许查看和编辑模板
3. WHEN 超级管理员访问模板管理页面 THEN 系统应允许所有操作（包括删除）
4. WHEN 管理员尝试删除正在使用的模板 THEN 系统应警告但允许删除（素材不受影响）
5. WHEN 管理员修改模板 THEN 系统应记录操作日志（谁在何时修改了什么）

### 需求 16: 自定义字段的创建和管理

**用户故事**: 作为管理员，我希望能够灵活地创建和管理模板中的自定义字段，以适应不同类型素材的元数据需求。

#### 验收标准

1. WHEN 管理员在模板编辑器中点击"添加字段" THEN 系统应显示字段配置表单
2. WHEN 管理员输入字段key THEN 系统应实时验证key的唯一性和格式（只允许字母、数字、下划线）
3. WHEN 管理员输入字段label THEN 系统应自动将其作为显示名称
4. WHEN 管理员选择字段类型 THEN 系统应根据类型显示相应的配置选项（如select类型显示选项配置）
5. WHEN 管理员拖拽字段调整顺序 THEN 系统应实时更新字段的 orderIndex
6. WHEN 管理员删除字段 THEN 系统应确认操作并警告可能影响已有素材
7. WHEN 管理员复制字段 THEN 系统应创建一个新字段，key自动添加后缀避免冲突

### 需求 17: 自定义字段的选项管理（select类型）

**用户故事**: 作为管理员，我希望能够为下拉选择字段配置选项列表，并支持动态添加和编辑选项。

#### 验收标准

1. WHEN 管理员为select字段添加选项 THEN 系统应支持逐行输入或JSON数组格式
2. WHEN 管理员输入的选项包含特殊字符或空格 THEN 系统应自动清洗并规范化
3. WHEN 管理员输入重复的选项 THEN 系统应自动去重
4. WHEN 管理员输入嵌套数组格式（如 `[[[option]]]`） THEN 系统应自动展开为单层数组
5. WHEN 管理员保存模板 THEN 系统应将选项数组转换为JSON字符串存储
6. WHEN 用户上传素材时 THEN 系统应正确解析选项并显示在下拉框中
7. WHEN 管理员修改选项列表 THEN 系统应保持已有素材的选项值不变（即使选项被删除）

### 需求 18: 自定义字段的验证配置

**用户故事**: 作为管理员，我希望能够为自定义字段配置验证规则，确保用户输入的数据质量。

#### 验收标准

1. WHEN 管理员勾选"必填" THEN 用户上传时该字段必须填写
2. WHEN 管理员为text字段设置最大长度 THEN 系统应在前端和后端都进行验证
3. WHEN 管理员为number字段设置范围 THEN 系统应验证输入值在范围内
4. WHEN 管理员设置正则表达式验证 THEN 系统应在用户输入时实时验证并提示
5. WHEN 管理员设置自定义错误提示 THEN 验证失败时应显示自定义消息
6. WHEN 验证规则冲突（如最小值大于最大值） THEN 系统应在保存模板时提示错误
7. WHEN 用户提交表单 THEN 系统应按字段顺序依次验证，并显示所有错误

### 需求 19: 自定义字段的条件显示

**用户故事**: 作为管理员，我希望能够设置字段的显示条件，根据其他字段的值动态显示或隐藏字段。

#### 验收标准

1. WHEN 管理员为字段设置显示条件 THEN 系统应提供可视化的条件编辑器
2. WHEN 管理员设置"当字段A等于值X时显示" THEN 用户上传时应根据条件动态显示字段
3. WHEN 管理员设置多个条件（AND/OR逻辑） THEN 系统应正确计算条件结果
4. WHEN 条件字段的值改变 THEN 系统应实时重新计算并更新字段显示状态
5. WHEN 隐藏的字段有值 THEN 系统应保留该值（不清空）
6. WHEN 条件配置循环依赖（A依赖B，B依赖A） THEN 系统应在保存时检测并拒绝
7. WHEN 条件字段被删除 THEN 系统应警告并清除相关的条件配置

### 需求 20: 自定义字段的数据存储和读取

**用户故事**: 作为系统开发者，我希望自定义字段的数据能够可靠地存储和读取，支持不同的存储策略。

#### 验收标准

1. WHEN 自定义字段key与Material模型的标准字段匹配 THEN 系统应直接存储到对应的数据库字段
2. WHEN 自定义字段key不匹配标准字段 THEN 系统应将其存储到 metadata JSON字段中
3. WHEN 用户上传素材 THEN 系统应正确解析templateFields并分配到对应的存储位置
4. WHEN 用户查看素材详情 THEN 系统应从标准字段和metadata中合并读取所有字段值
5. WHEN 用户编辑素材 THEN 系统应根据模板动态生成表单，并预填充现有值
6. WHEN metadata字段超过数据库限制 THEN 系统应压缩或分片存储
7. WHEN 模板字段被删除但素材中有该字段的值 THEN 系统应保留数据但不显示在编辑表单中

### 需求 21: 自定义字段的迁移和兼容性

**用户故事**: 作为系统维护者，我希望在修改模板字段时，已有素材的数据能够平滑迁移，不会丢失或损坏。

#### 验收标准

1. WHEN 管理员修改字段的key THEN 系统应提供数据迁移工具，将旧key的值迁移到新key
2. WHEN 管理员修改字段类型（如text改为select） THEN 系统应验证现有数据是否兼容
3. WHEN 字段类型不兼容 THEN 系统应警告并提供数据转换选项
4. WHEN 管理员删除字段 THEN 系统应保留素材中的数据（存储在metadata中）但不显示
5. WHEN 管理员恢复已删除的字段（相同key） THEN 系统应自动恢复素材中的数据
6. WHEN 模板版本升级 THEN 系统应支持批量更新素材的字段结构
7. WHEN 数据迁移失败 THEN 系统应回滚并记录详细的错误日志

### 需求 22: 自定义字段的性能优化

**用户故事**: 作为用户，我希望即使模板包含大量自定义字段，上传和编辑素材的速度也不会明显变慢。

#### 验收标准

1. WHEN 模板包含超过30个字段 THEN 系统应使用虚拟滚动或分页显示
2. WHEN 用户填写表单 THEN 系统应使用防抖技术减少验证频率
3. WHEN 用户提交表单 THEN 系统应批量验证所有字段，避免多次往返
4. WHEN 字段有复杂的显示条件 THEN 系统应缓存条件计算结果
5. WHEN 加载素材详情 THEN 系统应并行读取标准字段和metadata
6. WHEN 保存素材 THEN 系统应使用事务确保标准字段和metadata同时更新
7. WHEN metadata字段过大 THEN 系统应使用压缩算法减少存储空间

### 需求 23: 自定义字段的错误恢复

**用户故事**: 作为用户，我希望在填写表单时如果发生错误，我的输入不会丢失，可以继续编辑。

#### 验收标准

1. WHEN 用户填写表单时 THEN 系统应自动保存草稿到浏览器本地存储
2. WHEN 用户刷新页面或意外关闭 THEN 系统应提示恢复未保存的数据
3. WHEN 提交失败（网络错误、验证失败等） THEN 系统应保留用户输入，允许修改后重新提交
4. WHEN 用户在多个标签页同时编辑 THEN 系统应检测冲突并提示用户
5. WHEN 草稿数据过期（超过7天） THEN 系统应自动清理
6. WHEN 用户主动清除草稿 THEN 系统应提供"清除草稿"按钮
7. WHEN 用户成功提交 THEN 系统应自动清除对应的草稿数据

### 需求 24: 字段池同步的完整性和一致性

**用户故事**: 作为系统开发者，我希望模板字段与字段池之间的同步是完整、一致且可靠的，确保首页筛选和分类管理功能正常工作。

#### 验收标准

1. WHEN 管理员勾选字段的 `addToCategory` 并保存模板 THEN 系统应立即将该字段同步到字段池（FieldDefinition表）
2. WHEN 多个模板包含相同key的字段 THEN 系统应合并这些字段的选项到同一个FieldDefinition记录
3. WHEN 管理员取消勾选字段的 `addToCategory` THEN 系统应检查是否有其他模板使用该字段，如果没有则从字段池删除
4. WHEN 管理员修改字段的选项列表 THEN 系统应更新字段池中的FieldOption记录
5. WHEN 字段池同步过程中发生错误 THEN 系统应记录详细日志但不影响模板保存，并在后台重试
6. WHEN 字段池数据与模板数据不一致 THEN 系统应提供"重新同步"工具，管理员可手动触发全量同步
7. WHEN 系统启动时 THEN 系统应自动检查字段池完整性，发现问题自动修复

### 需求 25: 首页分类Tag按钮的动态生成

**用户故事**: 作为用户，我希望首页的分类Tag按钮能够准确反映字段池中的分类数据，并且加载速度快、交互流畅。

#### 验收标准

1. WHEN 用户访问首页 THEN 系统应从字段池读取所有启用的筛选字段（isFilterEnabled=true）
2. WHEN 字段池包含多个字段 THEN 系统应按 filterOrder 排序显示Tag按钮
3. WHEN 用户点击Tag按钮 THEN 系统应展开该字段的所有选项，并高亮当前选中的选项
4. WHEN 用户选择某个选项 THEN 系统应立即筛选素材列表，并更新URL参数
5. WHEN 字段的选项过多（>20个） THEN 系统应使用虚拟滚动或分页显示
6. WHEN 字段的 filterDisplayName 存在 THEN 系统应优先显示自定义名称，否则显示 label
7. WHEN 管理员在后台修改字段池 THEN 首页应在下次刷新时自动更新Tag按钮（无需重启服务）

### 需求 26: 首页Tag按钮的性能优化

**用户故事**: 作为用户，我希望首页Tag按钮的切换和筛选操作非常流畅，不会出现卡顿或闪烁。

#### 验收标准

1. WHEN 用户切换Tag按钮 THEN 系统应在100ms内完成UI更新（无闪烁）
2. WHEN 用户快速连续点击多个Tag THEN 系统应使用防抖技术，避免重复请求
3. WHEN 素材列表数据量大（>1000条） THEN 系统应使用虚拟滚动和分页加载
4. WHEN 用户选择多个筛选条件 THEN 系统应合并为单次API请求
5. WHEN 筛选结果为空 THEN 系统应显示友好的空状态提示，并建议清除筛选条件
6. WHEN 用户清除所有筛选 THEN 系统应快速恢复到初始状态
7. WHEN Tag按钮数量过多 THEN 系统应使用横向滚动或折叠显示，避免布局混乱

### 需求 27: 后台分类管理的字段池集成

**用户故事**: 作为管理员，我希望在后台分类管理页面能够方便地管理字段池，包括启用/禁用字段、调整顺序、重命名显示名称等。

#### 验收标准

1. WHEN 管理员进入分类管理页面 THEN 系统应显示所有字段池中的字段（包括已启用和未启用）
2. WHEN 管理员拖拽字段调整顺序 THEN 系统应实时更新 filterOrder，并同步到首页Tag按钮顺序
3. WHEN 管理员点击"重命名"按钮 THEN 系统应弹出输入框，允许修改 filterDisplayName
4. WHEN 管理员点击"启用/禁用"按钮 THEN 系统应切换 isFilterEnabled 状态，并立即反映到首页
5. WHEN 管理员点击字段卡片 THEN 系统应在右侧显示该字段的所有选项
6. WHEN 管理员添加/删除/重命名选项 THEN 系统应更新 FieldOption 表，并同步到所有使用该字段的模板
7. WHEN 管理员点击"刷新"按钮 THEN 系统应重新从模板同步字段池数据

### 需求 28: 分类管理的选项清洗和规范化

**用户故事**: 作为管理员，我希望系统能够自动清洗和规范化字段选项，避免脏数据影响用户体验。

#### 验收标准

1. WHEN 字段选项包含多余的括号（如 `[[[选项]]]`） THEN 系统应自动去除多余括号
2. WHEN 字段选项包含前后空格 THEN 系统应自动trim
3. WHEN 字段选项包含特殊字符（如引号、反斜杠） THEN 系统应自动转义或清除
4. WHEN 字段选项为嵌套数组格式（如 `["[选项1,选项2]"]`） THEN 系统应自动展开为单层数组
5. WHEN 字段选项重复 THEN 系统应自动去重
6. WHEN 字段选项为空字符串 THEN 系统应自动过滤
7. WHEN 清洗过程发现无法处理的数据 THEN 系统应记录警告日志并跳过该选项

### 需求 29: 分类管理的批量操作

**用户故事**: 作为管理员，我希望能够批量操作字段和选项，提高管理效率。

#### 验收标准

1. WHEN 管理员选中多个字段 THEN 系统应显示批量操作按钮（启用/禁用/删除）
2. WHEN 管理员批量启用字段 THEN 系统应一次性更新所有选中字段的 isFilterEnabled
3. WHEN 管理员批量删除字段 THEN 系统应确认操作并警告影响范围
4. WHEN 管理员批量导入选项 THEN 系统应支持CSV或JSON格式，并自动清洗数据
5. WHEN 管理员批量导出选项 THEN 系统应生成包含所有字段和选项的JSON文件
6. WHEN 批量操作失败 THEN 系统应显示详细的错误报告，说明哪些操作成功、哪些失败
7. WHEN 批量操作涉及大量数据（>100条） THEN 系统应显示进度条并支持取消

### 需求 30: 分类管理与模板的双向同步

**用户故事**: 作为管理员，我希望分类管理和模板管理之间能够双向同步，修改任何一方都能反映到另一方。

#### 验收标准

1. WHEN 管理员在分类管理中修改字段选项 THEN 系统应自动更新所有使用该字段的模板
2. WHEN 管理员在模板管理中修改字段选项 THEN 系统应自动同步到字段池
3. WHEN 管理员在分类管理中删除字段 THEN 系统应警告哪些模板正在使用该字段
4. WHEN 管理员在模板管理中删除字段 THEN 系统应检查字段池是否还有其他模板使用
5. WHEN 同步过程中发生冲突（如两个管理员同时修改） THEN 系统应使用版本号检测并提示冲突
6. WHEN 同步失败 THEN 系统应回滚所有相关修改，确保数据一致性
7. WHEN 管理员查看同步历史 THEN 系统应显示详细的同步日志（时间、操作、结果）