flnxi-Wu/docs/archive/素材模板迁移指南.md

素材模板迁移指南（新版本）

面向 AI 编程平台（如 Cursor）编写，帮助快速理解“素材模板 = 素材类型”的全新架构，并指导从老版本迁移。

1. 架构变化速览

• 模板即素材类型：预制模板只保留 6 类（3DMAX、PSD、AI 工作流、视频、模特、其他），materialType 作为模板元数据存储在 upload_templates.materialType 字段中。
• 字段更精简：表单中不再渲染 materialType 字段，通用字段统一来自 STANDARD_FIELD_TEMPLATES，必填逻辑由模板控制。
• 前台上传：components/UploadModal.tsx 依据模板元数据决定素材类型，不再依赖隐藏字段。
• 同步机制：BroadcastChannel + localStorage 继续用于前后台同步启用状态，无需重新部署即可生效。

2. 迁移步骤（按顺序执行）

Step 1：数据库

1. 执行 Prisma 迁移 20251124001000_add_material_type_to_templates：

   npx prisma migrate deploy
   

2. 如需要手动执行：

   ALTER TABLE "upload_templates"
   ADD COLUMN "materialType" TEXT NOT NULL DEFAULT '其他';
   UPDATE "upload_templates"
   SET "materialType" = COALESCE(NULLIF("materialType", ''), '其他');
   

Step 2：后端

• 确保以下 API 已更新并部署：
  • app/api/upload-templates/route.ts
  • app/api/admin/upload-templates/*
  • app/api/templates/route.ts
  • app/api/material-types/route.ts
  • app/api/template-categories/*
  • app/api/materials/route.ts
• 关键检查点：
  • API 返回的模板对象需包含 materialType。
  • 预制模板列表只包含 6 个 key。
  • template-categories 不再引用 materialType 字段。

Step 3：前端

• 主要文件：
  • app/admin/_components/TemplateManager.tsx
  • app/admin/_components/template-manager/*
  • components/UploadModal.tsx
• 必须确认：
  1. 新建/编辑模板时可选择素材类型（下拉框来自 MATERIAL_TYPE_OPTIONS）。
  2. 保存模板时写入 materialType 字段。
  3. 上传弹窗根据模板的 materialType 控制字段、校验与文件要求。
  4. 预制模板列表与文档保持一致（3DMAX、PSD、AI 工作流、视频、模特、其他）。

Step 4：文档与校验

• 更新 docs/素材类型模板配置记录.md（已完成）。
• 确认根目录的本指南同步提交，供 AI 工具拉取。
• 回归测试：
  • 切换预制模板触发前台刷新。
  • 上传不同类型素材，验证必填校验、文件校验与标签显示。
  • 首页筛选（模板 + 素材类型）可用。

3. 常见问题（FAQ）

问题	说明	排查建议
模板保存后 materialType 为空	旧模板未手动选择类型	在后台编辑模板，补全素材类型后再次保存
前台上传仍出现“素材类型”字段	构建未更新或缓存未失效	清理 .next、重新构建并刷新浏览器缓存
/api/material-types 返回旧数据	未部署最新 API 或存在历史模板	确认路由已更新，并检查 upload_templates.materialType
预制模板仍包含 CAD/C4D	enabledBuiltinTemplates 仍记录旧 key	在数据库 system_settings.enabledBuiltinTemplates 中清理旧 key

4. 建议的提交流程

1. 开发：在本地完成所有代码改造 + 文档更新。
2. 检查：npm run lint / npm run build，确保无类型/构建错误。
3. 部署：执行 deploy-new-fixed.ps1（或 CI/CD 流程），留意镜像推送日志。
4. 验证：访问 /admin 与 /，测试 6 种模板上传路径。

---

如需进一步扩展素材类型，请在 BUILTIN_TEMPLATES 与 BUILTIN_TEMPLATE_TYPES 中新增配置，并同步更新本文档与 docs/素材类型模板配置记录.md。 AI 平台可直接搜索“素材模板迁移指南”获取最新步骤。*** End Patch