126 lines
4.4 KiB
Markdown
126 lines
4.4 KiB
Markdown
# 枚举值传输与 SysEnum 同步设计
|
|
|
|
## 1. 背景
|
|
|
|
当前系统中存在两类问题：
|
|
|
|
1. 前后端针对长期固定的结构化字段，仍然传递字符串名称，例如 `chunkStrategy` 传 `"FIXED_LENGTH"`。
|
|
2. `sys_enum` 初始化依赖测试类中逐条 `saveOrUpdate(...)`，新增或修改枚举时需要手工同步多处，且不会清理同一 `catalog/type` 下的历史脏数据。
|
|
|
|
这会导致协议冗余、前后端约束不统一，以及数据库枚举配置可能与代码定义漂移。
|
|
|
|
## 2. 目标
|
|
|
|
本次改造需要达成以下目标：
|
|
|
|
- 长期固定的结构化文本字段，统一采用枚举值传输，不再传名称字符串。
|
|
- 后端 Java 枚举成为结构化枚举的单一事实来源。
|
|
- `sys_enum` 初始化机制支持按 `catalog + type` 分组，先删后全量重建。
|
|
- 前端展示继续使用中文文案，但请求协议只传枚举值。
|
|
- 新增或修改枚举后，只需改枚举类并运行统一测试，即可完成数据库同步。
|
|
|
|
## 3. 范围
|
|
|
|
本次纳入统一规范的枚举包括：
|
|
|
|
- `EnableStatusEnum`
|
|
- `CommonStatusEnum`
|
|
- `RagParseStatusEnum`
|
|
- `RagIndexStatusEnum`
|
|
- `RagChunkStrategyEnum`
|
|
|
|
本次同时把 `RagDocumentParseRequest.chunkStrategy` 从字符串协议改为数值协议。
|
|
|
|
## 4. 设计方案
|
|
|
|
### 4.1 后端枚举契约
|
|
|
|
新增一个统一的枚举定义接口，用于描述可同步到 `sys_enum` 的枚举项。接口提供：
|
|
|
|
- `getCatalog()`
|
|
- `getType()`
|
|
- `getName()`
|
|
- `getValue()`
|
|
- `getStrvalue()`
|
|
- `getSort()`
|
|
- `getRemark()`
|
|
|
|
上述五个现有枚举类统一实现该接口，使代码层直接具备落库所需信息。
|
|
|
|
### 4.2 枚举组唯一性
|
|
|
|
每一组枚举通过 `catalog + type` 唯一标识，例如：
|
|
|
|
- `common / enable_status`
|
|
- `common / common_status`
|
|
- `rag / parse_status`
|
|
- `rag / index_status`
|
|
- `rag / chunk_strategy`
|
|
|
|
系统要求不同枚举组之间 `catalog + type` 不能重复，否则无法安全执行“先删后全加”。
|
|
|
|
### 4.3 SysEnum 初始化机制
|
|
|
|
重写 `SysEnumDataInitTests` 的初始化方式：
|
|
|
|
1. 收集所有需要同步的枚举组。
|
|
2. 校验每个枚举组内部是否存在重复 `value`、重复 `sort`，以及不同组之间是否存在重复 `catalog + type`。
|
|
3. 对每个枚举组先按 `catalog + type` 删除数据库中的旧枚举。
|
|
4. 将当前代码定义的整组枚举全量写入 `sys_enum`。
|
|
|
|
这样可以保证数据库状态始终与当前代码一致，而不是增量叠加。
|
|
|
|
### 4.4 后端请求协议
|
|
|
|
`RagDocumentParseRequest.chunkStrategy` 改为 `Integer`，只接收枚举值。
|
|
|
|
同时为 `RagChunkStrategyEnum` 增加按值解析的方法，例如 `fromValue(Integer value)`，供服务层进行校验和转换。
|
|
|
|
`RagChunkCommand.chunkStrategy` 也同步改为 `Integer`，保持链路一致。
|
|
|
|
### 4.5 前端协议与展示
|
|
|
|
前端不再传字符串联合类型，而是改成数值枚举常量，例如：
|
|
|
|
- `FIXED_LENGTH = 1`
|
|
- `DELIMITER = 5`
|
|
|
|
页面中的单选项 `value` 使用数值，展示文案仍使用中文 `label`。提交请求时只传枚举值。
|
|
|
|
### 4.6 Agent 协作约定
|
|
|
|
在 `AGENT.md` 中新增长期规则：
|
|
|
|
- 对长期固定的结构化文本字段，统一采用枚举值传输。
|
|
- 枚举定义必须落在 Java 枚举类中。
|
|
- 枚举变更需要同步纳入 `sys_enum` 初始化测试。
|
|
- 每次新增或修改枚举后，需运行对应测试完成数据库同步。
|
|
|
|
## 5. 错误处理与边界
|
|
|
|
- 如果请求传入不存在的枚举值，后端直接抛出非法参数异常。
|
|
- 如果某个枚举组定义了重复 `value` 或重复 `sort`，初始化测试直接失败。
|
|
- 如果两个枚举组使用了相同的 `catalog + type`，初始化测试直接失败。
|
|
- 如果前端传入旧字符串协议，后端不做兼容，统一按新协议处理。
|
|
|
|
## 6. 测试策略
|
|
|
|
后端：
|
|
|
|
- 扩展 `EnumDefinitionTests`，验证关键枚举值稳定。
|
|
- 为 `RagDocumentParseServiceImplTests` 增加数值协议断言和非法值校验。
|
|
- 为新的 `sys_enum` 全量初始化逻辑增加单元测试，验证唯一性校验和重建行为。
|
|
|
|
前端：
|
|
|
|
- 更新 `RagDocumentsPage.spec.ts`，断言解析请求提交数值枚举值。
|
|
- 验证页面仍然展示中文切片名称。
|
|
|
|
## 7. 预期结果
|
|
|
|
改造完成后：
|
|
|
|
- 前后端结构化字段协议更紧凑、更稳定。
|
|
- 枚举定义、前端传值和数据库配置三者一致。
|
|
- 新增枚举时有固定流程，不再依赖手工增量补数据。
|