pj0235-eai_agentplatform/docs/04_Backend/01_平台治理底座/BG01_后端总体分层与路由总表.md

BG01 — 后端总体分层与路由总表

状态：当前有效 协议：HTTP / JSON 认证：JWT Bearer 代码依据：backend-go/internal/api/router.go 最后更新：2026-09-21

1. 当前后端分层

当前后端按五层理解最准确：

1. 平台治理底座
2. 对象中心
3. 运行中心
4. 知识底座
5. 兼容业务域

2. 当前主要路由分组

分层	主要路由	当前作用
平台治理底座	/api/auth/*、/api/system/*、/api/ai/*	登录鉴权、管理员治理、AI 路由与审计
对象中心	/api/specialists、/api/skills、/api/xapps、/api/actions、/api/connectors	specialist / skill / xapp / action / connector 定义入口
运行中心	/api/workbench/*、/api/my/tasks、/api/tasks、/api/projects、/api/chat/message	task / project / Workbench / 对话执行
知识底座	/api/knowledge/*、/api/media/*	知识空间、知识源、FAQ、素材与审批
兼容业务域	/api/company-train、/api/products、/api/courses、/api/exam/*	培训、考试、产品、课程等兼容场景

3. 当前对象与运行关系

当前后端核心关系可以压缩成一句话：

平台底座 -> 承载对象中心 -> 由 task / project 形成运行容器 -> 由 knowledge 提供底座支撑 -> 兼容业务域通过 xapp 和业务接口继续运行

4. 当前总判断

• xapp 是对象中心的一等对象
• task / project 是当前运行容器
• /api/chat/message 是当前 Workbench 主对话入口
• training / exam 当前属于兼容业务域，不承担后端主轴解释职责 | POST | /api/exam/submit | 提交考试 | | GET | /api/exam/record | 我的考试记录 | | GET | /api/exam/record/:record_id | 考试记录详情 | | GET | /api/exam/mistakes | 错题本 | | PUT | /api/exam/mistakes/:id/resolve | 标记错题已掌握 | | POST | /api/exam/mistakes/practice | 错题练习 | | GET | /api/exam/certificates | 我的证书 | | GET | /api/exam/certificates/:id | 证书详情 |

7.3 学习与积分

方法	路径	说明
POST	/api/learning/progress	上报学习进度
GET	/api/learning/me	我的学习进度
GET	/api/my/position	我的岗位
GET	/api/my/profile	我的资料
GET	/api/points/me	我的积分
GET	/api/points/leaderboard	积分排行榜
GET	/api/notes	学习笔记列表
POST	/api/notes	创建学习笔记
PUT	/api/notes/:id	更新学习笔记
DELETE	/api/notes/:id	删除学习笔记

---

8. 管理员治理接口

8.1 对象治理

方法	路径	说明
POST	/api/specialists	创建专家
PUT	/api/specialists/:id	更新专家
DELETE	/api/specialists/:id	删除专家
POST	/api/skills	创建技能
PUT	/api/skills/:id	更新技能
DELETE	/api/skills/:id	删除技能
POST	/api/xapps	创建 App
PUT	/api/xapps/:id	更新 App
DELETE	/api/xapps/:id	删除 App
POST	/api/actions	创建 Action
PUT	/api/actions/:id	更新 Action
DELETE	/api/actions/:id	删除 Action

8.2 任务与工件治理

方法	路径	说明
POST	/api/tasks	创建任务
PUT	/api/tasks/:id	更新任务
PUT	/api/tasks/:id/status	更新任务状态
DELETE	/api/tasks/:id	删除任务
POST	/api/tasks/:id/actions	执行任务动作
PUT	/api/artifacts/:id/status	更新交付物状态

8.3 组织治理

方法	路径	说明
GET	/api/departments	部门列表
POST	/api/departments	创建部门
PUT	/api/departments/:id	更新部门
DELETE	/api/departments/:id	删除部门
GET	/api/positions	岗位列表
POST	/api/positions	创建岗位
PUT	/api/positions/:id	更新岗位
DELETE	/api/positions/:id	删除岗位
GET	/api/positions/:id/knowledge	岗位知识要求
PUT	/api/positions/:id/knowledge	保存岗位知识要求
GET	/api/positions/:id/blueprint	岗位考试蓝图
PUT	/api/positions/:id/blueprint	保存岗位考试蓝图
PUT	/api/users/:id/position	设置用户岗位

8.4 系统治理

方法	路径	说明
GET	/api/system/users	用户列表
POST	/api/system/users	创建用户
PUT	/api/system/users/:id	更新用户
GET	/api/system/users/:id/overview	用户概览
GET	/api/system/exam-records	全部考试记录
GET	/api/system/exam-records/export	导出考试记录
GET	/api/system/exam-records/:id	考试记录详情
DELETE	/api/system/exam-records/:id	删除考试记录
GET	/api/system/dashboard	系统看板
GET	/api/system/exam-stats	考试统计
GET	/api/system/exam-stats-by-position	按岗位考试统计
GET	/api/system/department-stats	部门统计
GET	/api/system/certificates	证书统计
GET	/api/system/exam-coverage	考试覆盖统计
GET	/api/system/learning-progress	学习进度统计
GET	/api/system/config	系统配置
PUT	/api/system/config	更新系统配置

8.5 AI 配置治理

方法	路径	说明
GET	/api/ai/config	获取 AI 配置
PUT	/api/ai/config	保存 AI 配置
POST	/api/ai/reload	热重载 AI 配置
GET	/api/ai/secrets-status	AI 密钥状态
GET	/api/ai/usage/users	按用户查看 AI 用量

---

9. 当前口径说明

• 当前主前门是 POST /api/chat/message
• /api/ai-chat/* 继续保留，属于兼容对话入口
• 产品、课程、考试、公司介绍仍在运行，但已经不构成后端唯一主轴
• 当前后端真正的中心是：对象定义 + 任务运行 + 知识底座 + 兼容业务域