213 lines
5.8 KiB
Markdown
213 lines
5.8 KiB
Markdown
# 模型目录开关功能部署指南
|
||
|
||
## 问题修复
|
||
|
||
已解决以下问题：
|
||
1. ✅ 后端路由未注册 - 已在 `cmd/server/main.go` 中注册 `RegisterModelCatalogRoutes`
|
||
2. ✅ 前端初始化仍调用旧接口 - 已修改 `user-session.ts` 在登录和刷新时调用统一目录接口
|
||
3. ✅ 前端菜单未根据开关隐藏 - 已修改 `admin-shell.tsx` 根据 `frontendModelsEnabled` 过滤菜单
|
||
4. ✅ 路由未拦截直接访问 - 已在 `router.tsx` 中添加 `RequireFeature` 检查
|
||
|
||
## 部署步骤
|
||
|
||
### 1. 重新编译后端
|
||
|
||
```bash
|
||
cd /Users/catdd/Desktop/work/infinite-canvas/backend
|
||
go build -o bin/server ./cmd/server
|
||
```
|
||
|
||
### 2. 重启后端服务
|
||
|
||
```bash
|
||
# 停止当前服务
|
||
pkill -f "infinite-canvas.*server"
|
||
|
||
# 启动新服务
|
||
./bin/server
|
||
```
|
||
|
||
### 3. 验证后端接口
|
||
|
||
```bash
|
||
# 测试统一目录接口
|
||
curl http://localhost:3000/api/model-catalog
|
||
|
||
# 应该返回类似：
|
||
# {
|
||
# "source": "frontend",
|
||
# "models": [...]
|
||
# }
|
||
```
|
||
|
||
### 4. 编译前端
|
||
|
||
```bash
|
||
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
|
||
**原因**：后端未重启或路由未注册
|
||
**解决**：
|
||
```bash
|
||
# 确认路由注册
|
||
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：菜单未隐藏
|
||
**原因**：前端代码未更新
|
||
**解决**：
|
||
```bash
|
||
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
|
||
**状态**: 待部署测试
|