docs: 重构仓库文档目录并迁移训练素材
按当前架构重组 docs 目录,统一中文命名与目录分层,并将训练原材料迁移到独立目录以保持架构文档边界清晰。
This commit is contained in:
@@ -0,0 +1,154 @@
|
||||
# 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/*` 继续保留,属于兼容对话入口
|
||||
- 产品、课程、考试、公司介绍仍在运行,但已经不构成后端唯一主轴
|
||||
- 当前后端真正的中心是:**对象定义 + 任务运行 + 知识底座 + 兼容业务域**
|
||||
Reference in New Issue
Block a user