285 lines
6.2 KiB
Markdown
285 lines
6.2 KiB
Markdown
# AR01 — 后端架构
|
|
|
|
> 状态：当前有效
|
|
> 最后更新：2026-09-21
|
|
>
|
|
> 说明：
|
|
> 本文档描述当前后端的真实架构口径。
|
|
> 历史培训系统版本已归档至 `Historical_Records/AR01_后端架构-培训系统旧稿.md`。
|
|
|
|
---
|
|
|
|
## 1. 当前后端定位
|
|
|
|
当前后端定位为一个**对象目录与任务运行并列成立、以知识底座支撑、并兼容旧业务域的本地数字员工平台后端**。
|
|
|
|
当前统一主轴有三条：
|
|
|
|
1. **对象主轴**
|
|
- specialist
|
|
- skill
|
|
- xapp
|
|
- connector
|
|
- action
|
|
|
|
2. **运行主轴**
|
|
- task
|
|
- project
|
|
- task_run
|
|
- task_artifact
|
|
- specialist runtime
|
|
|
|
3. **支撑主轴**
|
|
- knowledge
|
|
- 权限与治理
|
|
|
|
培训、考试、产品知识、课程等能力当前继续在系统中运行，并作为兼容业务域存在。
|
|
|
|
## 2. 当前代码分层
|
|
|
|
后端当前主体位于：
|
|
|
|
`eai_agentplatform/backend-go/internal`
|
|
|
|
主要按“基础设施层 + 对象域 + 业务域”组织：
|
|
|
|
### 2.1 基础设施层
|
|
|
|
- `api`
|
|
- `auth`
|
|
- `middleware`
|
|
- `config`
|
|
- `store`
|
|
- `dal`
|
|
- `web`
|
|
- `ai`
|
|
|
|
职责：
|
|
|
|
- 路由注册
|
|
- 认证鉴权
|
|
- 配置装载
|
|
- 数据存取
|
|
- 统一响应与错误处理
|
|
- AI 调用支撑
|
|
|
|
### 2.2 对象域
|
|
|
|
- `specialists`
|
|
- `skills`
|
|
- `xapps`
|
|
- `connectors`
|
|
|
|
这几类目录已经体现出当前对象化拆分方向。
|
|
|
|
说明：
|
|
|
|
- 文档统一口径对外称 `App`
|
|
- 当前代码与表命名中仍保留 `xapp`
|
|
- 因此当前应理解为：`App = 代码中的 xapp 域`
|
|
- `xapp` 当前是一等对象和成品入口壳，但还不是运行主记录的主键
|
|
|
|
### 2.3 兼容业务域
|
|
|
|
当前后端仍保留以下运行中业务域：
|
|
|
|
- `company-train`
|
|
- `products`
|
|
- `courses`
|
|
- `exam`
|
|
- `knowledge`
|
|
- `media`
|
|
- `report`
|
|
- `document`
|
|
- `notes`
|
|
- `points`
|
|
|
|
这些目录构成当前平台的兼容业务面。
|
|
|
|
## 3. 当前路由骨架
|
|
|
|
当前路由注册集中在：
|
|
|
|
`backend-go/internal/api/router.go`
|
|
|
|
当前可以归纳为六类入口：
|
|
|
|
### 3.1 认证与系统入口
|
|
|
|
- `/api/auth/*`
|
|
- `/api/health`
|
|
|
|
### 3.2 对象目录入口
|
|
|
|
- `/api/specialists`
|
|
- `/api/skills`
|
|
- `/api/xapps`
|
|
- `/api/connectors`
|
|
- `/api/actions`
|
|
|
|
这是当前对象中心最明确的一层。
|
|
|
|
### 3.3 任务与项目入口
|
|
|
|
- `/api/tasks`
|
|
- `/api/my/tasks`
|
|
- `/api/projects`
|
|
- `/api/artifacts/:id`
|
|
- `/api/workbench/overview`
|
|
|
|
这是当前运行中心的主骨架。
|
|
|
|
### 3.4 知识与素材入口
|
|
|
|
- `/api/media/*`
|
|
- `/api/knowledge/*`
|
|
|
|
知识库当前仍是平台的组织级基础能力，不是外围附件。
|
|
|
|
### 3.5 AI 与技能执行入口
|
|
|
|
- `/api/ai-chat/*`
|
|
- `/api/chat/message`
|
|
- `/api/skills/office/*`
|
|
- `/api/report/*`
|
|
- `/api/document/*`
|
|
- `/api/contract/review`
|
|
- `/api/audio/transcribe`
|
|
|
|
这部分目前存在一定历史兼容痕迹，但总体都服务于任务、对象或知识底座。
|
|
|
|
### 3.6 兼容业务域入口
|
|
|
|
- `/api/company-train`
|
|
- `/api/products`
|
|
- `/api/courses`
|
|
- `/api/exam/*`
|
|
- `/api/points/*`
|
|
- `/api/my/profile`
|
|
|
|
这批接口说明平台仍处于“新主轴已形成，旧业务面仍在运行”的混合阶段。
|
|
|
|
## 4. 当前核心运行模型
|
|
|
|
后端当前的核心运行模型由以下三层组成：
|
|
|
|
### 4.1 对象定义层
|
|
|
|
- `specialist`
|
|
- `skill_definition`
|
|
- `xapp_definition`
|
|
- `action_definition`
|
|
|
|
这些对象定义的是：
|
|
|
|
- 谁能协作
|
|
- 能做什么
|
|
- 用户从哪里进入
|
|
- 哪些是可治理动作
|
|
|
|
这里需要特别区分：
|
|
|
|
- `specialist` 是当前运行时的主要执行人格对象
|
|
- `xapp` 是对象目录中的成品入口壳对象
|
|
- `skill` 是能力定义对象
|
|
- `action` 是动作定义与治理对象
|
|
|
|
### 4.2 任务运行层
|
|
|
|
- `task_record`
|
|
- `task_run`
|
|
- `task_artifact`
|
|
- `project`
|
|
|
|
这几张表承接的是：
|
|
|
|
- 一个工作实例
|
|
- 它的执行记录
|
|
- 它的输出物
|
|
- 它与项目容器的关系
|
|
|
|
当前运行层的关键事实是：
|
|
|
|
- `task_record` 当前以 `specialist_key` 作为主要执行挂载点
|
|
- `project` 是任务容器，不是执行主语
|
|
- `xapp` 当前不直接作为运行主键进入这条链
|
|
|
|
### 4.3 知识底座层
|
|
|
|
- `knowledge_space`
|
|
- `knowledge_source`
|
|
- `knowledge_chunk`
|
|
- `knowledge_faq`
|
|
- `media_file`
|
|
|
|
这层负责：
|
|
|
|
- 组织知识沉淀
|
|
- 素材接入
|
|
- 文本切片
|
|
- 检索支撑
|
|
- 审批前置
|
|
|
|
## 5. 当前对象口径与代码现实
|
|
|
|
当前文档层口径已经收敛为：
|
|
|
|
- 专家
|
|
- 技能
|
|
- App
|
|
- 连接器
|
|
|
|
但代码现实仍有两个过渡痕迹：
|
|
|
|
1. `specialist` 仍作为专家对象的实现命名存在
|
|
2. `xapp` 仍作为 App 对象的实现命名存在
|
|
|
|
因此当前后端应采用以下理解方式：
|
|
|
|
- `专家 = specialist`
|
|
- `App = xapp`
|
|
|
|
同时还要补上一条运行边界：
|
|
|
|
- `当前运行主语 = specialist-driven task`
|
|
- `当前入口壳对象 = xapp`
|
|
|
|
这是当前代码命名、对象口径和运行现实之间最重要的映射关系。
|
|
|
|
## 6. 当前架构判断
|
|
|
|
### 6.1 已经符合当前方向的部分
|
|
|
|
- 对象域已独立成目录
|
|
- 路由已有对象入口
|
|
- 任务/项目已形成运行主轴
|
|
- specialist 已成为当前任务运行的主要执行主语
|
|
- 知识库仍作为底座能力存在
|
|
- 后台治理与对象治理已进入统一后端
|
|
|
|
### 6.2 仍未完全收口的部分
|
|
|
|
- 培训、考试、课程、产品等旧业务域仍在主路由中并行存在
|
|
- `ai-chat`、`chat/message` 两套对话入口仍并存
|
|
- 对象命名在文档与代码之间仍有 `专家/specialist`、`App/xapp` 过渡
|
|
- `xapp` 已完成对象化，但尚未成为 task runtime 的主键级对象
|
|
|
|
## 7. 当前后端设计原则
|
|
|
|
后续后端整理应继续遵守以下原则：
|
|
|
|
1. 任务是运行中心，当前执行主语是 specialist
|
|
2. 对象定义与对象运行要继续解耦
|
|
3. `xapp` 继续作为成品入口壳演进，但不能提前写成当前运行主键
|
|
4. 培训/考试等业务域优先向 `App + task` 结构收敛
|
|
5. 新增能力优先进入 `specialists / skills / xapps / connectors` 对象域，而不是继续扩张旧业务模块
|
|
6. 历史兼容接口可以保留，但不能再主导新的架构描述
|
|
|
|
## 8. 建议阅读
|
|
|
|
1. `docs/01_System_Overall/SY21_统一角色技能动作架构.md`
|
|
2. `docs/01_System_Overall/SY22_角色技能应用统一任务架构.md`
|
|
3. `docs/02_Architecture/AR02_前端架构.md`
|
|
4. `docs/02_Architecture/AR03_数据库架构.md`
|
|
5. `docs/04_Backend/01_平台治理底座/BG01_后端总体分层与路由总表.md`
|