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

系统基础模块后端实现

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 业务服务。