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 接口。

## 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 的文档草案兼容路径与控制器测试。