From 1e1c731c3ffb74f8d93a92c343fa83e336313b56 Mon Sep 17 00:00:00 2001 From: bruce Date: Mon, 1 Jun 2026 00:44:53 +0800 Subject: [PATCH] =?UTF-8?q?docs(project):=20=E5=BB=BA=E7=AB=8B=E4=B8=AD?= =?UTF-8?q?=E6=96=87=E6=A8=A1=E5=9D=97=E6=96=87=E6=A1=A3=E4=BD=93=E7=B3=BB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 前端实现文档/0.前端模块总览.md | 27 +++++++++++++ 后端实现文档/0.后端模块总览.md | 36 +++++++++++++++++ 数据库设计/0.数据库与枚举总览.md | 54 ++++++++++++++++++++++++++ 设计文档/0.模块设计总览.md | 50 ++++++++++++++++++++++++ 需求分析/0.模块总览.md | 66 ++++++++++++++++++++++++++++++++ 5 files changed, 233 insertions(+) create mode 100644 前端实现文档/0.前端模块总览.md create mode 100644 后端实现文档/0.后端模块总览.md create mode 100644 数据库设计/0.数据库与枚举总览.md create mode 100644 设计文档/0.模块设计总览.md create mode 100644 需求分析/0.模块总览.md diff --git a/前端实现文档/0.前端模块总览.md b/前端实现文档/0.前端模块总览.md new file mode 100644 index 0000000..75f296a --- /dev/null +++ b/前端实现文档/0.前端模块总览.md @@ -0,0 +1,27 @@ +# 前端模块总览 + +## 1. 当前原型入口 + +Studio 原型页面位于 `frontend/src/pages/studio/`，路由集中在 `frontend/src/router/index.ts`，模拟数据位于 `frontend/src/data/studioMock.ts`。 + +## 2. 页面与模块映射 + +| 页面 | 模块 | +|------|------| +| `StudioDashboardPage.vue` | 工作台与发布就绪 | +| `KnowledgeWorkspacePage.vue` | 知识资产 | +| `IngestionPipelinePage.vue` | 文件解析管道 | +| `ModelWorkspacePage.vue` | 模型与路由 | +| `WorkflowBuilderPage.vue` | Workflow 编排 | +| `AgentWorkspacePage.vue` | Agent 对话调试 | +| `McpImportPage.vue` | MCP 能力接入 | +| `SkillWorkspacePage.vue` | Skill 编辑 | +| `ObservabilityPage.vue` | 运行观测 | + +## 3. 前端实现原则 + +- 页面使用聚合 ViewModel，避免页面直接拼多个低层接口。 +- 已落地旧接口保持兼容，新 Studio 接口以聚合资源为主。 +- Long ID 继续按字符串处理，避免 JS 精度问题。 +- 枚举值按整型协议处理，页面展示通过枚举字典或常量映射。 +- 管理后台保持信息密度、稳定布局和清晰状态提示。 diff --git a/后端实现文档/0.后端模块总览.md b/后端实现文档/0.后端模块总览.md new file mode 100644 index 0000000..67b7611 --- /dev/null +++ b/后端实现文档/0.后端模块总览.md @@ -0,0 +1,36 @@ +# 后端模块总览 + +## 1. 当前代码边界 + +当前后端已有 `common`、`rag`、`modelprovider`、`agent` 包。后续重新实现时，可以保留这些包作为技术分层落点，但业务文档按产品域拆分。 + +## 2. 后端实现原则 + +- Controller 不直接暴露实体。 +- 请求使用 `XxxRequest`，响应使用 `XxxResponse`。 +- 统一返回 `RequestResult`。 +- 实体继承 `BaseEntity`，保持审计字段和乐观锁字段。 +- Mapper 继续使用 MyBatis-Plus `BaseMapper`。 +- Service 负责业务校验、状态流转和跨表协调。 + +## 3. 模块落点建议 + +| 产品域 | 后端包建议 | +|--------|------------| +| 系统基础 | `com.bruce.common` | +| 知识资产与文件解析 | `com.bruce.rag` | +| 模型与路由 | `com.bruce.modelprovider` | +| Workflow 编排 | `com.bruce.workflow` | +| Agent 会话 | `com.bruce.agent` | +| MCP 能力接入 | `com.bruce.mcp` | +| Skill 编辑 | `com.bruce.skill` | +| 运行观测 | `com.bruce.observability` 或复用运行来源模块 | + +## 4. 枚举实现约束 + +新增结构化枚举时，继续实现 `PersistableSysEnumDefinition`，并同步： + +- Java 枚举定义。 +- `sys_enum` 初始化测试。 +- `script/sql/studio_enum.sql` 或对应模块枚举脚本。 +- 前端枚举常量或字典接口。 diff --git a/数据库设计/0.数据库与枚举总览.md b/数据库设计/0.数据库与枚举总览.md new file mode 100644 index 0000000..bfc6f01 --- /dev/null +++ b/数据库设计/0.数据库与枚举总览.md @@ -0,0 +1,54 @@ +# 数据库与枚举总览 + +## 1. 文档目的 + +本文集中说明本轮数据库和枚举脚本的更新范围，避免需求文档、设计文档、前端文档、后端文档与 SQL 脚本出现冲突。 + +## 2. SQL 脚本分层 + +| 脚本位置 | 作用 | +|----------|------| +| `script/sql/` | 可执行的模块化建表或初始化脚本 | +| `docs/MODEL_PROVIDER_SCHEMA.sql` | 模型平台 schema 汇总 | +| `docs/STUDIO_PROTOTYPE_SCHEMA.sql` | Studio 原型 schema 汇总 | + +模块化脚本是后续落库执行的优先参考，`docs/*SCHEMA.sql` 是完整设计快照。 + +## 3. 必须保持不变的内容 + +`script/sql/enum.sql` 中 `sys_enum` 表结构不变： + +- `catalog` +- `type` +- `name` +- `value` +- `strvalue` +- `sort` +- `version` +- `create_time` +- `update_time` +- `remark` +- `create_by` +- `update_by` + +Java 枚举契约 `PersistableSysEnumDefinition` 的格式不变。后续如果实现新枚举类，仍按现有 `getCatalog()`、`getType()`、`getValue()`、`getLabel()`、`getRemark()` 风格实现。 + +## 4. 本轮新增脚本 + +| 脚本 | 内容 | +|------|------| +| `script/sql/studio_project.sql` | Studio 项目空间表 | +| `script/sql/workflow.sql` | Workflow 定义、版本、运行、步骤日志 | +| `script/sql/mcp.sql` | MCP Server 与能力表 | +| `script/sql/skill.sql` | Skill 定义与版本表 | +| `script/sql/agent_session.sql` | Agent 会话与消息表 | +| `script/sql/agent_capability_binding.sql` | Agent/Workflow 与 MCP/Skill/知识能力绑定表 | +| `script/sql/studio_enum.sql` | Studio 相关枚举初始化 | + +## 5. 校验规则 + +- 所有新增表必须包含 `id`、`version`、`create_time`、`update_time`、`remark`、`create_by`、`update_by`。 +- 需要唯一业务编码的表必须增加唯一约束。 +- 需要跨模块引用的字段必须在文档中说明外键关系。 +- JSON 扩展字段统一使用 `JSONB`。 +- 枚举初始化脚本必须使用 `ON CONFLICT (catalog, type, name) DO UPDATE`，与现有脚本风格一致。 diff --git a/设计文档/0.模块设计总览.md b/设计文档/0.模块设计总览.md new file mode 100644 index 0000000..c24cd99 --- /dev/null +++ b/设计文档/0.模块设计总览.md @@ -0,0 +1,50 @@ +# Common Agent Studio 模块设计总览 + +## 1. 总体设计 + +Common Agent Studio 以一次 AI 应用发布旅程为主线：知识接入、模型路由、Workflow 编排、Agent 调试、MCP/Skill 扩展和运行观测围绕同一个项目空间协作。 + +旧代码中的 `common`、`rag`、`modelprovider`、`agent` 仍作为实现包存在，但新文档按产品域组织，便于后续重新实现时形成更清晰的模块边界。 + +## 2. 产品域关系 + +```mermaid +flowchart LR + Common["系统基础"] --> Knowledge["知识资产与文件解析"] + Common --> Model["模型与路由"] + Knowledge --> Workflow["Workflow 编排"] + Model --> Workflow + Workflow --> Agent["Agent 会话"] + MCP["MCP 能力接入"] --> Workflow + Skill["Skill 编辑"] --> Workflow + Agent --> Observability["运行观测"] + Workflow --> Observability + Model --> Observability +``` + +## 3. 数据主线 + +| 主线 | 表 | +|------|------| +| 系统基础 | `sys_enum`、`sys_attachment` | +| 知识资产 | `rag_store`、`rag_document`、`rag_document_parse_result`、`rag_chunk`、`rag_chunk_embedding` | +| 模型路由 | `model_provider`、`model_config`、`model_route_rule`、`rag_store_model_config`、`model_call_log` | +| Studio 项目 | `studio_project` | +| Workflow | `workflow_definition`、`workflow_version`、`workflow_run`、`workflow_run_step` | +| Agent | `agent_definition`、`agent_session`、`agent_message`、`agent_capability_binding` | +| MCP | `mcp_server`、`mcp_capability` | +| Skill | `skill_definition`、`skill_version` | + +## 4. 接口命名原则 + +- 已落地接口保持兼容，例如 `/api/rag/documents/query`、`/api/agents/{agentId}/chat`。 +- Studio 新接口使用聚合资源命名，例如 `/api/knowledge/workspaces/{storeId}`、`/api/workflows/{workflowId}/runs`。 +- 请求和响应继续使用 DTO，不直接暴露实体。 +- 统一返回体保持 `RequestResult`。 + +## 5. 状态设计原则 + +- 长期稳定状态使用结构化枚举。 +- 枚举设计必须保留 `sys_enum` 当前格式。 +- 数据库中状态字段允许继续使用 `VARCHAR` 保存枚举代码，前后端协议层对结构化枚举继续传整型值。 +- 页面展示文案来自枚举定义或前端常量映射，不在业务逻辑中散落硬编码。 diff --git a/需求分析/0.模块总览.md b/需求分析/0.模块总览.md new file mode 100644 index 0000000..02d4f6d --- /dev/null +++ b/需求分析/0.模块总览.md @@ -0,0 +1,66 @@ +# Common Agent Studio 模块总览 + +## 1. 文档目的 + +本文用于统一本轮文档重构的模块口径。后续需求分析、设计文档、前端实现文档、后端实现文档和数据库设计均以本文的产品域模块为准，不再直接按旧后端包名划分。 + +本轮只处理文档和 SQL 脚本，不修改 Java、Vue、测试代码。 + +## 2. 模块划分 + +| 序号 | 模块 | 范围 | +|------|------|------| +| 1 | 系统基础 | 系统枚举、附件、审计字段、统一返回体、文档解析抽象 | +| 2 | 知识资产与文件解析 | 知识库、知识文档、解析快照、切片、向量、索引任务 | +| 3 | 模型与路由 | 模型服务商、模型配置、任务路由、知识库模型绑定、调用日志 | +| 4 | Workflow 编排 | 项目空间、Workflow 定义、版本快照、运行记录、步骤日志 | +| 5 | Agent 会话 | Agent 定义、调试运行、会话、消息、引用切片 | +| 6 | MCP 能力接入 | MCP Server 导入、能力发现、能力启停用 | +| 7 | Skill 编辑 | Skill 定义、版本、Prompt/Code/Config、测试结果 | +| 8 | 运行观测 | Workflow Trace、模型调用日志、成本、延迟、异常排查 | + +## 3. 目录规范 + +| 目录 | 用途 | +|------|------| +| `需求分析/` | 描述业务目标、角色、场景、范围和验收标准 | +| `设计文档/` | 描述领域模型、状态流转、模块依赖和接口形态 | +| `数据库设计/` | 描述表结构、枚举、脚本同步规则和跨模块关系 | +| `前端实现文档/` | 描述页面、ViewModel、API 调用和交互状态 | +| `后端实现文档/` | 描述 Controller、DTO、Service、Entity、Mapper 和校验规则 | + +## 4. 脚本范围 + +本轮 SQL 脚本属于正式交付范围： + +- `script/sql/*.sql`：面向落库执行的模块化脚本。 +- `docs/MODEL_PROVIDER_SCHEMA.sql`：模型平台 schema 汇总。 +- `docs/STUDIO_PROTOTYPE_SCHEMA.sql`：Studio 原型 schema 汇总。 + +新增或调整数据库设计时，必须同步更新对应脚本。新增或调整枚举设计时，必须同步更新 `sys_enum` 初始化脚本。 + +## 5. 枚举约束 + +`sys_enum` 表结构保持不变，Java 枚举契约保持现有格式不变： + +- `catalog` +- `type` +- `name` +- `value` +- `strvalue` +- `sort` +- `remark` + +前后端结构化枚举继续使用整型 `value` 作为协议值，不改成字符串协议。 + +## 6. 交叉引用规则 + +每个模块文档必须说明： + +- 关联数据库表。 +- 关联枚举组。 +- 关联 SQL 脚本。 +- 关联前端页面或原型 View。 +- 关联后端接口草案。 + +最终以 `数据库设计/9.模块一致性校验.md` 统一检查跨模块冲突。