feat(enum): 统一结构化枚举值传输与同步

AGENT.md

@@ -147,6 +147,35 @@
 6. OpenAPI 注解覆盖
    所有 Controller、DTO 使用 `@Tag`、`@Operation`、`@Schema` 注解。
 
+## 4.1 代码注释约定
+
+为方便后续多人协作和 Agent 接力阅读，新增以下约定：
+
+1. 新增或修改核心业务代码时，需要补充中文注释
+   注释优先覆盖类职责、关键方法、关键分支和重要参数含义，避免只写重复代码字面的无效注释。
+
+2. 每次提交代码时，同步检查对应改动是否已经补齐中文注释
+   尤其是新引入的工厂、策略、服务编排、状态流转和复杂转换逻辑，默认需要有中文说明。
+
+3. 注释以“帮助后来者快速理解设计意图”为目标
+   不追求注释数量，重点说明为什么这样做、边界是什么、哪些地方后续还会扩展。
+
+## 4.2 结构化枚举约定
+
+为保证前后端协议、代码定义和数据库配置一致，新增以下长期规则：
+
+1. 长期固定的结构化文本字段，统一采用枚举值传输
+   不再以字符串名称作为接口协议值，前后端统一传整型枚举值。
+
+2. 这类枚举必须先定义为 Java 枚举类
+   Java 枚举类作为单一事实来源，再派生前端常量和 `sys_enum` 配置。
+
+3. 每次新增或修改结构化枚举时，必须同步纳入 `sys_enum` 初始化测试
+   通过统一测试入口按 `catalog + type` 先删后全量重建，避免数据库枚举配置漂移。
+
+4. `catalog + type` 在枚举组层面必须唯一
+   一旦重复，会破坏枚举组重建语义，因此视为非法设计。
+
 ## 5. 数据与存储设计
 
 ### 5.1 关系型数据库