docs(project): 调整中文模块文档位置

2026-06-01 02:02:08 +08:00
parent e9abf0b689
commit d92496854d
45 changed files with 0 additions and 0 deletions
--- a/docs/数据库设计/0.数据库与枚举总览.md
+++ b/docs/数据库设计/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`，与现有脚本风格一致。
--- a/docs/数据库设计/2.知识资产数据库设计.md
+++ b/docs/数据库设计/2.知识资产数据库设计.md
@@ -0,0 +1,37 @@
+# 知识资产数据库设计
+
+## 1. 表关系
+
+| 表 | 说明 | 关键关系 |
+|----|------|----------|
+| `rag_store` | 知识库主表 | 独立业务编码 |
+| `rag_document` | 知识文档 | 引用 `rag_store`、`sys_attachment` |
+| `rag_document_parse_result` | 解析快照 | 引用 `rag_store`、`rag_document` |
+| `rag_chunk` | 知识切片 | 引用 `rag_store`、`rag_document` |
+| `rag_chunk_embedding` | 切片向量 | 引用 `rag_store`、`rag_document`、`rag_chunk` |
+| `rag_store_model_config` | 知识库模型配置 | 引用 `rag_store`、`model_config` |
+
+## 2. 脚本清单
+
+- `script/sql/rag_store.sql`
+- `script/sql/rag_document.sql`
+- `script/sql/rag_document_parse_result.sql`
+- `script/sql/rag_chunk.sql`
+- `script/sql/rag_chunk_embedding.sql`
+- `docs/MODEL_PROVIDER_SCHEMA.sql` 中的 `rag_store_model_config`
+
+## 3. 枚举组
+
+| catalog | type | Java 枚举 |
+|---------|------|-----------|
+| `rag` | `parse_status` | `RagParseStatusEnum` |
+| `rag` | `index_status` | `RagIndexStatusEnum` |
+| `rag` | `chunk_strategy` | `RagChunkStrategyEnum` |
+
+## 4. 一致性要求
+
+- `rag_document.attachment_id` 保持唯一，避免一个附件重复建档。
+- `rag_document_parse_result.document_id` 保持唯一，表示一个文档一个当前解析快照。
+- `rag_chunk` 使用 `(document_id, chunk_index)` 保证同文档切片序号唯一。
+- `rag_chunk_embedding` 使用 `(chunk_id, embedding_model)` 防止同模型重复写入。
+- RAG 现有脚本与本文档一致，本轮不调整 `sys_enum` 格式。
--- a/docs/数据库设计/3.模型与路由数据库设计.md
+++ b/docs/数据库设计/3.模型与路由数据库设计.md
@@ -0,0 +1,37 @@
+# 模型与路由数据库设计
+
+## 1. 表关系
+
+| 表 | 说明 |
+|----|------|
+| `model_provider` | 模型服务商配置 |
+| `model_config` | 服务商下具体模型 |
+| `model_route_rule` | 任务路由规则 |
+| `rag_store_model_config` | 知识库 Embedding 与切片配置 |
+| `model_call_log` | 模型调用日志 |
+
+## 2. 关键约束
+
+- `model_provider.provider_code` 全局唯一。
+- `model_config` 使用 `(provider_id, model_code)` 唯一。
+- `model_route_rule.route_code` 全局唯一。
+- `rag_store_model_config` 使用 `(store_id, active)` 约束一个知识库只有一个生效配置。
+- `model_call_log.request_id` 全局唯一。
+
+## 3. 枚举组
+
+| catalog | type |
+|---------|------|
+| `model_provider` | `provider_type` |
+| `model_provider` | `protocol_type` |
+| `model_provider` | `model_type` |
+| `model_provider` | `task_type` |
+| `model_provider` | `route_strategy` |
+| `model_provider` | `call_status` |
+| `model_provider` | `health_status` |
+
+## 4. 脚本
+
+- `docs/MODEL_PROVIDER_SCHEMA.sql` 是完整 schema 快照。
+- `script/sql/model_provider.sql` 是后续执行入口。
+- 若模型枚举变更，需要同步 Java 枚举、初始化测试和 SQL 枚举脚本。
--- a/docs/数据库设计/4.Workflow数据库设计.md
+++ b/docs/数据库设计/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/docs/数据库设计/5.Agent会话数据库设计.md
+++ b/docs/数据库设计/5.Agent会话数据库设计.md
@@ -0,0 +1,32 @@
+# Agent 会话数据库设计
+
+## 1. 表结构
+
+| 表 | 说明 |
+|----|------|
+| `agent_definition` | Agent 定义 |
+| `agent_session` | Agent 会话 |
+| `agent_message` | Agent 消息 |
+| `agent_capability_binding` | 能力绑定 |
+
+## 2. 关键约束
+
+- `agent_definition.agent_code` 唯一。
+- `agent_session.session_code` 唯一。
+- `agent_session.agent_id` 引用 `agent_definition`。
+- `agent_session.workflow_run_id` 可引用 `workflow_run`。
+- `agent_message.session_id` 引用 `agent_session`。
+- `agent_capability_binding` 使用 `(owner_type, owner_id, capability_type, capability_id)` 唯一。
+
+## 3. JSON 字段
+
+- `agent_session.metadata_json` 保存会话扩展信息。
+- `agent_message.citation_json` 保存引用切片摘要。
+- `agent_capability_binding.config_json` 保存能力绑定配置。
+
+## 4. 脚本
+
+- `script/sql/agent_definition.sql`
+- `script/sql/agent_session.sql`
+- `script/sql/agent_capability_binding.sql`
+- `docs/STUDIO_PROTOTYPE_SCHEMA.sql`
--- a/docs/数据库设计/6.MCP数据库设计.md
+++ b/docs/数据库设计/6.MCP数据库设计.md
@@ -0,0 +1,20 @@
+# MCP 数据库设计
+
+## 1. 表结构
+
+| 表 | 说明 |
+|----|------|
+| `mcp_server` | MCP 服务配置 |
+| `mcp_capability` | MCP 能力清单 |
+
+## 2. 约束
+
+- `mcp_server.server_code` 唯一。
+- `mcp_capability` 使用 `(server_id, capability_code)` 唯一。
+- `mcp_capability.server_id` 引用 `mcp_server`。
+
+## 3. 脚本
+
+- `script/sql/mcp.sql`
+- `docs/STUDIO_PROTOTYPE_SCHEMA.sql`
+- `script/sql/studio_enum.sql`
--- a/docs/数据库设计/7.Skill数据库设计.md
+++ b/docs/数据库设计/7.Skill数据库设计.md
@@ -0,0 +1,20 @@
+# Skill 数据库设计
+
+## 1. 表结构
+
+| 表 | 说明 |
+|----|------|
+| `skill_definition` | Skill 定义 |
+| `skill_version` | Skill 版本 |
+
+## 2. 约束
+
+- `skill_definition.skill_code` 唯一。
+- `skill_version` 使用 `(skill_id, version_no)` 唯一。
+- `skill_version.skill_id` 引用 `skill_definition`。
+
+## 3. 脚本
+
+- `script/sql/skill.sql`
+- `docs/STUDIO_PROTOTYPE_SCHEMA.sql`
+- `script/sql/studio_enum.sql`
--- a/docs/数据库设计/8.运行观测数据库设计.md
+++ b/docs/数据库设计/8.运行观测数据库设计.md
@@ -0,0 +1,29 @@
+# 运行观测数据库设计
+
+## 1. 表范围
+
+运行观测复用已有运行表，不单独新增观测主表：
+
+- `workflow_run`
+- `workflow_run_step`
+- `model_call_log`
+- `agent_session`
+- `agent_message`
+
+## 2. 索引建议
+
+- `workflow_run.request_id`
+- `workflow_run.status`
+- `workflow_run_step.run_id`
+- `model_call_log.request_id`
+- `model_call_log.task_type`
+- `agent_session.agent_id`
+
+## 3. 脚本
+
+索引分散在：
+
+- `script/sql/workflow.sql`
+- `script/sql/model_provider.sql`
+- `script/sql/agent_session.sql`
+- `docs/STUDIO_PROTOTYPE_SCHEMA.sql`
--- a/docs/数据库设计/9.模块一致性校验.md
+++ b/docs/数据库设计/9.模块一致性校验.md
@@ -0,0 +1,79 @@
+# 模块一致性校验
+
+## 1. 校验范围
+
+本次校验覆盖：
+
+- `需求分析/`
+- `设计文档/`
+- `数据库设计/`
+- `前端实现文档/`
+- `后端实现文档/`
+- `script/sql/*.sql`
+- `docs/MODEL_PROVIDER_SCHEMA.sql`
+- `docs/STUDIO_PROTOTYPE_SCHEMA.sql`
+
+## 2. 文档占位检查
+
+已检查常见未决占位关键词，当前新增文档与 SQL 脚本中未保留未决占位。
+
+## 3. 数据库脚本一致性
+
+| 模块 | 汇总 schema | 模块化脚本 | 结论 |
+|------|-------------|------------|------|
+| 模型与路由 | `docs/MODEL_PROVIDER_SCHEMA.sql` | `script/sql/model_provider.sql` | 已补齐 `rag_store_model_config.store_id` 外键 |
+| Studio 项目 | `docs/STUDIO_PROTOTYPE_SCHEMA.sql` | `script/sql/studio_project.sql` | 表、唯一约束、索引一致 |
+| Workflow | `docs/STUDIO_PROTOTYPE_SCHEMA.sql` | `script/sql/workflow.sql` | 定义、版本、运行、步骤表一致 |
+| Agent 会话 | `docs/STUDIO_PROTOTYPE_SCHEMA.sql` | `script/sql/agent_session.sql` | 会话和消息表一致 |
+| 能力绑定 | `docs/STUDIO_PROTOTYPE_SCHEMA.sql` | `script/sql/agent_capability_binding.sql` | 唯一约束和索引一致 |
+| MCP | `docs/STUDIO_PROTOTYPE_SCHEMA.sql` | `script/sql/mcp.sql` | Server 与 Capability 表一致 |
+| Skill | `docs/STUDIO_PROTOTYPE_SCHEMA.sql` | `script/sql/skill.sql` | 定义与版本表一致 |
+
+## 4. 枚举一致性
+
+`script/sql/studio_enum.sql` 保持 `sys_enum` 既有格式：
+
+- `catalog`
+- `type`
+- `name`
+- `value`
+- `strvalue`
+- `sort`
+- `version`
+- `remark`
+
+校验结果：
+
+- 枚举行数：48。
+- 枚举组数：14。
+- 同一 `catalog + type` 下 `value` 无重复。
+- 同一 `catalog + type` 下 `sort` 无重复。
+
+## 5. 跨模块依赖检查
+
+| 依赖 | 结论 |
+|------|------|
+| 知识资产依赖系统附件 | `rag_document.attachment_id` 引用 `sys_attachment` 的设计保持不变 |
+| 知识资产依赖模型配置 | `rag_store_model_config` 连接 `rag_store` 与 `model_config` |
+| Workflow 依赖 Agent | `workflow_definition.bound_agent_id` 引用 `agent_definition` |
+| Workflow 运行依赖 Agent | `workflow_run.agent_id` 引用 `agent_definition` |
+| Agent 会话依赖 Workflow 运行 | `agent_session.workflow_run_id` 引用 `workflow_run` |
+| MCP/Skill 依赖能力绑定 | `agent_capability_binding` 通过类型和 ID 绑定能力 |
+| 运行观测依赖运行日志 | 复用 `workflow_run`、`workflow_run_step`、`model_call_log`、`agent_session` |
+
+## 6. 保留约束
+
+- 不修改 `sys_enum` 表结构。
+- 不修改 `PersistableSysEnumDefinition` 枚举契约。
+- 不把结构化枚举协议从整型值改为字符串值。
+- 本轮不修改 Java、Vue 或测试代码。
+
+## 7. 后续实现提示
+
+后续按文档重写代码时，新增 Java 枚举必须补齐：
+
+- Java 枚举类。
+- `SysEnumDataInitTests` 初始化入口。
+- `EnumDefinitionTests` 稳定性断言。
+- `script/sql/studio_enum.sql` 初始化数据。
+- 前端字典或常量映射。