EaiLab/pj0235-eai_agentplatform
11
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b00e55f0e5b30b6a0055a639a11816ec612bc06d
pj0235-eai_agentplatform/docs/api.md
T
eaiadmin 4e8817d768 init: 数字员工平台初始代码 
包含前端（Vue3 + VueFlow 画布）、后端（Go）、文档体系。
- 工作台画布：节点拖放、连线模式、右键菜单、AI 助手
- 后端：连接器 API、专员种子数据
- 导航：左侧导航、工坊、市场、控制台
2026-08-18 20:19:58 +08:00

11 KiB
Raw Blame History

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>

响应格式

{
  "data": { ... },
  "error": null,
  "message": "success"
}

错误响应：

{
  "data": null,
  "error": "error_code",
  "message": "人类可读的错误描述"
}

HTTP 状态码

状态码 含义
200 成功
201 创建成功
400 请求参数错误
401 未认证 / token 无效
403 无权限（非管理员访问管理接口）
404 资源不存在
409 资源冲突（如用户名重复）
500 服务器内部错误

1. 认证 API

POST /api/auth/login

描述： 登录获取 JWT Token

请求体：

{
  "username": "string",
  "password": "string"
}

响应：

{
  "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

描述： 获取公司介绍内容 认证： 必需

响应：

{
  "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 角色

请求体：

{
  "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 角色

请求体：

{
  "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

描述： 开始考试，下发题目 认证： 必需

请求体：

{
  "paper_id": 1
}

响应：

{
  "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

描述： 交卷判分 认证： 必需

请求体：

{
  "session_id": "exam-uuid",
  "answers": {"1": "D", "2": ["A","B"], "3": "true"},
  "time_spent_sec": 1200
}

响应（正式考试）：

{
  "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） 认证： 必需

请求体：

{
  "filename": "training.mp4",
  "file_size": 524288000,
  "bind_type": "course",
  "bind_id": 1
}

响应：

{
  "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

描述： 完成分片上传，合并文件 认证： 必需

请求体：

{
  "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 角色

请求体：

{
  "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 角色

响应：

{
  "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 角色

请求体：

{
  "action": "approve",
  "reject_reason": "内容不符合要求（驳回时必填）"
}

响应（approve）：

{
  "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 认证： 必需

请求体：

{
  "message": "请介绍一下资本咨询类产品",
  "context": {
    "product_id": 1,
    "page": "product_detail"
  }
}

响应（SSE 流式）：

data: {"type": "text", "content": "资本咨询类产品主要包括..."}
data: {"type": "done"}

GET /api/ai-chat/quick-actions

描述： 获取快捷按钮列表 认证： 必需

响应：

{
  "data": {
    "actions": [
      {"id": "scenario", "label": "客户情景演练"},
      {"id": "commission", "label": "查询佣金/规则"},
      {"id": "compare", "label": "产品对比"}
    ]
  }
}

POST /api/ai-chat/quick-action

描述： 触发快捷动作 认证： 必需

请求体：

{
  "action_id": "commission",
  "params": {"product_code": "ZQ-001"}
}

10. 系统管理 API（管理员）

10.1 用户管理

GET /api/system/users

描述： 用户列表 认证： 需 admin 角色

POST /api/system/users

描述： 创建用户 认证： 需 admin 角色

请求体：

{
  "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 角色

请求体：

{
  "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

描述： 服务健康检查 认证： 不需要 响应：

{
  "status": "ok",
  "service": "eaisalestrain-app",
  "version": "1.1.0"
}
Reference in New Issue View Git Blame Copy Permalink