1

2025-11-24 13:23:42 +08:00
commit 5d7444cd65
156 changed files with 50653 additions and 0 deletions
--- a/api/controller_admin/README.md
+++ b/api/controller_admin/README.md
@@ -0,0 +1,321 @@
+# 后台管理 API 接口文档
+
+## 📋 接口概览
+
+本目录包含所有后台管理系统的 API 接口，每个业务模块对应一个控制器文件。
+
+### 🗂️ 控制器列表
+
+| 文件名 | 模块 | 路由前缀 | 说明 |
+|--------|------|----------|------|
+| `apply_records.js` | 投递记录管理 | `/admin_api/apply` | 投递记录的查询、统计、删除 |
+| `job_postings.js` | 岗位信息管理 | `/admin_api/job` | 岗位信息的查询、统计、删除 |
+| `pla_account.js` | 平台账号管理 | `/admin_api/account` | 平台账号的查询、更新、删除 |
+| `resume_info.js` | 简历信息管理 | `/admin_api/resume` | 简历信息的查询、统计、删除 |
+| `device_monitor.js` | 设备状态管理 | `/admin_api/device` | 设备状态的查询、监控、配置 |
+| `chat_records.js` | 聊天记录管理 | `/admin_api/chat` | 聊天记录的查询、统计、删除 |
+| `task_status.js` | 任务状态管理 | `/admin_api/task` | 任务状态的查询、更新、删除 |
+| `system_config.js` | 系统配置管理 | `/admin_api/config` | 系统配置的CRUD操作 |
+| `dashboard.js` | 数据统计面板 | `/admin_api/dashboard` | 综合数据统计 |
+| `sys_user.js` | 系统用户管理 | `/admin_api/user` | 用户管理 |
+
+---
+
+## 🔌 接口详情
+
+### 1️⃣ 投递记录管理 (`apply_records.js`)
+
+**路由前缀**: `/admin_api/apply`
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/list` | POST | 分页获取投递记录列表 |
+| `/statistics` | GET | 获取投递统计数据 |
+| `/detail` | GET | 获取投递记录详情 |
+| `/delete` | POST | 删除投递记录 |
+
+**主要功能**：
+- ✅ 按状态、反馈、面试、Offer 筛选
+- ✅ 支持搜索岗位名称/公司名称
+- ✅ 统计成功率、面试率、Offer率
+- ✅ 按平台和状态统计
+
+---
+
+### 2️⃣ 岗位信息管理 (`job_postings.js`)
+
+**路由前缀**: `/admin_api/job`
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/list` | POST | 分页获取岗位列表 |
+| `/statistics` | GET | 获取岗位统计数据 |
+| `/detail` | GET | 获取岗位详情 |
+| `/delete` | POST | 删除岗位信息 |
+
+**主要功能**：
+- ✅ 按平台、外包、薪资范围筛选
+- ✅ 支持搜索岗位名称/公司名称
+- ✅ AI 匹配度排序
+- ✅ 统计外包率、平均匹配度、薪资分布
+
+---
+
+### 3️⃣ 平台账号管理 (`pla_account.js`)
+
+**路由前缀**: `/admin_api/account`
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/list` | POST | 分页获取账号列表 |
+| `/statistics` | GET | 获取账号统计数据 |
+| `/detail` | GET | 获取账号详情 |
+| `/update` | POST | 更新账号信息 |
+| `/delete` | POST | 删除平台账号 |
+
+**主要功能**：
+- ✅ 按平台、激活状态筛选
+- ✅ 支持搜索账号/设备SN码
+- ✅ 统计激活率、平台分布
+- ✅ 更新 cookies/token
+
+---
+
+### 4️⃣ 简历信息管理 (`resume_info.js`)
+
+**路由前缀**: `/admin_api/resume`
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/list` | POST | 分页获取简历列表 |
+| `/statistics` | GET | 获取简历统计数据 |
+| `/detail` | GET | 获取简历详情 |
+| `/delete` | POST | 删除简历信息 |
+
+**主要功能**：
+- ✅ 按竞争力评分筛选
+- ✅ 支持搜索姓名/技能
+- ✅ 竞争力分布统计
+- ✅ 工作年限统计
+
+---
+
+### 5️⃣ 设备状态管理 (`device_monitor.js`)
+
+**路由前缀**: `/admin_api/device`
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/list` | POST | 分页获取设备列表 |
+| `/overview` | GET | 获取设备概览统计 |
+| `/update-config` | POST | 更新设备配置 |
+| `/reset-error` | POST | 重置设备错误 |
+| `/delete` | POST | 删除设备记录 |
+
+**主要功能**：
+- ✅ 按在线、健康状态筛选
+- ✅ 实时监控设备状态
+- ✅ 统计在线率、健康率
+- ✅ 最近离线设备列表
+
+---
+
+### 6️⃣ 聊天记录管理 (`chat_records.js`)
+
+**路由前缀**: `/admin_api/chat`
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/list` | POST | 分页获取聊天记录 |
+| `/statistics` | GET | 获取聊天统计数据 |
+| `/detail` | GET | 获取聊天详情 |
+| `/delete` | POST | 删除聊天记录 |
+
+**主要功能**：
+- ✅ 按类型、回复状态筛选
+- ✅ 支持搜索聊天内容
+- ✅ 统计回复率
+- ✅ 按类型和平台统计
+
+---
+
+### 7️⃣ 任务状态管理 (`task_status.js`)
+
+**路由前缀**: `/admin_api/task`
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/list` | POST | 分页获取任务列表 |
+| `/statistics` | GET | 获取任务统计数据 |
+| `/detail` | GET | 获取任务详情 |
+| `/update` | POST | 更新任务状态 |
+| `/delete` | POST | 删除任务记录 |
+
+**主要功能**：
+- ✅ 按类型、状态筛选
+- ✅ 支持搜索任务名称
+- ✅ 统计成功率
+- ✅ 按类型和状态统计
+
+---
+
+### 8️⃣ 系统配置管理 (`system_config.js`)
+
+**路由前缀**: `/admin_api/config`
+
+| 接口 | 方法 | 说明 |
+|------|------|------|
+| `/list` | POST | 分页获取配置列表 |
+| `/get` | GET | 获取配置详情 |
+| `/add` | POST | 添加配置 |
+| `/update` | POST | 更新配置 |
+| `/delete` | POST | 删除配置 |
+| `/categories` | GET | 获取配置分类 |
+| `/reset` | POST | 重置配置为默认值 |
+| `/batch-update` | POST | 批量更新配置 |
+
+**主要功能**：
+- ✅ 完整的 CRUD 操作
+- ✅ 支持多种配置类型（string/number/boolean/json）
+- ✅ 配置加密存储
+- ✅ 批量更新
+
+---
+
+## 📊 统一响应格式
+
+### 成功响应
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    // 响应数据
+  }
+}
+```
+
+### 错误响应
+```json
+{
+  "code": -1,
+  "message": "错误信息",
+  "data": null
+}
+```
+
+### 分页列表响应
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "total": 100,
+    "page": 1,
+    "pageSize": 20,
+    "list": [
+      // 数据列表
+    ]
+  }
+}
+```
+
+---
+
+## 🔍 通用查询参数
+
+所有 `POST /list` 接口都支持以下通用参数：
+
+| 参数 | 类型 | 说明 | 默认值 |
+|------|------|------|--------|
+| `page` | Integer | 页码 | 1 |
+| `pageSize` | Integer | 每页数量 | 20 |
+| `searchText` | String | 搜索关键词 | - |
+
+---
+
+## 🎯 接口特点
+
+### ✅ 已实现功能
+- 📋 **分页查询**：所有列表接口都支持分页
+- 🔍 **搜索过滤**：支持关键词搜索和多条件筛选
+- 📊 **统计分析**：每个模块都提供详细的统计数据
+- 🔐 **错误处理**：统一的错误处理和日志记录
+- 📝 **Swagger文档**：所有接口都有完整的 Swagger 注释
+
+### 🚀 接口亮点
+1. **统一规范**：所有接口遵循相同的命名和响应格式
+2. **丰富统计**：提供多维度的数据统计和分析
+3. **灵活查询**：支持多种筛选条件和排序方式
+4. **安全可靠**：完整的参数校验和错误处理
+
+---
+
+## 📝 使用示例
+
+### 获取投递记录列表
+```bash
+POST /admin_api/apply/list
+Content-Type: application/json
+
+{
+  "page": 1,
+  "pageSize": 20,
+  "applyStatus": "success",
+  "hasOffer": true,
+  "searchText": "前端"
+}
+```
+
+### 获取设备概览
+```bash
+GET /admin_api/device/overview
+```
+
+### 更新系统配置
+```bash
+POST /admin_api/config/update
+Content-Type: application/json
+
+{
+  "configKey": "ai.provider",
+  "configValue": "openai",
+  "description": "AI服务提供商"
+}
+```
+
+---
+
+## 🔗 相关文件
+
+- **前端页面**：`admin/src/views/` - 各模块的 Vue 页面
+- **API服务**：`admin/src/api/` - 前端 API 调用封装
+- **数据模型**：`api/model/` - 数据库表模型定义
+- **路由配置**：`admin/src/router/` - 前端路由配置
+
+---
+
+## 📌 注意事项
+
+1. **权限控制**：生产环境需要添加权限验证中间件
+2. **数据安全**：敏感信息（如密码、token）需要加密处理
+3. **性能优化**：大数据量查询需要添加索引和分页限制
+4. **日志记录**：所有操作都会记录日志便于追踪
+5. **错误处理**：统一使用 `ctx.success()` 和 `ctx.fail()` 方法
+
+---
+
+## 🎉 总结
+
+所有 8 个业务模块的后台管理接口已完整实现，涵盖：
+- ✅ 投递记录管理
+- ✅ 岗位信息管理
+- ✅ 平台账号管理
+- ✅ 简历信息管理
+- ✅ 设备状态管理
+- ✅ 聊天记录管理
+- ✅ 任务状态管理
+- ✅ 系统配置管理
+
+每个模块都提供了完整的 CRUD 操作和统计分析功能！🚀
+