From 1002380b287c8e868bc2eff832af6c5cb52c55d2 Mon Sep 17 00:00:00 2001
From: bruce <sunzhiye01@outlook.com>
Date: Mon, 1 Jun 2026 00:46:38 +0800
Subject: [PATCH] =?UTF-8?q?docs(common):=20=E8=A1=A5=E5=85=A8=E7=B3=BB?=
 =?UTF-8?q?=E7=BB=9F=E5=9F=BA=E7=A1=80=E8=AE=BE=E8=AE=A1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 前端实现文档/1.系统基础模块前端实现.md | 28 ++++++++++++++++++
 后端实现文档/1.系统基础模块后端实现.md | 39 ++++++++++++++++++++++++++
 设计文档/1.系统基础模块设计.md         | 32 +++++++++++++++++++++
 需求分析/1.系统基础模块需求.md         | 38 +++++++++++++++++++++++++
 4 files changed, 137 insertions(+)
 create mode 100644 前端实现文档/1.系统基础模块前端实现.md
 create mode 100644 后端实现文档/1.系统基础模块后端实现.md
 create mode 100644 设计文档/1.系统基础模块设计.md
 create mode 100644 需求分析/1.系统基础模块需求.md

diff --git a/前端实现文档/1.系统基础模块前端实现.md b/前端实现文档/1.系统基础模块前端实现.md
new file mode 100644
index 0000000..b40b7d5
--- /dev/null
+++ b/前端实现文档/1.系统基础模块前端实现.md
@@ -0,0 +1,28 @@
+# 系统基础模块前端实现
+
+## 1. 页面范围
+
+系统基础前端能力主要体现为枚举字典、上传控件和统一请求处理。当前已有系统枚举管理页，后续 Studio 页面继续复用这些能力。
+
+## 2. API 使用
+
+| 能力 | 接口 |
+|------|------|
+| 枚举管理查询 | `POST /api/sys-enum/queryForManagement` |
+| 枚举详情 | `GET /api/sys-enum/detail` |
+| 枚举保存 | `POST /api/sys-enum/save` |
+| 枚举删除 | `POST /api/sys-enum/delete` |
+| 附件上传 | `POST /api/attachments/upload` |
+
+## 3. 实现约定
+
+- API 层继续使用 `frontend/src/api/request.ts` 解包 `RequestResult<T>`。
+- Long ID 继续通过 `json-bigint` 安全解析。
+- 枚举展示通过字典或本地常量映射，不直接依赖数据库展示顺序。
+- 上传失败时展示后端错误摘要，不吞掉异常。
+
+## 4. Studio 复用点
+
+- 文件解析管道复用附件上传能力。
+- 知识资产、模型路由、Workflow、Agent 等页面复用枚举字典。
+- 运行观测页面复用统一状态颜色和错误提示格式。
diff --git a/后端实现文档/1.系统基础模块后端实现.md b/后端实现文档/1.系统基础模块后端实现.md
new file mode 100644
index 0000000..d5a76bd
--- /dev/null
+++ b/后端实现文档/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 业务服务。
diff --git a/设计文档/1.系统基础模块设计.md b/设计文档/1.系统基础模块设计.md
new file mode 100644
index 0000000..d700c8f
--- /dev/null
+++ b/设计文档/1.系统基础模块设计.md
@@ -0,0 +1,32 @@
+# 系统基础模块设计
+
+## 1. 模块边界
+
+系统基础模块不承载具体 AI 业务逻辑，只提供跨模块复用能力。知识资产、模型路由、Workflow、Agent、MCP、Skill 和观测模块都可以依赖它。
+
+## 2. 核心对象
+
+| 对象 | 说明 |
+|------|------|
+| `SysEnum` | 系统枚举配置，面向前端字典和初始化脚本 |
+| `SysAttachment` | 附件元数据，保存文件名称、路径、来源和大小 |
+| `BaseEntity` | 主键、审计字段、乐观锁字段 |
+| `RequestResult<T>` | 统一 API 响应信封 |
+| `DocumentParser` | 文档文本抽取接口 |
+| `DocumentParserFactory` | 根据文件类型选择解析器 |
+
+## 3. 枚举设计原则
+
+结构化枚举继续以 Java 枚举为单一事实来源。Java 枚举实现 `PersistableSysEnumDefinition`，暴露 `catalog`、`type`、`name`、`value`、`strvalue`、`sort` 和 `remark`。
+
+`sys_enum` 表结构不变，新增 Studio 枚举只能新增枚举组或枚举行，不能调整原字段含义。
+
+## 4. 状态与错误
+
+- 业务启停用统一使用 `EnableStatusEnum` 或模块自有状态。
+- 长流程处理状态使用模块自有枚举，但必须同步到 `sys_enum`。
+- 全局异常处理将校验错误转换为统一响应。
+
+## 5. 依赖关系
+
+系统基础模块不能依赖其他业务模块。业务模块可依赖系统基础模块的枚举、附件、解析、返回体和异常处理。
diff --git a/需求分析/1.系统基础模块需求.md b/需求分析/1.系统基础模块需求.md
new file mode 100644
index 0000000..ff665a9
--- /dev/null
+++ b/需求分析/1.系统基础模块需求.md
@@ -0,0 +1,38 @@
+# 系统基础模块需求
+
+## 1. 模块目标
+
+系统基础模块为 Common Agent Studio 提供所有产品域共用的底座能力，包括系统枚举、附件上传、审计字段、统一响应、文档解析抽象和全局异常处理。
+
+## 2. 用户角色
+
+| 角色 | 诉求 |
+|------|------|
+| 平台管理员 | 维护系统枚举、检查附件上传和基础配置 |
+| 开发者 | 复用统一 DTO、返回体、审计字段和解析能力 |
+| 前端开发者 | 使用一致的枚举字典和错误响应 |
+| 运维人员 | 通过统一字段排查创建人、更新时间和异常信息 |
+
+## 3. 功能需求
+
+1. 系统枚举必须支持按 `catalog + type` 查询，用于前端字典、后台管理和初始化校验。
+2. `sys_enum` 结构必须保持现状，不因 Studio 新增模块调整字段格式。
+3. 附件模块必须支持本地上传、元数据入库和业务来源关联。
+4. 文档解析抽象必须支持 TXT/Markdown/LOG、PDF、Word、Excel 的文本抽取。
+5. 所有业务接口继续返回 `RequestResult<T>`。
+6. 所有业务实体继续继承公共审计字段和乐观锁字段。
+
+## 4. 非功能需求
+
+- 枚举值稳定，不能随展示文案调整而改变。
+- 附件路径不直接暴露为外部可访问地址。
+- 异常响应保持统一结构，便于前端统一提示。
+- 文档解析失败必须返回可定位的错误摘要。
+
+## 5. 关联资料
+
+- 表：`sys_enum`、`sys_attachment`
+- 枚举：`common/enable_status`、`common/common_status`
+- 脚本：`script/sql/enum.sql`、`script/sql/attachment.sql`
+- 后端入口：`SysEnumController`、`SysAttachmentController`、`DocumentParserFactory`
+- 前端入口：系统枚举 API、文件上传组件、枚举字典调用