docs: 重构仓库文档目录并迁移训练素材
按当前架构重组 docs 目录，统一中文命名与目录分层，并将训练原材料迁移到独立目录以保持架构文档边界清晰。
This commit is contained in:
eaiadmin
@@ -0,0 +1,284 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user