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

docs/后端实现文档/0.后端模块总览.md

@@ -0,0 +1,36 @@
+# 后端模块总览
+
+## 1. 当前代码边界
+
+当前后端已有 `common`、`rag`、`modelprovider`、`agent` 包。后续重新实现时，可以保留这些包作为技术分层落点，但业务文档按产品域拆分。
+
+## 2. 后端实现原则
+
+- Controller 不直接暴露实体。
+- 请求使用 `XxxRequest`，响应使用 `XxxResponse`。
+- 统一返回 `RequestResult<T>`。
+- 实体继承 `BaseEntity`，保持审计字段和乐观锁字段。
+- Mapper 继续使用 MyBatis-Plus `BaseMapper<T>`。
+- 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` 或对应模块枚举脚本。
+- 前端枚举常量或字典接口。

docs/后端实现文档/1.系统基础模块后端实现.md

@@ -0,0 +1,39 @@
+# 系统基础模块后端实现
+
+## 1. 包结构
+
+当前实现位于 `com.bruce.common`：
+
+- `controller`：枚举和附件 API。
+- `domain/entity`：`SysEnum`、`SysAttachment`。
+- `domain/model`：`BaseEntity`、`RequestResult`。
+- `document/parse`：文档解析抽象和 Tika 实现。
+- `enums`：通用枚举与可持久化枚举契约。
+- `service`：枚举与附件服务。
+
+## 2. Controller 约定
+
+Controller 只接收请求 DTO 或基础参数，不直接暴露实体。响应统一使用 `RequestResult<T>`。
+
+## 3. Service 约定
+
+`SysEnumService` 负责：
+
+- 管理端查询。
+- 单条保存和删除。
+- 批量保存。
+- 按 `catalog + type` 全量替换初始化。
+
+`SysAttachmentService` 负责：
+
+- 校验上传文件。
+- 生成存储路径。
+- 保存本地文件。
+- 写入附件元数据。
+
+## 4. 后续实现注意
+
+- 不调整 `PersistableSysEnumDefinition` 现有方法。
+- 不调整 `sys_enum` 表字段。
+- 新增枚举时同步初始化测试和 SQL 初始化脚本。
+- 文档解析器新增类型时，只扩展解析器实现和工厂注册，不影响 RAG 业务服务。

docs/后端实现文档/2.知识资产与文件解析模块后端实现.md

@@ -0,0 +1,39 @@
+# 知识资产与文件解析模块后端实现
+
+## 1. 当前实现落点
+
+当前实现位于 `com.bruce.rag`，包含知识库、文档、解析、切片和向量实体。
+
+## 2. Controller
+
+已落地接口继续保留：
+
+- `/api/rag/store/list`
+- `/api/rag/store/query`
+- `/api/rag/store/detail`
+- `/api/rag/store/overview`
+- `/api/rag/store/documentOverview`
+- `/api/rag/documents/query`
+- `/api/rag/documents/batchUpload`
+- `/api/rag/documents/parse`
+- `/api/rag/documents/chunk`
+
+Studio 聚合接口后续新增在知识资产模块，不替代旧接口。
+
+## 3. Service
+
+| Service | 职责 |
+|---------|------|
+| `IRagStoreService` | 知识库 CRUD、概览统计 |
+| `IRagDocumentService` | 文档 CRUD、批量上传 |
+| `IRagDocumentParseService` | 解析状态流转和解析快照 |
+| `IRagDocumentChunkService` | 根据解析快照生成切片 |
+| `IRagChunkEmbeddingService` | 向量写入和召回 |
+
+## 4. 校验规则
+
+- 知识库编码唯一。
+- 文档必须绑定存在的知识库和附件。
+- 只有解析成功的文档允许切片。
+- 向量化必须读取知识库生效模型配置。
+- 重新切片或模型变更后，索引状态必须回到待索引或索引中。

docs/后端实现文档/3.模型与路由模块后端实现.md

@@ -0,0 +1,41 @@
+# 模型与路由模块后端实现
+
+## 1. 当前实现落点
+
+当前实现位于 `com.bruce.modelprovider`，包含服务商、模型、路由、网关、客户端和调用日志。
+
+## 2. Controller
+
+- `ModelProviderController`
+- `ModelConfigController`
+- `ModelRouteRuleController`
+- `RagStoreModelConfigController`
+- `ModelCallLogController`
+
+## 3. Service
+
+| Service | 职责 |
+|---------|------|
+| `IModelProviderService` | 服务商 CRUD 和健康检查 |
+| `IModelConfigService` | 模型配置 CRUD |
+| `IModelRouteRuleService` | 路由规则 CRUD |
+| `IModelRouteService` | 根据任务上下文选择模型 |
+| `IRagStoreModelConfigService` | 知识库模型绑定 |
+| `IModelCallLogService` | 调用日志写入与查询 |
+
+## 4. 网关
+
+业务模块只能依赖：
+
+- `ChatModelGateway`
+- `EmbeddingModelGateway`
+
+不得直接依赖具体上游客户端。
+
+## 5. 校验规则
+
+- 服务商编码唯一。
+- 同一服务商下模型编码唯一。
+- 路由主模型必须启用。
+- 路由任务类型必须来自枚举。
+- 知识库 Embedding 维度必须与模型配置一致。

docs/后端实现文档/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 节点必须配置知识库或继承项目默认知识库。

docs/后端实现文档/5.Agent会话模块后端实现.md

@@ -0,0 +1,29 @@
+# Agent 会话模块后端实现
+
+## 1. 当前实现落点
+
+当前 Agent 定义和调试入口位于 `com.bruce.agent`。后续会话能力建议继续放在该包下。
+
+## 2. Controller 草案
+
+- `AgentDefinitionController`：保留定义管理和兼容调试入口。
+- `AgentSessionController`：新增会话查询、详情和消息发送。
+- `AgentRunController`：新增运行入口，关联 Workflow 或模型调用。
+
+## 3. Service 草案
+
+| Service | 职责 |
+|---------|------|
+| `IAgentDefinitionService` | Agent 定义管理 |
+| `IAgentSessionService` | 会话创建、关闭、查询 |
+| `IAgentMessageService` | 消息写入和引用保存 |
+| `IAgentRunService` | 对话编排、RAG 召回、模型调用 |
+| `IAgentCapabilityBindingService` | 能力绑定维护 |
+
+## 4. 校验规则
+
+- Agent 必须启用才允许发起对话。
+- RAG 对话必须绑定可用知识库和 Embedding 配置。
+- 消息内容不能为空。
+- `citation_json` 必须是数组结构。
+- 会话关闭后不允许继续写入消息。

docs/后端实现文档/6.MCP能力接入模块后端实现.md

@@ -0,0 +1,20 @@
+# MCP 能力接入模块后端实现
+
+## 1. 包建议
+
+后续实现建议新增 `com.bruce.mcp`，包含 Controller、DTO、Entity、Mapper、Service 和 MCP Client 适配。
+
+## 2. Service 草案
+
+| Service | 职责 |
+|---------|------|
+| `IMcpServerService` | Server 导入、启停用、健康检查 |
+| `IMcpCapabilityService` | 能力发现、保存、启停用 |
+| `IMcpImportService` | 处理 URL、package、Manifest 导入 |
+
+## 3. 校验规则
+
+- Server 编码唯一。
+- 能力编码在 Server 下唯一。
+- 导入方式必须来自枚举。
+- 能力 schema 必须为合法 JSON。

docs/后端实现文档/7.Skill编辑模块后端实现.md

@@ -0,0 +1,20 @@
+# Skill 编辑模块后端实现
+
+## 1. 包建议
+
+后续实现建议新增 `com.bruce.skill`。
+
+## 2. Service 草案
+
+| Service | 职责 |
+|---------|------|
+| `ISkillDefinitionService` | Skill 定义管理 |
+| `ISkillVersionService` | 草稿保存、测试、发布、归档 |
+| `ISkillRunner` | 运行 Skill 并生成测试结果 |
+
+## 3. 校验规则
+
+- Skill 编码唯一。
+- 版本号在 Skill 内唯一。
+- Prompt、Code、Config 至少一种非空。
+- 变量 schema 必须为合法 JSON。

docs/后端实现文档/8.运行观测模块后端实现.md

@@ -0,0 +1,24 @@
+# 运行观测模块后端实现
+
+## 1. 包建议
+
+后续实现可新增 `com.bruce.observability`，也可以先由 Workflow、Agent 和模型模块分别提供查询接口。
+
+## 2. Controller 草案
+
+- `ObservabilityRunController`
+- `ObservabilityModelCallController`
+
+## 3. Service 草案
+
+| Service | 职责 |
+|---------|------|
+| `IObservabilityRunService` | 聚合运行记录 |
+| `IObservabilityTraceService` | 聚合步骤、会话和模型调用 |
+| `IObservabilityExportService` | 导出脱敏日志 |
+
+## 4. 校验规则
+
+- 只允许查询脱敏后的运行摘要。
+- 导出接口必须过滤密钥和完整请求内容。
+- requestId 不存在时返回空结果而不是内部异常。