common_agent/docs/模块完成度审计.md

# Common Agent Studio 模块完成度审计

## 1. 审计范围

本次审计以当前仓库最新状态为准，核对以下资料与实现是否一致：

- `docs/需求分析/*`
- `docs/设计文档/*`
- `docs/数据库设计/*`
- `docs/后端实现文档/*`
- `docs/前端实现文档/*`
- `script/sql/*.sql`

审计目标不是重复设计方案，而是确认当前代码、接口、测试与文档约束之间的对应关系，并标记仍需持续关注的风险点。

## 2. 总体结论

- Maven 多模块单体骨架已落地，根 `pom.xml` 已拆分 `common-agent-boot`、`common-agent-common`、`common-agent-rag`、`common-agent-modelprovider`、`common-agent-agent`、`common-agent-workflow`、`common-agent-mcp`、`common-agent-skill`、`common-agent-observability`。
- 后端已按业务域拆分模块，每个业务模块均已形成 `controller / service / service/impl / mapper / entity / dto / vo / factory` 主体结构。
- `sys_enum`、整型枚举协议、`PersistableSysEnumDefinition` 契约、`BaseEntity` 审计习惯均保持不变。
- 前端 Studio 九个工作台页面均已对接真实 API，API 层与页面单测已覆盖主要聚合接口。
- 旧管理接口继续兼容；Studio 原型新增聚合接口用于支撑工作台页面，不替代低层 CRUD 接口。

## 2.1 目标逐条验收矩阵

以下矩阵直接对照本次目标中的显式要求，标记当前证据状态：

| 验收项 | 当前状态 | 主要证据 |
|--------|----------|----------|
| 以 `docs/需求分析`、`docs/设计文档`、`docs/数据库设计`、`docs/后端实现文档`、`docs/前端实现文档` 为实现依据 | 已核对 | 本文档第 1 节与模块核对章节；`docs/数据库设计/9.模块一致性校验.md` |
| 后端为 Maven 多模块单体架构 | 已实现 | 根 `pom.xml` 的 9 个子模块；`common-agent-boot` 作为启动模块 |
| 模块按业务域拆分，而不是按技术类型散落 | 已实现 | `common-agent-common`、`rag`、`modelprovider`、`agent`、`workflow`、`mcp`、`skill`、`observability` 子模块 |
| `sys_enum` 设计与整型枚举协议保持不变 | 已实现 | `script/sql/1.enum.sql`、`script/sql/18.studio_enum.sql`、`PersistableSysEnumDefinition`、`EnumDefinitionTests` |
| Entity 与 SQL 表结构一致 | 已强验证 | `SqlEntityMappingContractTests` + `docs/数据库设计/9.模块一致性校验.md` |
| Controller 不直接暴露 Entity，统一 DTO/VO/RequestResult | 已实现 | 各模块控制器签名；controller/component 测试 |
| Factory/Assembler 承担 DTO/Entity/VO 转换 | 已实现 | 各模块 `factory` 包与 `*FactoryTests` |
| Service 承担业务逻辑、状态流转、校验 | 已实现 | 各模块 `service/impl` 与 `*ServiceTests` |
| Mapper 使用 MyBatis-Plus，数据访问与脚本命名一致 | 基本实现，证据中等 | `BaseMapper` 结构测试 + SQL/Entity 契约测试；真实 DB 读写集成仍偏少 |
| 核心流程补中文注释与中文业务日志 | 基本实现，证据中等 | `1d401c68` 提交 + 关键控制器/服务实现；未做全仓逐文件注释覆盖率检测 |
| 每模块补测试并运行 | 已实现 | 当前后端测试文件 68 个；前端 API/页面测试 25 个；多轮 reactor/vitest/build 验证 |
| 前端 Studio 页面与真实 API 对接 | 已实现 | 9 个工作台页面、16 个 API 单测、9 个页面单测、`npm run build` 通过 |
| 旧接口兼容且新增聚合接口支撑工作台 | 已实现 | RAG/Agent/Workflow/MCP/Skill 文档草案兼容路径与聚合接口 |
| 输出模块完成总结、测试结果、本地提交 | 已持续执行 | 最近提交记录：`c8245ba0`、`73237507`、`d5d239ae` 等 |

说明：

- 上表中“基本实现，证据中等”的项目，不表示发现功能缺失，而是提示当前最强证据还不如“脚本/实体一致性”那样直接。
- 目前最薄弱的仍是“真实数据库读写集成测试”和“全仓中文日志/注释覆盖率的自动化证明”。

## 3. 模块核对

### 3.1 common

已核对内容：

- 实体与 SQL 对应：
  - `sys_enum` -> `common-agent-common/src/main/java/com/bruce/common/domain/entity/SysEnum.java`
  - `sys_attachment` -> `common-agent-common/src/main/java/com/bruce/common/domain/entity/SysAttachment.java`
- 基础模型：
  - `BaseEntity`、`RequestResult<T>`、全局异常、审计配置均位于 `com.bruce.common`
- 接口：
  - `POST /api/sys-enum/list`
  - `POST /api/sys-enum/query`
  - `POST /api/sys-enum/queryForManagement`
  - `GET /api/sys-enum/detail`
  - `POST /api/sys-enum/save`
  - `POST /api/sys-enum/batchSave`
  - `POST /api/sys-enum/delete`
  - `POST /api/attachments/upload`
- 文档解析：
  - `document/parse` 与 `document/parse/impl` 已提供解析抽象和解析器工厂

证据：

- 代码：`common-agent-common/src/main/java/com/bruce/common/controller/*`
- 测试：
  - `common-agent-common/src/test/java/com/bruce/common/controller/SysEnumControllerTests.java`
  - `common-agent-common/src/test/java/com/bruce/common/factory/*`
  - `common-agent-common/src/test/java/com/bruce/common/document/parse/*`
  - `common-agent-common/src/test/java/com/bruce/common/handler/GlobalExceptionHandlerTests.java`

### 3.2 rag

已核对内容：

- 实体已覆盖：
  - `rag_store`
  - `rag_document`
  - `rag_document_parse_result`
  - `rag_chunk`
  - `rag_chunk_embedding`
- 旧接口保持兼容：
  - `/api/rag/store/*`
  - `/api/rag/documents/*`
- 聚合接口已提供：
  - `GET /api/knowledge/workspaces/{storeId}`
  - `POST /api/knowledge/ingestion-runs`
  - `GET /api/knowledge/ingestion-runs/{runId}`
- 受控最小运行链路已落地：
  - 批量上传
  - 手动解析
  - 手动切片
  - 向量化记录聚合查询

本轮补充：

- 新增 `POST /api/knowledge/ingestion-runs`，与前端实现文档草案保持一致。

证据：

- 代码：
  - `common-agent-rag/src/main/java/com/bruce/rag/controller/*`
  - `common-agent-rag/src/main/java/com/bruce/rag/service/impl/IngestionRunServiceImpl.java`
- 测试：
  - `common-agent-rag/src/test/java/com/bruce/rag/controller/IngestionRunControllerTests.java`
  - `common-agent-rag/src/test/java/com/bruce/rag/ingestion/IngestionRunServiceTests.java`
  - `common-agent-rag/src/test/java/com/bruce/rag/workspace/KnowledgeWorkspaceServiceTests.java`
  - 其余 `Rag*Tests`

### 3.3 modelprovider

已核对内容：

- 实体已覆盖：
  - `model_provider`
  - `model_config`
  - `model_route_rule`
  - `rag_store_model_config`
  - `model_call_log`
- 控制器已覆盖：
  - `ModelProviderController`
  - `ModelConfigController`
  - `ModelRouteRuleController`
  - `RagStoreModelConfigController`
  - `ModelCallLogController`
  - `ModelWorkspaceController`
- 网关抽象已位于 `gateway`

证据：

- 代码：`common-agent-modelprovider/src/main/java/com/bruce/modelprovider/**/*`
- 测试：
  - `common-agent-modelprovider/src/test/java/com/bruce/modelprovider/controller/ModelWorkspaceControllerTests.java`
  - `common-agent-modelprovider/src/test/java/com/bruce/modelprovider/workspace/ModelWorkspaceServiceTests.java`
  - `common-agent-modelprovider/src/test/java/com/bruce/modelprovider/factory/ModelProviderFactoryTests.java`

### 3.4 agent

已核对内容：

- 实体已覆盖：
  - `agent_definition`
  - `agent_session`
  - `agent_message`
  - `agent_capability_binding`
- 兼容接口与会话接口并存：
  - Agent 定义管理
  - `/api/agents/{agentId}/chat`
  - `/api/agent-sessions/*`
  - 工作台聚合接口

证据：

- 代码：`common-agent-agent/src/main/java/com/bruce/agent/**/*`
- 测试：
  - `common-agent-agent/src/test/java/com/bruce/agent/controller/AgentSessionControllerTests.java`
  - `common-agent-agent/src/test/java/com/bruce/agent/session/AgentSessionServiceTests.java`
  - `common-agent-agent/src/test/java/com/bruce/agent/workspace/AgentWorkspaceServiceTests.java`

### 3.5 workflow

已核对内容：

- 实体已覆盖：
  - `studio_project`
  - `workflow_definition`
  - `workflow_version`
  - `workflow_run`
  - `workflow_run_step`
- 控制器已覆盖：
  - `ProjectController`
  - `WorkflowDefinitionController`
  - `WorkflowVersionController`
  - `WorkflowRunController`
  - `WorkflowWorkspaceController`
- 前端工作台聚合使用 `GET /api/workflow-workspace/detail`；
  旧管理接口继续承担定义、版本与运行管理能力。
- 文档草案兼容路径已补充：
  - `GET /api/workflows/{workflowId}`
  - `POST /api/workflows/save-draft`
  - `POST /api/workflow-versions/compat/workflows/{workflowId}/publish`
  - `POST /api/workflow-runs/compat/workflows/{workflowId}/runs`
  - `GET /api/workflow-runs/compat/workflows/runs/{runId}`

证据：

- 代码：`common-agent-workflow/src/main/java/com/bruce/workflow/**/*`
- 测试：
  - `common-agent-workflow/src/test/java/com/bruce/workflow/controller/WorkflowCompatControllerTests.java`
  - `common-agent-workflow/src/test/java/com/bruce/workflow/controller/WorkflowWorkspaceControllerTests.java`
  - `common-agent-workflow/src/test/java/com/bruce/workflow/workspace/WorkflowWorkspaceServiceTests.java`
  - `common-agent-workflow/src/test/java/com/bruce/workflow/version/WorkflowVersionServiceTests.java`
  - `common-agent-workflow/src/test/java/com/bruce/workflow/WorkflowComponentStructureTests.java`

### 3.6 mcp

已核对内容：

- 实体已覆盖：
  - `mcp_server`
  - `mcp_capability`
- 接口已覆盖：
  - `POST /api/mcp/import`
  - `GET /api/mcp/servers`
  - `POST /api/mcp/servers/query`
  - `GET /api/mcp/servers/{serverId}/capabilities`
  - `GET /api/mcp/servers/code/{serverCode}/capabilities`
  - `POST /api/mcp/capabilities/save`
  - `GET /api/mcp/workspace`

证据：

- 代码：`common-agent-mcp/src/main/java/com/bruce/mcp/**/*`
- 测试：
  - `common-agent-mcp/src/test/java/com/bruce/mcp/controller/McpImportControllerTests.java`
  - `common-agent-mcp/src/test/java/com/bruce/mcp/importing/McpImportServiceTests.java`
  - `common-agent-mcp/src/test/java/com/bruce/mcp/workspace/McpWorkspaceServiceTests.java`

### 3.7 skill

已核对内容：

- 实体已覆盖：
  - `skill_definition`
  - `skill_version`
- 工作台接口已覆盖：
  - `GET /api/skills/{skillCode}`
  - `POST /api/skills/{skillCode}/draft`
  - `PUT /api/skills/{skillCode}/draft`
  - `POST /api/skills/{skillCode}/test`
  - `POST /api/skills/{skillCode}/publish`
  - `POST /api/skills/{skillCode}/archive`

证据：

- 代码：`common-agent-skill/src/main/java/com/bruce/skill/**/*`
- 测试：
  - `common-agent-skill/src/test/java/com/bruce/skill/controller/SkillWorkspaceControllerTests.java`
  - `common-agent-skill/src/test/java/com/bruce/skill/version/SkillVersionServiceTests.java`
  - `common-agent-skill/src/test/java/com/bruce/skill/workspace/SkillWorkspaceServiceTests.java`

### 3.8 observability

已核对内容：

- 聚合来源已复用：
  - `workflow_run`
  - `workflow_run_step`
  - `model_call_log`
  - `agent_session`
  - `agent_message`
- 接口已覆盖：
  - `GET /api/observability/runs`
  - `GET /api/observability/runs/{requestId}`
  - `GET /api/observability/model-calls`
  - `GET /api/observability/runs/{requestId}/export`
- 导出接口返回脱敏摘要对象

证据：

- 代码：`common-agent-observability/src/main/java/com/bruce/observability/**/*`
- 测试：
  - `common-agent-observability/src/test/java/com/bruce/observability/controller/ObservabilityTraceControllerTests.java`
  - `common-agent-observability/src/test/java/com/bruce/observability/trace/ObservabilityTraceServiceTests.java`

## 4. 前端对接核对

已核对内容：

- Studio 页面：
  - `frontend/src/pages/studio/StudioDashboardPage.vue`
  - `frontend/src/pages/studio/KnowledgeWorkspacePage.vue`
  - `frontend/src/pages/studio/IngestionPipelinePage.vue`
  - `frontend/src/pages/studio/ModelWorkspacePage.vue`
  - `frontend/src/pages/studio/WorkflowBuilderPage.vue`
  - `frontend/src/pages/studio/AgentWorkspacePage.vue`
  - `frontend/src/pages/studio/McpImportPage.vue`
  - `frontend/src/pages/studio/SkillWorkspacePage.vue`
  - `frontend/src/pages/studio/ObservabilityPage.vue`
- API 封装已覆盖：
  - `frontend/src/api/*.ts`
- 页面/API 单测已覆盖：
  - `frontend/src/pages/studio/__tests__/*`
  - `frontend/src/api/__tests__/*`

## 4.1 文档草案路径兼容收口

为减少“文档草案路径”和“现有聚合接口路径”之间的偏差，当前已额外补齐以下兼容入口：

- Workflow：
  - `GET /api/workflows/{workflowId}`
  - `POST /api/workflows/save-draft`
  - `POST /api/workflow-versions/compat/workflows/{workflowId}/publish`
  - `POST /api/workflow-runs/compat/workflows/{workflowId}/runs`
  - `GET /api/workflow-runs/compat/workflows/runs/{runId}`
- Agent：
  - `POST /api/agents/{agentId}/runs`
  - `GET /api/agent-sessions/agents/{agentId}/sessions`
  - `GET /api/agent-sessions/{sessionId}`
- MCP：
  - `POST /api/mcp/servers/query`
- Skill：
  - `PUT /api/skills/{skillCode}/draft`

## 5. 当前仍需持续关注的风险

- 当前多数“mapper / repository 验证”仍以结构契约测试为主，真实数据库集成测试覆盖度有限。
- 当前实现仍保留“旧管理接口 + Studio 聚合接口 + 文档草案兼容路径”的三轨并行方式，能力已覆盖，但后续如进入正式 API 收敛阶段，仍建议选定长期主路径并逐步淘汰别名。
- 现有运行链路以“主数据优先 + 最小可运行”实现为主，复杂分支调度、远程 MCP 实时执行编排、重型运行器能力仍适合后续继续增强。
- 当前尚未形成“逐文件自动扫描中文日志/注释完整性”的机械化证明，现阶段主要依赖关键实现抽查、提交记录与模块测试覆盖。

## 6. 本次审计后的新增变更

- 新增 `POST /api/knowledge/ingestion-runs`，补齐前端实现文档中的摄取运行创建入口。
- 补充 `IngestionRunControllerTests` 与前端 `ingestion.spec.ts` 创建接口测试。
- 补充 `WorkflowWorkspaceController` 中文注释与标准化业务日志。
- 补充 Workflow / Agent / MCP / Skill 的文档草案兼容路径与控制器测试。