# 系统基础模块需求

## 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/1.enum.sql`、`script/sql/2.attachment.sql`
- 后端入口：`SysEnumController`、`SysAttachmentController`、`DocumentParserFactory`
- 前端入口：系统枚举 API、文件上传组件、枚举字典调用