autoAiWorkSys/api/controller_admin/README.md

# 后台管理 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` | 任务状态的查询、更新、删除 |
| `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 | 删除任务记录 |

**主要功能**：
- ✅ 按类型、状态筛选
- ✅ 支持搜索任务名称
- ✅ 统计成功率
- ✅ 按类型和状态统计

---
- ✅ 批量更新

---

## 📊 统一响应格式

### 成功响应
```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 操作和统计分析功能！🚀