# 枚举值传输与 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. 预期结果

改造完成后：

- 前后端结构化字段协议更紧凑、更稳定。
- 枚举定义、前端传值和数据库配置三者一致。
- 新增枚举时有固定流程，不再依赖手工增量补数据。