# 系统基础模块设计

## 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. 依赖关系

系统基础模块不能依赖其他业务模块。业务模块可依赖系统基础模块的枚举、附件、解析、返回体和异常处理。