common_agent/设计文档/1.系统基础模块设计.md

系统基础模块设计

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

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