# eai_agentplatform_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": "eai_agentplatform-app",
  "version": "1.1.0"
}
```