# 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`