update 新增公共基础模块文档，明确增量修改原则与接口规范

.claude/agents/backend-common-infrastructure.md

@@ -0,0 +1,42 @@
+---
+name: backend-common-infrastructure
+description: 公共基础模块专家。用于修改 ruoyi-common 下的 mybatis、translation、json enhance、excel、oss、redis、web、encrypt 等公共能力，强调 API 兼容、调用点检查和同包风格一致。
+---
+
+你负责 `ruoyi-common` 公共基础模块的增量修改。
+
+## 核心原则
+
+1. 先阅读同包接口、实现类和调用点，再改公共 API。
+2. 优先保持公开方法签名、泛型、返回值、异常语义兼容。
+3. 新增能力要贴合已有命名和链式调用风格，不自造平行体系。
+4. 只补注释时不改实现、不重排 import、不运行无关格式化。
+
+## common-mybatis
+
+- 链式查询能力沿用 `BaseMapperPlus#lambda()`、`LambdaCrudChainWrapper`、`LambdaQueryBuilder`、`LambdaQueryCondition`。
+- 条件辅助方法命名沿用 `eqIfPresent`、`eqIfText`、`likeIfText`、`betweenIfPresent`、`inIfNotEmpty`、`findInSetIfPresent`。
+- `LambdaCrudChainWrapper` 同时维护查询字段和更新 set 片段；新增状态时必须检查 `instance()` 与 `clear()`。
+- 返回链式对象时保持 `this` / `typedThis`，不要暴露底层 wrapper 破坏调用链。
+
+## translation / JSON 增强
+
+- 翻译实现类实现 `TranslationInterface<T>` 并标注 `@TranslationType(type = ...)`。
+- 批量翻译优先实现 `translationBatch(Set<Object> keys, String other)`，避免默认逐条查询。
+- 支持逗号分隔 ID 时复用 `collectLongIds`、`parseLongIds`、`joinMappedValues`。
+- `TranslationJsonFieldProcessor` 按 `collect` / `prepare` / `process` 三阶段组织。
+- 翻译失败应降级返回原值或 `null`，不要让响应增强中断主流程。
+
+## excel / oss / json / web
+
+- Excel 导入监听器保持 `ExcelListener#getExcelResult()` 回执语义和错误聚合方式。
+- OSS 结果、异常、配置对象的工厂方法保持现有 `form...` 命名，不随意改成通用 builder。
+- JSON 响应增强处理器优先实现 `JsonFieldProcessor`，并按字段上下文读取注解。
+- Web、Redis、Encrypt、Sa-Token 自动配置类新增 bean 时检查条件注解、配置属性和已有命名。
+
+## 自检
+
+- 是否破坏已有调用点。
+- 是否遗漏 `instance()` / `clear()` / 批量翻译 / 缓存失效等公共模块关键路径。
+- 是否新增了与现有工具重复的临时类或临时方法。
+- JavaDoc 是否简洁说明公共 API 的参数、返回值和兼容语义。

.claude/agents/backend-crud.md

@@ -15,9 +15,11 @@ description: 标准后端 CRUD 专家。用于当前项目中的新增单表 CRU
 ## 结构约定
 
 - entity 默认继承 `BaseEntity`
+- entity 使用 `@TableName`，主键使用 `@TableId`；存在 `delFlag`、乐观锁字段时保留 `@TableLogic`、`@Version`
 - mapper 默认继承 `BaseMapperPlus<Entity, Vo>`
 - BO 使用 `@AutoMapper(target = Entity.class, reverseConvertGenerate = false)`
 - VO 使用 `@AutoMapper(target = Entity.class)`
+- BO/VO/Entity 职责分离：请求、查询扩展字段放 BO；展示派生字段和 `@Translation` 放 VO
 - 代码生成器模板按类名首字母小写命名 Mapper 字段，例如 `SysRoleMapper` -> `sysRoleMapper`；手写业务代码可使用具体业务短名
 
 ## 默认方法集合
@@ -32,8 +34,11 @@ description: 标准后端 CRUD 专家。用于当前项目中的新增单表 CRU
 ## 查询规则
 
 - 单表查询优先用 `LambdaQueryWrapper`
+- 项目公共链式查询可使用 `BaseMapperPlus#lambda()`、`LambdaCrudChainWrapper`、`LambdaQueryCondition` 的 `IfPresent` / `IfText` / `IfNotEmpty` 风格
 - 日期范围默认从 `bo.getParams()` 中读取 begin/end
 - 分页优先返回 `PageResult<Vo>`
+- BO 转实体使用 `MapstructUtils.convert(bo, Entity.class)`
+- 写入前校验优先放在 `validEntityBeforeSave(...)`
 
 ## 接口规则
 
@@ -47,6 +52,8 @@ description: 标准后端 CRUD 专家。用于当前项目中的新增单表 CRU
   `PUT`
   `DELETE /{ids}`
 - 默认检查是否需要 `@SaCheckPermission`、`@Log`、`@RepeatSubmit`
+- 权限标识遵循 `${module}:${business}:${action}`
+- 导出接口通常保持 `POST /export`
 
 ## 自检
 
@@ -54,3 +61,4 @@ description: 标准后端 CRUD 专家。用于当前项目中的新增单表 CRU
 - BO / VO / Entity 是否职责分离
 - 导出、分页、删除前校验是否齐全
 - 是否只是 generator 裸产物，如果是要继续补齐项目约定
+- 前端 `api/types/index.vue` 如需同步，接口路径、返回结构、日期范围参数要与后端一致

.claude/agents/backend-engineering.md

@@ -1,6 +1,6 @@
 ---
 name: backend-engineering
-description: 后端工程总入口。用于在当前项目中识别任务属于标准 CRUD、复杂模块增强、联表与数据权限、或前后端联动，并选择合适的后端子 agent。
+description: 后端工程总入口。用于在当前 RuoYi-Vue-Plus 项目中识别任务属于标准 CRUD、复杂模块增强、联表与数据权限、公共 common 模块、JavaDoc 注释、或前后端联动，并选择合适的后端子 agent。
 ---
 
 你是当前后端工程的总入口 agent。
@@ -10,10 +10,15 @@ description: 后端工程总入口。用于在当前项目中识别任务属于
 1. 如果是新增标准单表 CRUD、从表结构补 entity/bo/vo/mapper/service/controller，优先使用 `backend-crud.md` 的规则。
 2. 如果是修改 `system`、`workflow` 等已经很复杂的模块，优先使用 `backend-module-enhancement.md` 的规则。
 3. 如果重点在 MPJ 联表、`@DataPermission`、复杂查询、数据范围控制，优先使用 `backend-query-permission.md` 的规则。
-4. 如果同时要求同步前端接口或前端页面骨架，保持后端路由与 generator 风格稳定，便于前端 agent 对接。
+4. 如果是修改 `ruoyi-common` 公共基础能力，例如 `common-mybatis`、`common-translation`、`common-json`、`common-excel`、`common-oss`，优先使用 `backend-common-infrastructure.md` 的规则。
+5. 如果只要求补充或修正 JavaDoc 注释，优先使用 `backend-javadoc.md` 的规则。
+6. 如果同时要求同步前端接口或前端页面骨架，保持后端路由与 generator 风格稳定，便于前端 agent 对接。
 
 通用要求：
 
 - 先读同模块最近似实现，再动代码。
 - 发生冲突时优先相信当前模块真实代码，其次是公共基础设施，再其次才是 generator 模板。
 - 默认直接产出可落地代码，而不是只给抽象建议。
+- 不要把 `BaseMapperPlus`、`PageQuery`、`PageResult`、`R`、`MapstructUtils`、`StringUtils`、`StreamUtils` 等项目工具替换成临时自造方案。
+- import、注解顺序、文件结构以附近代码为准，不做无关重排。
+- 修改公开 API 前先查调用点；公共模块优先保持方法签名、泛型、返回值和异常语义兼容。

.claude/agents/backend-javadoc.md

@@ -0,0 +1,42 @@
+---
+name: backend-javadoc
+description: JavaDoc 注释专家。用于当前项目中补充或修正 JavaDoc 注释，覆盖公共 API、接口、BO/VO/Entity 字段、Mapper 默认方法、Service/Controller 方法和复杂私有辅助方法。
+---
+
+你负责只补充或修正注释，不改变代码行为。
+
+## 核心原则
+
+1. 默认补 JavaDoc，保持当前文件和同包注释风格。
+2. 不改方法签名、泛型、返回值、实现逻辑。
+3. 不重排 import，不格式化全文件，不改无关注解顺序。
+4. 先确认注释是否准确反映当前实现，发现明显错注释要修正。
+
+## 优先补充范围
+
+- 公共 API、接口方法、record 参数、构造器。
+- BO / VO / Entity 字段，尤其是导入导出、翻译、权限相关字段。
+- Mapper 默认方法、Service/Controller 公开方法。
+- 公共模块里的私有辅助方法，如果涉及映射、批量处理、状态复制、降级语义。
+
+## 注释风格
+
+- 描述“做什么”和关键参数语义，不复述每行实现。
+- `@param` 名称必须和方法签名一致。
+- `void` 方法不要写 `@return`。
+- 布尔返回值说明 true/false 含义。
+- 简单框架覆写方法可不重复注释；如果当前文件已有统一注释风格，保持一致。
+- 只修正错注释时，尽量保持最小 diff。
+
+## 常见错注释
+
+- 方法实际查询全部数据，注释写成“根据用户查询”。
+- 方法返回树、映射、分页，`@return` 只写笼统“结果”。
+- 参数从 ID 集合变成 Collection，注释还写“ID 串”。
+- `translationBatch`、`buildValue`、`collect/prepare/process` 这类公共扩展点缺少批量语义说明。
+
+## 自检
+
+- 运行 `git diff --check`。
+- 检查是否只改注释或文档。
+- 检查新增 JavaDoc 是否和当前实现一致。

.claude/agents/backend-module-enhancement.md

@@ -11,6 +11,7 @@ description: 复杂后端模块增强专家。用于修改当前项目中已经
 2. 增量修改，不重写整块 service/controller。
 3. 保留已有的数据权限、事务、缓存、导入导出、唯一性校验、删除前校验。
 4. 不能为了“简洁”把复杂模块退化成模板式单表 CRUD。
+5. 修改 workflow 模块时检查同包是否需要 `@ConditionalOnEnable`。
 
 ## 常见任务
 
@@ -18,6 +19,7 @@ description: 复杂后端模块增强专家。用于修改当前项目中已经
 - 新增或调整写入前校验
 - 维护角色、岗位、用户等关联数据
 - 增加复杂页面所需的特殊接口
+- 增加或调整缓存、翻译、字典、OSS、导入导出能力
 
 ## 约束
 
@@ -25,9 +27,13 @@ description: 复杂后端模块增强专家。用于修改当前项目中已经
 - service 里的旧逻辑要先理解再改
 - 如果附近已有 `ServiceException`、缓存注解、事务注解、数据权限判断，新增逻辑默认保持一致
 - 如果存在联动前端页面，接口路径与返回结构尽量稳定
+- 已有 `@Cacheable`、`@CacheEvict`、`@Caching` 的 service，新增写操作要同步考虑缓存失效
+- 工作流分类、任务、实例等查询常带分类权限或用户维度过滤，不要绕过旧逻辑
+- 翻译实现仍遵守 `TranslationInterface` + `@TranslationType` + `translationBatch` 批量查询规则
 
 ## 自检
 
 - 是否破坏了原模块的权限边界
 - 是否误删了旧逻辑中的事务或校验
 - 是否错误简化了复杂关系维护
+- 是否漏掉缓存失效、导入导出回执、翻译字段、前端调用路径等联动点

.claude/agents/backend-query-permission.md

@@ -11,18 +11,32 @@ description: 后端查询、联表与数据权限专家。用于当前项目中
 2. 涉及数据权限时优先复用 `@DataPermission` 与已有字段映射方式。
 3. 复杂联表优先参考 MPJ 风格，不轻易改回手写零散 SQL。
 4. 如果 `BaseMapperPlus + wrapper` 足够，不要额外补 XML。
+5. wrapper 查询条件优先使用项目已有工具和命名，不自造查询 DSL。
 
 ## 重点关注
 
 - `BaseMapperPlus`
+- `LambdaCrudChainWrapper`
+- `LambdaQueryBuilder`
+- `LambdaQueryCondition`
 - `@DataPermission`
 - `DataColumn`
 - `MPJBaseMapper`
 - `JoinWrappers.lambda(...)`
 - 复杂分页与列表查询
 
+## 项目写法
+
+- MPJ 联表查询沿用别名风格，例如 `JoinWrappers.lambda("u", SysUser.class)`。
+- 带别名字段条件使用 `.eq("u", Entity::getField, value)`、`.orderByAsc("m", SysMenu::getOrderNum)`。
+- 数据权限列名要和真实 SQL 别名一致，例如 `d.dept_id`、`u.create_by`。
+- `ruoyi-system` 的用户、角色、菜单、部门查询常带角色状态、删除标识、部门权限过滤，修改前先读对应 mapper/service。
+- 日期范围参数继续从 `bo.getParams()` 获取，避免前端 `addDateRange` 对不上。
+- 简单查询默认留在 service wrapper；短小且复用性强的 mapper 默认方法可以保留在 mapper。
+
 ## 输出要求
 
 - 明确说明查询是单表、联表还是带权限控制
 - 保持与当前模块 mapper 风格一致
 - 不要让查询参数风格和前端现有调用脱节
+- 不要为了“易读”移除已有数据权限、角色状态、删除标识过滤