feat(audit): 补齐摄取管道入口并沉淀完成度审计

2026-06-01 06:04:30 +08:00
parent 1d401c6841
commit c8245ba0d6
10 changed files with 505 additions and 2 deletions
--- a/docs/模块完成度审计.md
+++ b/docs/模块完成度审计.md
@@ -0,0 +1,275 @@
+# 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`；
+  旧管理接口继续承担定义、版本与运行管理能力。
+
+说明：
+
+- 前端实现文档中的 REST 草案与当前聚合接口命名不完全一致，但职责已由 `WorkflowWorkspaceController` 承接，且不影响旧接口兼容。
+
+证据：
+
+- 代码：`common-agent-workflow/src/main/java/com/bruce/workflow/**/*`
+- 测试：
+  - `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`
+  - `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`
+  - `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__/*`
+
+## 5. 当前仍需持续关注的风险
+
+- 当前多数“mapper / repository 验证”仍以结构契约测试为主，真实数据库集成测试覆盖度有限。
+- 部分前端实现文档中的接口命名是草案，当前实现更多采用“旧管理接口 + Studio 聚合接口”的双轨方式；职责已覆盖，但验收时需要按“能力是否已落地”而非“路径字面一致”判断。
+- 现有运行链路以“主数据优先 + 最小可运行”实现为主，复杂分支调度、远程 MCP 实时执行编排、重型运行器能力仍适合后续继续增强。
+
+## 6. 本次审计后的新增变更
+
+- 新增 `POST /api/knowledge/ingestion-runs`，补齐前端实现文档中的摄取运行创建入口。
+- 补充 `IngestionRunControllerTests` 与前端 `ingestion.spec.ts` 创建接口测试。
+- 补充 `WorkflowWorkspaceController` 中文注释与标准化业务日志。