docs(workflow): 补全流程编排设计

2026-06-01 00:51:11 +08:00
parent 3526322811
commit b26edb8877
8 changed files with 318 additions and 0 deletions
--- a/docs/STUDIO_PROTOTYPE_SCHEMA.sql
+++ b/docs/STUDIO_PROTOTYPE_SCHEMA.sql
@@ -226,3 +226,25 @@ CREATE TABLE IF NOT EXISTS agent_capability_binding (
    update_by VARCHAR(64),
    CONSTRAINT uk_agent_capability_binding UNIQUE (owner_type, owner_id, capability_type, capability_id)
 );
+
+CREATE INDEX IF NOT EXISTS idx_studio_project_environment ON studio_project (environment);
+CREATE INDEX IF NOT EXISTS idx_studio_project_publish_status ON studio_project (publish_status);
+CREATE INDEX IF NOT EXISTS idx_workflow_definition_project_id ON workflow_definition (project_id);
+CREATE INDEX IF NOT EXISTS idx_workflow_definition_status ON workflow_definition (status);
+CREATE INDEX IF NOT EXISTS idx_workflow_version_workflow_id ON workflow_version (workflow_id);
+CREATE INDEX IF NOT EXISTS idx_workflow_run_workflow_id ON workflow_run (workflow_id);
+CREATE INDEX IF NOT EXISTS idx_workflow_run_status ON workflow_run (status);
+CREATE INDEX IF NOT EXISTS idx_workflow_run_step_run_id ON workflow_run_step (run_id);
+
+COMMENT ON TABLE studio_project IS 'Studio项目空间表';
+COMMENT ON TABLE workflow_definition IS 'Workflow定义表';
+COMMENT ON TABLE workflow_version IS 'Workflow版本快照表';
+COMMENT ON TABLE workflow_run IS 'Workflow运行记录表';
+COMMENT ON TABLE workflow_run_step IS 'Workflow运行步骤表';
+COMMENT ON TABLE mcp_server IS 'MCP服务表';
+COMMENT ON TABLE mcp_capability IS 'MCP能力表';
+COMMENT ON TABLE skill_definition IS 'Skill定义表';
+COMMENT ON TABLE skill_version IS 'Skill版本表';
+COMMENT ON TABLE agent_session IS 'Agent会话表';
+COMMENT ON TABLE agent_message IS 'Agent消息表';
+COMMENT ON TABLE agent_capability_binding IS 'Agent能力绑定表';
--- a/script/sql/studio_project.sql
+++ b/script/sql/studio_project.sql
@@ -0,0 +1,27 @@
+-- Studio 项目空间表。
+
+CREATE TABLE IF NOT EXISTS studio_project (
+    id BIGSERIAL PRIMARY KEY,
+    project_code VARCHAR(100) NOT NULL,
+    project_name VARCHAR(200) NOT NULL,
+    environment VARCHAR(50) NOT NULL DEFAULT 'DEV',
+    publish_status VARCHAR(50) NOT NULL DEFAULT 'DRAFT',
+    current_version VARCHAR(50),
+    version INTEGER NOT NULL DEFAULT 1,
+    create_time TIMESTAMP,
+    update_time TIMESTAMP,
+    remark VARCHAR(500) DEFAULT '',
+    create_by VARCHAR(64),
+    update_by VARCHAR(64),
+    CONSTRAINT uk_studio_project_code UNIQUE (project_code)
+);
+
+CREATE INDEX IF NOT EXISTS idx_studio_project_environment ON studio_project (environment);
+CREATE INDEX IF NOT EXISTS idx_studio_project_publish_status ON studio_project (publish_status);
+
+COMMENT ON TABLE studio_project IS 'Studio项目空间表';
+COMMENT ON COLUMN studio_project.project_code IS '项目编码';
+COMMENT ON COLUMN studio_project.project_name IS '项目名称';
+COMMENT ON COLUMN studio_project.environment IS '环境';
+COMMENT ON COLUMN studio_project.publish_status IS '发布状态';
+COMMENT ON COLUMN studio_project.current_version IS '当前发布版本';
--- a/script/sql/workflow.sql
+++ b/script/sql/workflow.sql
@@ -0,0 +1,94 @@
+-- Workflow 编排核心表。
+
+CREATE TABLE IF NOT EXISTS workflow_definition (
+    id BIGSERIAL PRIMARY KEY,
+    project_id BIGINT,
+    workflow_code VARCHAR(100) NOT NULL,
+    workflow_name VARCHAR(200) NOT NULL,
+    description VARCHAR(1000),
+    bound_agent_id BIGINT,
+    status VARCHAR(50) NOT NULL DEFAULT 'DRAFT',
+    version INTEGER NOT NULL DEFAULT 1,
+    create_time TIMESTAMP,
+    update_time TIMESTAMP,
+    remark VARCHAR(500) DEFAULT '',
+    create_by VARCHAR(64),
+    update_by VARCHAR(64),
+    CONSTRAINT uk_workflow_definition_code UNIQUE (workflow_code),
+    CONSTRAINT fk_workflow_definition_project_id FOREIGN KEY (project_id) REFERENCES studio_project (id),
+    CONSTRAINT fk_workflow_definition_agent_id FOREIGN KEY (bound_agent_id) REFERENCES agent_definition (id)
+);
+
+CREATE TABLE IF NOT EXISTS workflow_version (
+    id BIGSERIAL PRIMARY KEY,
+    workflow_id BIGINT NOT NULL,
+    version_no INTEGER NOT NULL,
+    snapshot_name VARCHAR(100) NOT NULL,
+    graph_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+    publish_status VARCHAR(50) NOT NULL DEFAULT 'DRAFT',
+    published_time TIMESTAMP,
+    version INTEGER NOT NULL DEFAULT 1,
+    create_time TIMESTAMP,
+    update_time TIMESTAMP,
+    remark VARCHAR(500) DEFAULT '',
+    create_by VARCHAR(64),
+    update_by VARCHAR(64),
+    CONSTRAINT uk_workflow_version_no UNIQUE (workflow_id, version_no),
+    CONSTRAINT fk_workflow_version_workflow_id FOREIGN KEY (workflow_id) REFERENCES workflow_definition (id)
+);
+
+CREATE TABLE IF NOT EXISTS workflow_run (
+    id BIGSERIAL PRIMARY KEY,
+    request_id VARCHAR(64) NOT NULL,
+    workflow_id BIGINT,
+    workflow_version_id BIGINT,
+    agent_id BIGINT,
+    run_source VARCHAR(50) NOT NULL,
+    status VARCHAR(50) NOT NULL,
+    input_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+    output_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+    duration_ms INTEGER,
+    estimated_cost NUMERIC(14, 8),
+    version INTEGER NOT NULL DEFAULT 1,
+    create_time TIMESTAMP,
+    update_time TIMESTAMP,
+    remark VARCHAR(500) DEFAULT '',
+    create_by VARCHAR(64),
+    update_by VARCHAR(64),
+    CONSTRAINT uk_workflow_run_request_id UNIQUE (request_id),
+    CONSTRAINT fk_workflow_run_workflow_id FOREIGN KEY (workflow_id) REFERENCES workflow_definition (id),
+    CONSTRAINT fk_workflow_run_version_id FOREIGN KEY (workflow_version_id) REFERENCES workflow_version (id),
+    CONSTRAINT fk_workflow_run_agent_id FOREIGN KEY (agent_id) REFERENCES agent_definition (id)
+);
+
+CREATE TABLE IF NOT EXISTS workflow_run_step (
+    id BIGSERIAL PRIMARY KEY,
+    run_id BIGINT NOT NULL,
+    node_id VARCHAR(100) NOT NULL,
+    node_type VARCHAR(50) NOT NULL,
+    node_name VARCHAR(200),
+    status VARCHAR(50) NOT NULL,
+    input_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+    output_json JSONB NOT NULL DEFAULT '{}'::jsonb,
+    duration_ms INTEGER,
+    error_message VARCHAR(1000),
+    version INTEGER NOT NULL DEFAULT 1,
+    create_time TIMESTAMP,
+    update_time TIMESTAMP,
+    remark VARCHAR(500) DEFAULT '',
+    create_by VARCHAR(64),
+    update_by VARCHAR(64),
+    CONSTRAINT fk_workflow_run_step_run_id FOREIGN KEY (run_id) REFERENCES workflow_run (id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_workflow_definition_project_id ON workflow_definition (project_id);
+CREATE INDEX IF NOT EXISTS idx_workflow_definition_status ON workflow_definition (status);
+CREATE INDEX IF NOT EXISTS idx_workflow_version_workflow_id ON workflow_version (workflow_id);
+CREATE INDEX IF NOT EXISTS idx_workflow_run_workflow_id ON workflow_run (workflow_id);
+CREATE INDEX IF NOT EXISTS idx_workflow_run_status ON workflow_run (status);
+CREATE INDEX IF NOT EXISTS idx_workflow_run_step_run_id ON workflow_run_step (run_id);
+
+COMMENT ON TABLE workflow_definition IS 'Workflow定义表';
+COMMENT ON TABLE workflow_version IS 'Workflow版本快照表';
+COMMENT ON TABLE workflow_run IS 'Workflow运行记录表';
+COMMENT ON TABLE workflow_run_step IS 'Workflow运行步骤表';
--- a/前端实现文档/4.Workflow编排模块前端实现.md
+++ b/前端实现文档/4.Workflow编排模块前端实现.md
@@ -0,0 +1,31 @@
+# Workflow 编排模块前端实现
+
+## 1. 页面
+
+`WorkflowBuilderPage.vue` 提供节点库、画布、运行 Trace 抽屉和节点 Inspector。
+
+## 2. ViewModel
+
+`WorkflowBuilderView` 建议包含：
+
+- Workflow 基本信息。
+- 当前草稿版本。
+- 节点列表。
+- 边列表。
+- 当前选中节点配置。
+- 最近测试运行 Trace。
+
+## 3. 接口草案
+
+- `GET /api/workflows/{workflowId}`
+- `POST /api/workflows/save-draft`
+- `POST /api/workflows/{workflowId}/publish`
+- `POST /api/workflows/{workflowId}/runs`
+- `GET /api/workflows/runs/{runId}`
+
+## 4. 交互规则
+
+- 保存草稿只更新草稿版本。
+- 运行测试生成 `workflow_run` 和 `workflow_run_step`。
+- 发布前调用发布就绪检查。
+- 节点 Inspector 只编辑当前节点配置，不直接改其他节点。
--- a/后端实现文档/4.Workflow编排模块后端实现.md
+++ b/后端实现文档/4.Workflow编排模块后端实现.md
@@ -0,0 +1,38 @@
+# Workflow 编排模块后端实现
+
+## 1. 包建议
+
+后续实现建议新增 `com.bruce.workflow`：
+
+- `controller`
+- `dto/request`
+- `dto/response`
+- `entity`
+- `enums`
+- `mapper`
+- `service`
+- `runner`
+
+## 2. Controller 草案
+
+- `WorkflowDefinitionController`
+- `WorkflowVersionController`
+- `WorkflowRunController`
+
+## 3. Service 草案
+
+| Service | 职责 |
+|---------|------|
+| `IWorkflowDefinitionService` | 定义 CRUD、绑定 Agent |
+| `IWorkflowVersionService` | 草稿保存、发布快照 |
+| `IWorkflowRunService` | 运行测试、运行记录查询 |
+| `IWorkflowRunner` | 按图执行节点并写入步骤日志 |
+
+## 4. 校验规则
+
+- Workflow 编码唯一。
+- 发布版本号不可重复。
+- 运行时必须使用确定的版本快照。
+- 节点类型必须来自枚举。
+- LLM 节点必须配置任务类型。
+- Knowledge Retrieval 节点必须配置知识库或继承项目默认知识库。
--- a/数据库设计/4.Workflow数据库设计.md
+++ b/数据库设计/4.Workflow数据库设计.md
@@ -0,0 +1,33 @@
+# Workflow 数据库设计
+
+## 1. 表结构
+
+| 表 | 说明 |
+|----|------|
+| `studio_project` | Studio 项目空间 |
+| `workflow_definition` | Workflow 主定义 |
+| `workflow_version` | Workflow 版本快照 |
+| `workflow_run` | Workflow 运行记录 |
+| `workflow_run_step` | Workflow 节点步骤日志 |
+
+## 2. 关键约束
+
+- `studio_project.project_code` 唯一。
+- `workflow_definition.workflow_code` 唯一。
+- `workflow_version` 使用 `(workflow_id, version_no)` 唯一。
+- `workflow_run.request_id` 唯一。
+- `workflow_definition.bound_agent_id` 可引用 `agent_definition`。
+
+## 3. 脚本
+
+- `script/sql/studio_project.sql`
+- `script/sql/workflow.sql`
+- `docs/STUDIO_PROTOTYPE_SCHEMA.sql`
+
+## 4. JSON 字段
+
+- `workflow_version.graph_json` 保存流程图快照。
+- `workflow_run.input_json` 与 `output_json` 保存运行输入输出摘要。
+- `workflow_run_step.input_json` 与 `output_json` 保存节点级输入输出摘要。
+
+JSON 字段只保存运行必要摘要，不保存敏感密钥。
--- a/设计文档/4.Workflow编排模块设计.md
+++ b/设计文档/4.Workflow编排模块设计.md
@@ -0,0 +1,46 @@
+# Workflow 编排模块设计
+
+## 1. 核心模型
+
+| 对象 | 说明 |
+|------|------|
+| Studio 项目 | 聚合多个 Workflow、Agent 和发布配置 |
+| Workflow 定义 | 可编辑流程主数据 |
+| Workflow 版本 | 发布或草稿快照，保存 `graph_json` |
+| Workflow 运行 | 一次测试或正式运行 |
+| Workflow 步骤 | 单个节点的输入、输出、耗时和错误 |
+
+## 2. 图模型
+
+`workflow_version.graph_json` 保存节点与边：
+
+- 节点：`id`、`type`、`label`、`config`、`position`
+- 边：`from`、`to`、`condition`
+
+图模型由后端做最小结构校验，复杂交互由前端画布负责。
+
+## 3. 运行链路
+
+```mermaid
+flowchart LR
+    Start["Start"] --> Retrieve["Knowledge Retrieval"]
+    Retrieve --> LLM["LLM"]
+    LLM --> Tool["MCP Tool"]
+    Tool --> Skill["Skill"]
+    Skill --> Answer["Answer"]
+```
+
+## 4. 状态设计
+
+- Workflow 定义状态：草稿、启用、停用、归档。
+- 发布状态：草稿、已发布、已归档。
+- 运行状态：排队中、运行中、成功、失败、取消。
+- 节点状态：等待、运行中、成功、失败、跳过。
+
+## 5. 依赖关系
+
+- Knowledge Retrieval 节点依赖知识资产模块。
+- LLM 节点依赖模型与路由模块。
+- MCP Tool 节点依赖 MCP 模块。
+- Skill 节点依赖 Skill 模块。
+- 运行记录被运行观测模块消费。
--- a/需求分析/4.Workflow编排模块需求.md
+++ b/需求分析/4.Workflow编排模块需求.md
@@ -0,0 +1,27 @@
+# Workflow 编排模块需求
+
+## 1. 模块目标
+
+Workflow 编排模块负责把知识检索、模型调用、MCP 工具、Skill 和回答输出组织成可保存、可测试、可发布、可追踪的图形化流程。
+
+## 2. 功能需求
+
+- 支持项目空间管理，区分环境和发布状态。
+- 支持 Workflow 草稿编辑、保存和发布版本。
+- 支持节点库：Start、LLM、Knowledge Retrieval、MCP Tool、Skill、Condition、Answer。
+- 支持 JSON Graph 保存画布结构。
+- 支持运行测试并生成运行记录和步骤日志。
+- 支持绑定默认 Agent，供对话调试和发布使用。
+
+## 3. 发布要求
+
+- 草稿可以保存但不能直接作为生产版本。
+- 发布时必须生成不可变版本快照。
+- 发布前必须检查模型路由、知识库索引、MCP 授权和 Skill 发布状态。
+
+## 4. 关联资料
+
+- 表：`studio_project`、`workflow_definition`、`workflow_version`、`workflow_run`、`workflow_run_step`
+- 枚举：`studio/environment`、`studio/publish_status`、`workflow/status`、`workflow/run_status`、`workflow/node_type`
+- 脚本：`script/sql/studio_project.sql`、`script/sql/workflow.sql`
+- 前端原型：`StudioDashboardPage.vue`、`WorkflowBuilderPage.vue`