pj0235-eai_agentplatform/docs/02_Architecture/AR01_后端架构.md

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