eaiadmin
4e8817d768
包含前端（Vue3 + VueFlow 画布）、后端（Go）、文档体系。 - 工作台画布：节点拖放、连线模式、右键菜单、AI 助手 - 后端：连接器 API、专员种子数据 - 导航：左侧导航、工坊、市场、控制台
576 lines
11 KiB
Markdown
576 lines
11 KiB
Markdown
# eaisalestrain_app — API 文档
|
||
|
||
> **版本：V1.1 | 协议：HTTP/JSON | 认证：JWT Bearer**
|
||
> **最后更新：2026-08-15**
|
||
>
|
||
> **⚠️ 本文档为 V1.1 设计期基线，后端已重写为 Go + Gin（见 docs/changelog.md V1.2）。** V1.4–V1.7 新增的岗位（`/api/positions`）、部门（`/api/departments`）、消息（`/api/notifications`）、积分（`/api/points`）、证书（`/api/exam/certificates`）、错题本（`/api/exam/mistakes`）、学习档案（`/api/my/profile`）等接口未收录于本文档，以 `docs/changelog.md` 为准。
|
||
|
||
---
|
||
|
||
## 通用约定
|
||
|
||
### 认证方式
|
||
所有 API（除 login 外）需在请求头携带：`Authorization: Bearer <token>`
|
||
|
||
### 响应格式
|
||
```json
|
||
{
|
||
"data": { ... },
|
||
"error": null,
|
||
"message": "success"
|
||
}
|
||
```
|
||
|
||
错误响应：
|
||
```json
|
||
{
|
||
"data": null,
|
||
"error": "error_code",
|
||
"message": "人类可读的错误描述"
|
||
}
|
||
```
|
||
|
||
### HTTP 状态码
|
||
| 状态码 | 含义 |
|
||
|--------|------|
|
||
| 200 | 成功 |
|
||
| 201 | 创建成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未认证 / token 无效 |
|
||
| 403 | 无权限（非管理员访问管理接口） |
|
||
| 404 | 资源不存在 |
|
||
| 409 | 资源冲突（如用户名重复） |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 1. 认证 API
|
||
|
||
### `POST /api/auth/login`
|
||
**描述：** 登录获取 JWT Token
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"username": "string",
|
||
"password": "string"
|
||
}
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"data": {
|
||
"token": "string",
|
||
"expires_in": 28800,
|
||
"user": {
|
||
"id": 1,
|
||
"username": "string",
|
||
"full_name": "string",
|
||
"role": "employee"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### `GET /api/auth/me`
|
||
**描述：** 获取当前登录用户信息
|
||
**认证：** 必需
|
||
|
||
---
|
||
|
||
## 2. 公司介绍培训 API
|
||
|
||
### `GET /api/company-train`
|
||
**描述：** 获取公司介绍内容
|
||
**认证：** 必需
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"data": {
|
||
"content": "公司简介HTML/文本",
|
||
"medias": [
|
||
{
|
||
"id": 1,
|
||
"filename": "公司介绍.pptx",
|
||
"file_ext": "pptx",
|
||
"preview_url": "/api/media/preview/1"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### `POST /api/company-train/suggest-material`
|
||
**描述：** 员工提交素材建议（弹窗）
|
||
**认证：** 必需
|
||
|
||
**请求体：** `multipart/form-data`
|
||
- `file`: 文件
|
||
- `remark`: 备注说明（可选）
|
||
|
||
---
|
||
|
||
## 3. 产品知识 API
|
||
|
||
### `GET /api/products`
|
||
**描述：** 获取产品列表
|
||
**参数：** `?category=capital_consulting`（可选，按分类筛选）
|
||
**认证：** 必需
|
||
|
||
### `GET /api/products/{id}`
|
||
**描述：** 获取产品详情
|
||
**认证：** 必需
|
||
|
||
### `POST /api/products` （管理员）
|
||
**描述：** 新增产品
|
||
**认证：** 需 admin 角色
|
||
|
||
### `PUT /api/products/{id}` （管理员）
|
||
**描述：** 编辑产品
|
||
|
||
### `DELETE /api/products/{id}` （管理员）
|
||
**描述：** 停用产品（软删除）
|
||
|
||
### `POST /api/products/import` （管理员）
|
||
**描述：** 批量导入产品（Excel / JSON）
|
||
|
||
---
|
||
|
||
## 4. 销售培训 API
|
||
|
||
### `GET /api/courses`
|
||
**描述：** 获取课程列表
|
||
**参数：** `?category=capital_script`（可选）
|
||
**认证：** 必需
|
||
|
||
### `GET /api/courses/{id}`
|
||
**描述：** 获取课程详情（含绑定产品信息）
|
||
**认证：** 必需
|
||
|
||
### `POST /api/courses` （管理员）
|
||
**描述：** 新增课程
|
||
**认证：** 需 admin 角色
|
||
|
||
### `PUT /api/courses/{id}` （管理员）
|
||
**描述：** 编辑课程，绑定/解绑产品
|
||
|
||
---
|
||
|
||
## 5. 考试 API
|
||
|
||
### 5.1 题库管理（管理员）
|
||
|
||
#### `GET /api/exam/questions`
|
||
**描述：** 题目列表
|
||
**参数：** `?domain=company&status=active`
|
||
**认证：** 需 admin 角色
|
||
|
||
#### `POST /api/exam/questions`
|
||
**描述：** 新增题目
|
||
**认证：** 需 admin 角色
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"domain": "company",
|
||
"course_id": null,
|
||
"type": "single",
|
||
"stem": "博昇的主营业务包括？",
|
||
"options": [
|
||
{"key": "A", "text": "资本咨询"},
|
||
{"key": "B", "text": "AI产业落地"},
|
||
{"key": "C", "text": "房地产开发"},
|
||
{"key": "D", "text": "以上都是"}
|
||
],
|
||
"answer": ["D"],
|
||
"explanation": "博昇双主营业务为资本咨询与AI产业落地"
|
||
}
|
||
```
|
||
|
||
#### `PUT /api/exam/questions/{id}`
|
||
**描述：** 编辑题目
|
||
|
||
#### `DELETE /api/exam/questions/{id}`
|
||
**描述：** 停用题目
|
||
|
||
### 5.2 考试配置（管理员）
|
||
|
||
#### `GET /api/exam/papers`
|
||
**描述：** 考试配置列表
|
||
|
||
#### `POST /api/exam/papers`
|
||
**描述：** 创建考试配置
|
||
**认证：** 需 admin 角色
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"name": "公司介绍正式考试",
|
||
"type": "formal",
|
||
"domain": "company",
|
||
"question_count": 20,
|
||
"total_score": 100,
|
||
"pass_score": 60,
|
||
"duration_minutes": 30,
|
||
"randomize": true
|
||
}
|
||
```
|
||
|
||
### 5.3 学员端考试
|
||
|
||
#### `GET /api/exam/list`
|
||
**描述：** 我的考试列表（所有可用考试 + 状态）
|
||
**认证：** 必需
|
||
|
||
#### `GET /api/exam/cover?id={paperId}`
|
||
**描述：** 考试封面/说明
|
||
**认证：** 必需
|
||
|
||
#### `POST /api/exam/start`
|
||
**描述：** 开始考试，下发题目
|
||
**认证：** 必需
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"paper_id": 1
|
||
}
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"data": {
|
||
"session_id": "exam-uuid",
|
||
"exam_name": "公司介绍正式考试",
|
||
"time_limit_min": 30,
|
||
"questions": [
|
||
{
|
||
"id": 1,
|
||
"order": 1,
|
||
"type": "single",
|
||
"stem": "博昇的主营业务包括？",
|
||
"options": [
|
||
{"key": "A", "text": "资本咨询"},
|
||
{"key": "B", "text": "AI产业落地"}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### `POST /api/exam/submit`
|
||
**描述：** 交卷判分
|
||
**认证：** 必需
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"session_id": "exam-uuid",
|
||
"answers": {"1": "D", "2": ["A","B"], "3": "true"},
|
||
"time_spent_sec": 1200
|
||
}
|
||
```
|
||
|
||
**响应（正式考试）：**
|
||
```json
|
||
{
|
||
"data": {
|
||
"session_id": "exam-uuid",
|
||
"exam_name": "公司介绍正式考试",
|
||
"score": 85,
|
||
"total_score": 100,
|
||
"pass_score": 60,
|
||
"passed": true,
|
||
"correct_count": 17,
|
||
"wrong_count": 3,
|
||
"detail": [
|
||
{"question_id": 1, "is_correct": true, "user_answer": "D", "correct_answer": "D"}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应（自测）：** 同上，但不会持久化到 exam_record
|
||
|
||
#### `GET /api/exam/record`
|
||
**描述：** 我的考试记录列表
|
||
**认证：** 必需（员工仅自己，管理员可看全部）
|
||
**参数：** `?page=1&size=20`
|
||
|
||
#### `GET /api/exam/record/{recordId}`
|
||
**描述：** 考试记录详情（答题明细回溯）
|
||
**认证：** 必需
|
||
|
||
---
|
||
|
||
## 6. 素材/媒体 API
|
||
|
||
### `POST /api/media/upload`
|
||
**描述：** 上传文件（文档 ≤ 200MB 直传）
|
||
**认证：** 必需
|
||
|
||
**请求体：** `multipart/form-data`
|
||
- `file`: 文件
|
||
- `bind_type`: company / product / course / none
|
||
- `bind_id`: 绑定实体 ID（可选）
|
||
|
||
### `POST /api/media/upload-init`
|
||
**描述：** 初始化分片上传（视频 > 100MB）
|
||
**认证：** 必需
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"filename": "training.mp4",
|
||
"file_size": 524288000,
|
||
"bind_type": "course",
|
||
"bind_id": 1
|
||
}
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"data": {
|
||
"upload_id": "uuid",
|
||
"chunk_size": 5242880,
|
||
"chunk_count": 100
|
||
}
|
||
}
|
||
```
|
||
|
||
### `POST /api/media/upload-chunk`
|
||
**描述：** 上传分片
|
||
**认证：** 必需
|
||
|
||
**请求体：** `multipart/form-data`
|
||
- `upload_id`: 上传会话 ID
|
||
- `chunk_index`: 分片序号（从 0 开始）
|
||
- `file`: 分片二进制
|
||
|
||
### `POST /api/media/upload-complete`
|
||
**描述：** 完成分片上传，合并文件
|
||
**认证：** 必需
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"upload_id": "uuid"
|
||
}
|
||
```
|
||
|
||
### `GET /api/media/preview/{mediaId}`
|
||
**描述：** 获取预览 URL / 信息（仅 approved 素材）
|
||
**认证：** 必需
|
||
|
||
### `GET /api/media/status/{mediaId}`
|
||
**描述：** 查询素材状态（含提取进度）
|
||
**认证：** 必需
|
||
|
||
---
|
||
|
||
## 7. 素材审批 API（管理员）
|
||
|
||
### `GET /api/media/audit-list`
|
||
**描述：** 待审批素材列表
|
||
**参数：** `?status=pending&page=1&size=20`
|
||
**认证：** 需 admin 角色
|
||
|
||
### `POST /api/media/audit/{mediaId}`
|
||
**描述：** 审批素材
|
||
**认证：** 需 admin 角色
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"action": "approve",
|
||
"reject_reason": "内容不符合要求（驳回时必填）"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 知识源入库 API（管理员）
|
||
|
||
> 结构化知识源（`docs/knowledge_source/*.md`）的扫描、审批、摄入。完整设计见 `04_Backend/BE05_Knowledge_Ingest_Module.md`。
|
||
|
||
### `POST /api/knowledge/scan`
|
||
**描述：** 扫描 knowledge_source 目录，为新增/变更的 md 建 pending 记录
|
||
**认证：** 需 admin 角色
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"data": {
|
||
"results": [
|
||
{"file_path": "02_资本咨询类.md", "status": "created", "title": "资本咨询类（表1）"}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### `GET /api/knowledge/audit-list`
|
||
**描述：** 知识源审批列表
|
||
**参数：** `?status=pending&page=1&size=20`
|
||
**认证：** 需 admin 角色
|
||
|
||
### `POST /api/knowledge/audit/{sourceId}`
|
||
**描述：** 审批知识源（approve → 同步摄入 product/question/chunk；reject → 必填理由）
|
||
**认证：** 需 admin 角色
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"action": "approve",
|
||
"reject_reason": "内容不符合要求（驳回时必填）"
|
||
}
|
||
```
|
||
|
||
**响应（approve）：**
|
||
```json
|
||
{
|
||
"data": {
|
||
"status": "approved",
|
||
"source_id": 1,
|
||
"products": 3,
|
||
"chunks": 3,
|
||
"questions": 4
|
||
}
|
||
}
|
||
```
|
||
|
||
### `GET /api/knowledge/status/{sourceId}`
|
||
**描述：** 查询知识源审批/摄入状态
|
||
**认证：** 必需
|
||
|
||
---
|
||
|
||
## 9. AI PathCoach API
|
||
|
||
### `POST /api/ai-chat/message`
|
||
**描述：** 发送消息给 AI PathCoach
|
||
**认证：** 必需
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"message": "请介绍一下资本咨询类产品",
|
||
"context": {
|
||
"product_id": 1,
|
||
"page": "product_detail"
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应（SSE 流式）：**
|
||
```
|
||
data: {"type": "text", "content": "资本咨询类产品主要包括..."}
|
||
data: {"type": "done"}
|
||
```
|
||
|
||
### `GET /api/ai-chat/quick-actions`
|
||
**描述：** 获取快捷按钮列表
|
||
**认证：** 必需
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"data": {
|
||
"actions": [
|
||
{"id": "scenario", "label": "客户情景演练"},
|
||
{"id": "commission", "label": "查询佣金/规则"},
|
||
{"id": "compare", "label": "产品对比"}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### `POST /api/ai-chat/quick-action`
|
||
**描述：** 触发快捷动作
|
||
**认证：** 必需
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"action_id": "commission",
|
||
"params": {"product_code": "ZQ-001"}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 系统管理 API（管理员）
|
||
|
||
### 10.1 用户管理
|
||
|
||
#### `GET /api/system/users`
|
||
**描述：** 用户列表
|
||
**认证：** 需 admin 角色
|
||
|
||
#### `POST /api/system/users`
|
||
**描述：** 创建用户
|
||
**认证：** 需 admin 角色
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"username": "zhangsan",
|
||
"password": "初始密码",
|
||
"full_name": "张三",
|
||
"role": "employee"
|
||
}
|
||
```
|
||
|
||
#### `PUT /api/system/users/{id}`
|
||
**描述：** 编辑用户（可禁用、改角色）
|
||
|
||
### 10.2 考试成绩管理
|
||
|
||
#### `GET /api/system/exam-records`
|
||
**描述：** 全部考试成绩（支持按用户/考试筛选）
|
||
**认证：** 需 admin 角色
|
||
|
||
#### `GET /api/system/exam-records/{id}`
|
||
**描述：** 考试记录详情
|
||
|
||
### 10.3 系统参数配置
|
||
|
||
#### `GET /api/system/config`
|
||
**描述：** 获取所有系统参数
|
||
**认证：** 需 admin 角色
|
||
|
||
#### `PUT /api/system/config`
|
||
**描述：** 更新系统参数
|
||
**认证：** 需 admin 角色
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"configs": {
|
||
"llm_base_url": "http://192.168.1.100:11434/v1",
|
||
"llm_api_key": "sk-xxx",
|
||
"llm_model": "qwen2.5:7b",
|
||
"jwt_expire_minutes": 480
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 11. 健康检查
|
||
|
||
### `GET /api/health`
|
||
**描述：** 服务健康检查
|
||
**认证：** 不需要
|
||
**响应：**
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"service": "eaisalestrain-app",
|
||
"version": "1.1.0"
|
||
}
|
||
``` |