# 洛天依管理系统 - 功能清单与开发状态

> 生成时间：2026-03-19（已通过 API 实测验证）

---

## 一、整体架构

| 组件 | 技术栈 | 路径 |
|------|--------|------|
| 后端 API | Django + DRF + Channels + Daphne | `qy_lty/` |
| 管理后台前端 | Next.js 15 + React 19 + Tailwind + shadcn/ui | `qy-lty-admin/` |
| 数据库 | PostgreSQL（阿里云 RDS） | 远程 |
| 缓存/消息 | Redis（阿里云） | 远程 |

---

## 二、功能模块状态总览

| 模块 | 前端页面 | 后端 API | 前后端对接 | 后端实测数据 | 状态 |
|------|----------|----------|------------|-------------|------|
| 邮箱登录 | ✅ | ✅ | ✅ 已对接 | ✅ 返回 token | ✅ 完成 |
| 手机登录 | ✅ UI | ✅ 已验证 | ❌ 未对接 | ✅ 接口可用 | ⚠️ 待对接 |
| 注册 | ✅ UI | ✅ 已验证 | ❌ 未对接 | ✅ 接口可用（返回参数校验） | ⚠️ 待对接 |
| 忘记密码 | ✅ UI | ✅ 已验证 | ❌ 未对接 | ✅ 接口可用 | ⚠️ 待对接 |
| 仪表盘 | ✅ UI | ❌ 无统计接口 | ❌ 硬编码数据 | — | ⚠️ 待开发 |
| 用户管理 | ✅ | ✅ | ✅ 已对接 | ✅ 5 条数据 | ✅ 完成 |
| 歌曲管理 | ✅ | ✅ | ✅ 已对接 | ✅ 9 条数据 | ✅ 完成 |
| 舞蹈管理 | ✅ UI | ✅ 已验证 | ❌ 前端用 mock | ✅ 5 条数据 | ⚠️ 待对接 |
| 服装管理 | ✅ UI | ✅ 已验证 | ❌ 前端用 mock | ✅ 11 条数据 | ⚠️ 待对接 |
| 道具管理 | ✅ UI | ✅ 已验证 | ❌ 前端用 mock | ✅ 3 条数据 | ⚠️ 待对接 |
| 家居装饰 | ✅ UI | ✅ 已验证 | ❌ 前端用 mock | ✅ 6 条数据 | ⚠️ 待对接 |
| 食物管理 | ✅ | ✅ | ✅ 已对接 | ✅ 5 条数据 | ✅ 完成 |
| 成就系统 | ✅ UI | ✅ 已验证 | ❌ 前端用 mock | ✅ 13 条数据 | ⚠️ 待对接 |
| 好感度 | ✅ UI | ✅ 已验证 | ❌ 前端用 mock | ✅ 接口可用（暂无数据） | ⚠️ 待对接 |
| AI 模型管理 | ✅ UI | ✅ 已验证 | ❌ 前端纯展示 | ✅ 1 个 Bot | ⚠️ 待对接 |
| 权限管理 | ✅ UI | ✅ 已验证 | ❌ 前端用 mock | ✅ 接口可用（暂无数据） | ⚠️ 待对接 |
| 系统设置 | ✅ UI | ❌ 无接口 | ❌ 无持久化 | — | ❌ 待开发 |
| 设备管理 | ❌ 无页面 | ✅ 已验证 | ❌ | ✅ 2 类型/20 设备 | ❌ 前端待开发 |
| 订阅管理 | ❌ 无页面 | ⚠️ 有模型无接口 | ❌ | — | ❌ 待开发 |
| 工作流 | ❌ 无页面 | ❌ 空模块 | ❌ | — | ❌ 待开发 |

---

## 三、已完成功能详细说明

### 1. 邮箱登录（✅ 完成）

- **前端**：`/login` 页面，邮箱 + 密码表单
- **后端**：`POST /api/v1/admin/login/` → 返回 token
- **使用方式**：输入邮箱和密码，登录后 token 自动存储到 localStorage 和 Cookie
- **测试账号**：邮箱 `111111@qq.com`，密码 `111111`

### 2. 用户管理（✅ 完成）

- **前端**：`/users` 页面，完整 CRUD
- **后端**：`/api/user/` ViewSet
- **功能**：
  - 用户列表（分页、搜索）
  - 新增用户
  - 编辑用户信息
  - 删除用户
  - 切换用户状态（启用/禁用）

### 3. 歌曲管理（✅ 完成）

- **前端**：`/songs` 列表页 + `/songs/[id]` 详情页
- **后端**：`/api/card/category/song/` + `/api/card/templates/`
- **功能**：
  - 歌曲列表（分页、搜索）
  - 新增/编辑歌曲（含音频上传）
  - 发布/取消发布
  - 批次生成与管理
  - 音频播放器（播放/暂停/音量控制）

### 4. 食物管理（✅ 完成）

- **前端**：`/food` 列表页 + `/food/[id]` 详情页
- **后端**：`/api/food/foods/`
- **功能**：
  - 食物列表（分页、搜索、分类筛选）
  - 新增/编辑/删除食物
  - 食物分类和稀有度管理
  - 使用记录查看

---

## 四、待对接功能（前后端都有，需要连接）

以下模块前端 UI 已完成，后端 API 已存在，但前端页面使用的是 mock 硬编码数据，需要替换为真实 API 调用。

### 5. 舞蹈管理（⚠️ 待对接）

- **前端**：`/dances` 页面，使用 `initialDances` 硬编码 5 条数据
- **后端 API**：
  - `GET /api/card/category/dance/` — 舞蹈列表
  - `POST /api/card/templates/` — 创建
  - `PATCH /api/card/templates/{id}/` — 更新
  - `DELETE /api/card/templates/{id}/` — 删除
- **前端 API 模块**：`lib/api/dances.ts` 已写好，页面未调用
- **工作量**：将页面中 mock 数据替换为 API 调用即可

### 6. 服装管理（⚠️ 待对接）

- **前端**：`/outfits` 页面，内联硬编码数据
- **后端 API**：`/api/card/category/clothing/` + `/api/card/templates/`
- **前端 API 模块**：`lib/api/outfits.ts` 已写好
- **工作量**：页面重构程度较大，CRUD 交互不完整

### 7. 道具管理（⚠️ 待对接）

- **前端**：`/props` 页面，使用 `initialProps` 硬编码数据
- **后端 API**：`/api/card/category/prop/` + `/api/card/templates/`
- **前端 API 模块**：`lib/api/props.ts` 已写好
- **工作量**：与舞蹈管理类似，替换 mock 数据

### 8. 家居装饰（⚠️ 待对接）

- **前端**：`/home-decor` 页面，使用 `initialDecors` 硬编码数据
- **后端 API**：`/api/card/category/decoration/` + `/api/card/templates/`
- **前端 API 模块**：`lib/api/home-decor.ts` 已写好
- **工作量**：与舞蹈管理类似，替换 mock 数据

### 9. 成就系统（⚠️ 待对接）

- **前端**：`/achievements` 页面，使用 `mockData` 硬编码 10 条数据
- **后端 API**：
  - `GET /api/achievement/achievements/` — 列表
  - `POST /api/achievement/achievements/` — 创建
  - `PATCH /api/achievement/achievements/{id}/` — 更新
  - `DELETE /api/achievement/achievements/{id}/` — 删除
- **前端 API 模块**：`lib/api/achievements.ts` 已写好
- **工作量**：替换 mock 数据 + 对齐数据结构

### 10. 好感度系统（⚠️ 待对接）

- **前端**：`/affinity` 页面，使用 `initialRules` 和 `initialLevels` 硬编码
- **后端 API**：
  - `/api/user/affinity-rules/` — 好感度规则 CRUD
  - `/api/user/affinity-levels/` — 好感度等级 CRUD
- **前端 API 模块**：`lib/api/affinity.ts` 已写好
- **工作量**：替换 mock 数据

### 11. AI 模型管理（⚠️ 待对接）

- **前端**：`/ai-model` 页面，纯展示页面（框架/微调/语音/知识库 tab）
- **后端 API**：
  - `GET/POST/PATCH/DELETE /api/ai/bots/` — Bot CRUD
- **前端 API 模块**：`lib/api/ai-models.ts` 已写好
- **工作量**：需要将展示页改为管理页，添加 CRUD 交互

### 12. 权限管理（⚠️ 待对接）

- **前端**：`/permissions` 页面，使用 `initialRoles` 硬编码 5 个角色
- **后端 API**：`/api/user/groups/` — Django Group CRUD
- **前端 API 模块**：`lib/api/roles.ts` 已写好
- **工作量**：替换 mock 数据，权限矩阵需与后端权限体系对齐

### 13. 手机登录 / 注册 / 忘记密码（⚠️ 待对接）

- **前端**：UI 表单已完成，但使用 `setTimeout` 模拟请求
- **后端**：
  - 手机登录：`POST /api/user/auth/phone/login/`
  - 发送验证码：`POST /api/user/auth/phone/verify/`
  - 注册：`POST /api/user/auth/register/`
  - 重置密码：`POST /api/user/auth/password/reset/`
- **工作量**：前端对接后端已有接口

---

## 五、待开发功能（缺前端或缺后端）

### 14. 仪表盘数据（❌ 待开发）

- **现状**：前端 `/` 页面显示硬编码统计数据（12,345 用户、5,732 活跃等）
- **需要**：后端开发统计聚合接口，前端对接
- **建议接口**：
  - `GET /api/v1/admin/dashboard/stats/` — 用户统计、卡片统计等

### 15. 系统设置（❌ 待开发）

- **现状**：前端 `/settings` 页面有基本/数据库/安全/通知 4 个 tab，但无持久化
- **需要**：后端设计系统配置模型和接口
- **工作量**：前后端都需要开发

### 16. 设备管理（❌ 前端待开发）

- **后端已有完整 API**：
  - `/api/device/device-types/` — 设备类型 CRUD
  - `/api/device/device-batches/` — 设备批次 CRUD
  - `/api/device/devices/` — 设备 CRUD（含批量创建）
  - `/api/device/user-devices/` — 用户设备绑定
  - `/api/device/messages/` — 消息管理
  - WebSocket：`ws://domain/ws/device/{user_id}/`
- **需要**：开发前端管理页面

### 17. 订阅管理（❌ 前后端待开发）

- **现状**：后端有模型定义（SubscriptionPlan、Subscription、AddOnPackage 等），但无 API 接口
- **需要**：后端开发 API + 前端开发页面

### 18. 工作流系统（❌ 前后端待开发）

- **现状**：后端 `workflow_app` 为空模块，无模型无接口
- **需要**：完整设计和开发

### 19. 阿里云 VI（视觉智能）（❌ 已禁用）

- **现状**：后端 `ali_vi_app` 有人脸相关接口，但在主 urls.py 中已注释禁用
- **接口**：人脸模板、人脸合成、美颜、美妆等
- **状态**：暂不需要管理后台

---

## 六、后端 API 完整清单

### 用户模块 `/api/user/`
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` | 用户列表 |
| POST | `/` | 创建用户 |
| GET/PUT/PATCH/DELETE | `/{id}/` | 用户详情/更新/删除 |
| GET | `/info/` | 当前用户信息 |
| PUT/PATCH | `/update_profile/` | 更新个人资料 |
| POST | `/bind_phone/` | 绑定手机号 |
| GET/POST | `/groups/` | 角色列表/创建 |
| GET/PUT/DELETE | `/groups/{id}/` | 角色详情/更新/删除 |
| GET/POST | `/affinity-rules/` | 好感度规则列表/创建 |
| GET/PUT/DELETE | `/affinity-rules/{id}/` | 规则详情/更新/删除 |
| GET/POST | `/affinity-levels/` | 好感度等级列表/创建 |
| GET/PUT/DELETE | `/affinity-levels/{id}/` | 等级详情/更新/删除 |

### 认证模块 `/api/user/auth/`
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/login/` | 用户名密码登录 |
| POST | `/logout/` | 登出 |
| POST | `/register/` | 注册 |
| POST | `/email/login/` | 邮箱登录 |
| POST | `/phone/login/` | 手机号登录 |
| POST | `/phone/verify/` | 发送验证码 |
| POST | `/username/login/` | 用户名登录 |
| POST | `/mac/login/` | MAC 地址登录 |
| POST | `/password/reset/` | 重置密码 |

### 管理员模块 `/api/v1/admin/`
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/login/` | 管理员邮箱登录 |
| POST | `/logout/` | 管理员登出 |

### AI 模块 `/api/ai/`
| 方法 | 路径 | 说明 |
|------|------|------|
| GET/POST | `/bots/` | Bot 列表/创建 |
| GET/PUT/DELETE | `/bots/{id}/` | Bot 详情/更新/删除 |
| POST | `/chat/{bot_id}/` | 单轮对话 |
| POST | `/multichat/` | 多轮对话 |

### 卡片模块 `/api/card/`
| 方法 | 路径 | 说明 |
|------|------|------|
| GET/POST | `/templates/` | 模板列表/创建 |
| GET/PUT/DELETE | `/templates/{id}/` | 模板详情/更新/删除 |
| POST | `/templates/{id}/publish/` | 发布模板 |
| POST | `/templates/{id}/archive/` | 归档模板 |
| GET/POST | `/cards/` | 卡片列表/创建 |
| POST | `/cards/scan/` | 扫描卡片（需认证） |
| POST | `/cards/scan_public/` | 扫描卡片（公开） |
| POST | `/cards/use/` | 使用卡片 |
| GET/POST | `/batches/` | 批次列表/创建 |
| POST | `/batches/generate/` | 批量生成卡片 |
| GET | `/batches/{id}/export/` | 导出批次 |
| POST | `/batches/{id}/mark_produced/` | 标记生产完成 |
| POST | `/batches/{id}/publish/` | 发布批次 |
| GET | `/category/{category}/` | 按分类查询模板 |
| GET | `/user/cards/` | 用户卡片列表 |

### 食物模块 `/api/food/`
| 方法 | 路径 | 说明 |
|------|------|------|
| GET/POST | `/foods/` | 食物列表/创建 |
| GET/PUT/PATCH/DELETE | `/foods/{id}/` | 食物详情/更新/删除 |
| GET | `/foods/categories/` | 食物分类信息 |
| POST | `/use-food/` | 使用食物 |
| GET | `/my-foods/` | 我的食物 |
| GET | `/user-foods/` | 用户食物列表 |
| GET | `/food-stats/` | 食物统计 |
| GET | `/usage-logs/` | 使用记录 |

### 成就模块 `/api/achievement/`
| 方法 | 路径 | 说明 |
|------|------|------|
| GET/POST | `/achievements/` | 成就列表/创建 |
| GET/PUT/DELETE | `/achievements/{id}/` | 成就详情/更新/删除 |
| GET | `/achievements/{id}/check_achievement/` | 检查成就 |
| GET/POST | `/user-achievements/` | 用户成就列表/授予 |
| POST | `/user-achievements/check_and_grant/` | 检查并授予 |
| GET | `/user-achievements/stats/` | 成就统计 |

### 设备模块 `/api/device/`
| 方法 | 路径 | 说明 |
|------|------|------|
| CRUD | `/device-types/` | 设备类型管理 |
| CRUD | `/device-batches/` | 设备批次管理 |
| CRUD | `/devices/` | 设备管理 |
| POST | `/devices/batch_create/` | 批量创建设备 |
| CRUD | `/user-devices/` | 用户设备绑定 |
| GET | `/messages/` | 消息列表 |
| POST | `/rtc-token/` | 获取 RTC Token |
| POST | `/send_message_to_user/{user_id}/` | WebSocket 发消息 |

### 通用 `/api/common/`
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/upload/` | 文件上传 |

---

## 七、开发优先级建议

### 高优先级（API 已有，仅需前端对接）
1. **舞蹈管理** — 前端 API 模块已写好，替换 mock 数据即可
2. **道具管理** — 同上
3. **家居装饰** — 同上
4. **成就系统** — 同上
5. **好感度系统** — 同上
6. **权限管理** — 同上
7. **手机登录/注册/忘记密码** — 前端 UI 已有，对接后端接口

### 中优先级（需要一定开发量）
8. **服装管理** — 前端页面结构需调整
9. **AI 模型管理** — 需要从展示页改为管理页
10. **仪表盘** — 需要后端开发统计接口
11. **设备管理** — 后端完整，需要开发前端页面

### 低优先级（需要较大开发量）
12. **系统设置** — 前后端都需要开发
13. **订阅管理** — 后端需要暴露 API，前端需要开发页面
14. **工作流系统** — 完全空白，需要完整设计