ttstd-infinite-canvas/DEPLOYMENT_GUIDE.md

模型目录开关功能部署指南

问题修复

已解决以下问题：

1. ✅ 后端路由未注册 - 已在 cmd/server/main.go 中注册 RegisterModelCatalogRoutes
2. ✅ 前端初始化仍调用旧接口 - 已修改 user-session.ts 在登录和刷新时调用统一目录接口
3. ✅ 前端菜单未根据开关隐藏 - 已修改 admin-shell.tsx 根据 frontendModelsEnabled 过滤菜单
4. ✅ 路由未拦截直接访问 - 已在 router.tsx 中添加 RequireFeature 检查

部署步骤

1. 重新编译后端

cd /Users/catdd/Desktop/work/infinite-canvas/backend
go build -o bin/server ./cmd/server

2. 重启后端服务

# 停止当前服务
pkill -f "infinite-canvas.*server"

# 启动新服务
./bin/server

3. 验证后端接口

# 测试统一目录接口
curl http://localhost:3000/api/model-catalog

# 应该返回类似：
# {
#   "source": "frontend",
#   "models": [...]
# }

4. 编译前端

cd /Users/catdd/Desktop/work/infinite-canvas/web
npm run build

5. 刷新浏览器

清除浏览器缓存并刷新页面，确保加载最新的前端代码。

功能测试

测试场景 1：前台模型开启（默认）

1. 登录管理后台
2. 进入"功能开放"页面
3. 确认"前台模型"开关为开启状态
4. 观察左侧菜单：应显示"前台模型"菜单项
5. 进入创作页面，查看模型选择器：应显示前台模型
6. 创建任务：应使用 logicalModelId

测试场景 2：关闭前台模型

1. 在"功能开放"页面，点击"前台模型"开关关闭
2. 确认二次确认对话框，点击"确认关闭"
3. 观察左侧菜单："前台模型"菜单项应消失
4. 尝试直接访问 /admin/models：应显示"前台模型暂未开放"提示
5. 刷新页面，进入创作页面
6. 查看模型选择器：应显示系统渠道中的模型（不再是前台模型）
7. 创建任务：应使用 channelId + model（不再有 logicalModelId）

测试场景 3：重新开启前台模型

1. 在"功能开放"页面，点击"前台模型"开关开启
2. 观察左侧菜单：应重新显示"前台模型"菜单项
3. 刷新页面，进入创作页面
4. 查看模型选择器：应重新显示前台模型

关键验证点

✓ 管理后台

• "管理后台功能"卡片正常显示
• "前台模型"开关可以正常切换
• 关闭时显示二次确认对话框
• 关闭后左侧菜单隐藏"前台模型"项
• 开启后左侧菜单显示"前台模型"项

✓ 用户端（前台模型开启）

• 模型选择器显示前台模型列表
• 创建任务时带 logicalModelId
• 任务正常执行

✓ 用户端（前台模型关闭）

• 模型选择器显示系统渠道模型列表
• 创建任务时带 channelId + model，不带 logicalModelId
• 任务正常执行
• 刷新页面后仍然显示系统渠道模型

✓ 接口调用

• /api/model-catalog 返回正确的数据
• 开启时 source: "frontend"
• 关闭时 source: "system"

常见问题排查

问题1：接口返回 404

原因：后端未重启或路由未注册 解决：

# 确认路由注册
grep "RegisterModelCatalogRoutes" /Users/catdd/Desktop/work/infinite-canvas/backend/cmd/server/main.go

# 重新编译并重启
cd backend
go build -o bin/server ./cmd/server
./bin/server

问题2：关闭开关后仍显示前台模型

原因：前端未刷新或浏览器缓存 解决：

1. 硬刷新浏览器（Cmd+Shift+R / Ctrl+Shift+F5）
2. 清除浏览器缓存
3. 检查浏览器控制台是否有错误

问题3：菜单未隐藏

原因：前端代码未更新 解决：

cd web
npm run build
# 清除浏览器缓存并刷新

问题4：模型选择器为空

原因：系统渠道无可用模型或接口异常 解决：

1. 检查浏览器控制台网络请求
2. 查看 /api/model-catalog 返回的数据
3. 确认系统渠道中有启用且配置价格的模型

API 对照表

场景	旧接口	新接口	返回数据
前台模型开启	/api/models	/api/model-catalog	{source:"frontend", models:[...]}
前台模型关闭	-	/api/model-catalog	{source:"system", channels:[...]}

数据流图

前台模型开启

用户登录
  ↓
前端调用 /api/model-catalog
  ↓
后端检查 frontendModelsEnabled = true
  ↓
返回 {source:"frontend", models:[前台模型]}
  ↓
前端加载前台模型到选择器
  ↓
用户创建任务（带 logicalModelId）

前台模型关闭

用户登录
  ↓
前端调用 /api/model-catalog
  ↓
后端检查 frontendModelsEnabled = false
  ↓
返回 {source:"system", channels:[系统渠道模型]}
  ↓
前端加载系统渠道模型到选择器
  ↓
用户创建任务（带 channelId + model）

文件修改清单

后端

• ✅ cmd/server/main.go - 注册路由
• ✅ internal/handler/model_catalog.go - 新增统一目录接口
• ✅ internal/service/model_catalog.go - 实现目录逻辑
• ✅ internal/service/task_creation.go - 任务创建分流
• ✅ internal/service/feature_availability.go - 添加开关

前端

• ✅ services/api/logical-models.ts - 新增API函数
• ✅ lib/user-session.ts - 调用统一目录接口
• ✅ stores/use-user-store.ts - 添加类型定义
• ✅ pages/admin/components/feature-availability-panel.tsx - 添加开关UI
• ✅ pages/admin/components/admin-shell.tsx - 菜单过滤
• ✅ components/auth/require-feature.tsx - 添加权限检查
• ✅ router.tsx - 路由拦截

下一步工作

1. 数据库迁移（创建 logical_model_price_skus 表）
2. 编写单元测试
3. 压力测试
4. 文档更新

---

创建时间: 2026-08-22 状态: 待部署测试