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