From 14e444e4bd44b2d335e176d2358af6354e22ccf8 Mon Sep 17 00:00:00 2001 From: AprilWind <2100166581@qq.com> Date: Fri, 15 May 2026 13:59:44 +0800 Subject: [PATCH] =?UTF-8?q?update=20=E6=96=B0=E5=A2=9E=E5=85=AC=E5=85=B1?= =?UTF-8?q?=E5=9F=BA=E7=A1=80=E6=A8=A1=E5=9D=97=E6=96=87=E6=A1=A3=EF=BC=8C?= =?UTF-8?q?=E6=98=8E=E7=A1=AE=E5=A2=9E=E9=87=8F=E4=BF=AE=E6=94=B9=E5=8E=9F?= =?UTF-8?q?=E5=88=99=E4=B8=8E=E6=8E=A5=E5=8F=A3=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../agents/backend-common-infrastructure.md | 42 +++++++++++++++++++ .claude/agents/backend-crud.md | 8 ++++ .claude/agents/backend-engineering.md | 9 +++- .claude/agents/backend-javadoc.md | 42 +++++++++++++++++++ .claude/agents/backend-module-enhancement.md | 6 +++ .claude/agents/backend-query-permission.md | 14 +++++++ 6 files changed, 119 insertions(+), 2 deletions(-) create mode 100644 .claude/agents/backend-common-infrastructure.md create mode 100644 .claude/agents/backend-javadoc.md diff --git a/.claude/agents/backend-common-infrastructure.md b/.claude/agents/backend-common-infrastructure.md new file mode 100644 index 000000000..3e5a77fc7 --- /dev/null +++ b/.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` 并标注 `@TranslationType(type = ...)`。 +- 批量翻译优先实现 `translationBatch(Set 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 的参数、返回值和兼容语义。 diff --git a/.claude/agents/backend-crud.md b/.claude/agents/backend-crud.md index 26d732bf8..6da0b453d 100644 --- a/.claude/agents/backend-crud.md +++ b/.claude/agents/backend-crud.md @@ -15,9 +15,11 @@ description: 标准后端 CRUD 专家。用于当前项目中的新增单表 CRU ## 结构约定 - entity 默认继承 `BaseEntity` +- entity 使用 `@TableName`，主键使用 `@TableId`；存在 `delFlag`、乐观锁字段时保留 `@TableLogic`、`@Version` - mapper 默认继承 `BaseMapperPlus` - 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` +- 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` 如需同步，接口路径、返回结构、日期范围参数要与后端一致 diff --git a/.claude/agents/backend-engineering.md b/.claude/agents/backend-engineering.md index 440d1bfc5..59efb4daf 100644 --- a/.claude/agents/backend-engineering.md +++ b/.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 前先查调用点；公共模块优先保持方法签名、泛型、返回值和异常语义兼容。 diff --git a/.claude/agents/backend-javadoc.md b/.claude/agents/backend-javadoc.md new file mode 100644 index 000000000..a65d7b99d --- /dev/null +++ b/.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 是否和当前实现一致。 diff --git a/.claude/agents/backend-module-enhancement.md b/.claude/agents/backend-module-enhancement.md index 440a8f48e..fe25515e2 100644 --- a/.claude/agents/backend-module-enhancement.md +++ b/.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` 批量查询规则 ## 自检 - 是否破坏了原模块的权限边界 - 是否误删了旧逻辑中的事务或校验 - 是否错误简化了复杂关系维护 +- 是否漏掉缓存失效、导入导出回执、翻译字段、前端调用路径等联动点 diff --git a/.claude/agents/backend-query-permission.md b/.claude/agents/backend-query-permission.md index 6bd741d7d..c801d598c 100644 --- a/.claude/agents/backend-query-permission.md +++ b/.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 风格一致 - 不要让查询参数风格和前端现有调用脱节 +- 不要为了“易读”移除已有数据权限、角色状态、删除标识过滤