diff --git a/.claude/agents/backend-common-infrastructure.md b/.claude/agents/backend-common-infrastructure.md index 3e5a77fc7..3e1c3d60f 100644 --- a/.claude/agents/backend-common-infrastructure.md +++ b/.claude/agents/backend-common-infrastructure.md @@ -14,8 +14,8 @@ description: 公共基础模块专家。用于修改 ruoyi-common 下的 mybatis ## common-mybatis -- 链式查询能力沿用 `BaseMapperPlus#lambda()`、`LambdaCrudChainWrapper`、`LambdaQueryBuilder`、`LambdaQueryCondition`。 -- 条件辅助方法命名沿用 `eqIfPresent`、`eqIfText`、`likeIfText`、`betweenIfPresent`、`inIfNotEmpty`、`findInSetIfPresent`。 +- 链式查询能力沿用 `QueryBuilder.lambda(...)`、`QueryBuilder.lambdaJoin(...)`、`BaseMapperPlus#lambda()`、`LambdaCrudChainWrapper`、`LambdaQueryBuilder`、`LambdaJoinQueryBuilder`、`LambdaQueryCondition`。 +- 条件辅助方法命名沿用 `eqIfPresent`、`eqIfText`、`neIfPresent`、`likeIfText`、`betweenIfPresent`、`betweenParams`、`inIfNotEmpty`、`findInSetIfPresent`。 - `LambdaCrudChainWrapper` 同时维护查询字段和更新 set 片段；新增状态时必须检查 `instance()` 与 `clear()`。 - 返回链式对象时保持 `this` / `typedThis`，不要暴露底层 wrapper 破坏调用链。 diff --git a/.claude/agents/backend-crud.md b/.claude/agents/backend-crud.md index 6da0b453d..8d4dd08aa 100644 --- a/.claude/agents/backend-crud.md +++ b/.claude/agents/backend-crud.md @@ -33,8 +33,8 @@ description: 标准后端 CRUD 专家。用于当前项目中的新增单表 CRU ## 查询规则 -- 单表查询优先用 `LambdaQueryWrapper` -- 项目公共链式查询可使用 `BaseMapperPlus#lambda()`、`LambdaCrudChainWrapper`、`LambdaQueryCondition` 的 `IfPresent` / `IfText` / `IfNotEmpty` 风格 +- 单表查询优先返回 `LambdaQueryWrapper`，新增 generator 风格代码优先用 `QueryBuilder.lambda(Entity.class).build()` +- 项目公共链式查询可使用 `QueryBuilder.lambda(...)`、`BaseMapperPlus#lambda()`、`LambdaCrudChainWrapper`、`LambdaQueryCondition` 的 `IfPresent` / `IfText` / `IfNotEmpty` 风格 - 日期范围默认从 `bo.getParams()` 中读取 begin/end - 分页优先返回 `PageResult` - BO 转实体使用 `MapstructUtils.convert(bo, Entity.class)` diff --git a/.claude/agents/backend-engineering.md b/.claude/agents/backend-engineering.md index 59efb4daf..ac3198a6f 100644 --- a/.claude/agents/backend-engineering.md +++ b/.claude/agents/backend-engineering.md @@ -14,6 +14,14 @@ description: 后端工程总入口。用于在当前 RuoYi-Vue-Plus 项目中识 5. 如果只要求补充或修正 JavaDoc 注释，优先使用 `backend-javadoc.md` 的规则。 6. 如果同时要求同步前端接口或前端页面骨架，保持后端路由与 generator 风格稳定，便于前端 agent 对接。 +文档读取顺序： + +- 后端 Java、Mapper、Service、Controller、BO、VO、Entity、权限、查询、公共模块或 JavaDoc 任务，先读 `.codex/skills/ruoyi-plus-ai-coding/references/backend.md`。 +- 同步前端 Vue、TypeScript、api、types 或页面骨架时，再读 `.codex/skills/ruoyi-plus-ai-coding/references/frontend.md`。 +- 任务边界不清晰或需要标准场景示例时，再读 `.codex/skills/ruoyi-plus-ai-coding/references/examples.md`。 +- 只读取当前任务相关的 reference，不一次性展开全部文档。 +- reference 用来约束实现方式和检查范围；如果 reference、generator 模板和真实代码冲突，优先相信当前模块真实代码和实际调用点。 + 通用要求： - 先读同模块最近似实现，再动代码。 diff --git a/.claude/agents/backend-query-permission.md b/.claude/agents/backend-query-permission.md index c801d598c..adcc168d8 100644 --- a/.claude/agents/backend-query-permission.md +++ b/.claude/agents/backend-query-permission.md @@ -16,18 +16,20 @@ description: 后端查询、联表与数据权限专家。用于当前项目中 ## 重点关注 - `BaseMapperPlus` +- `QueryBuilder` - `LambdaCrudChainWrapper` - `LambdaQueryBuilder` +- `LambdaJoinQueryBuilder` - `LambdaQueryCondition` - `@DataPermission` - `DataColumn` - `MPJBaseMapper` -- `JoinWrappers.lambda(...)` +- `QueryBuilder.lambdaJoin(...)` - 复杂分页与列表查询 ## 项目写法 -- MPJ 联表查询沿用别名风格，例如 `JoinWrappers.lambda("u", SysUser.class)`。 +- MPJ 联表查询沿用别名风格，例如 `QueryBuilder.lambdaJoin("u", SysUser.class)`。 - 带别名字段条件使用 `.eq("u", Entity::getField, value)`、`.orderByAsc("m", SysMenu::getOrderNum)`。 - 数据权限列名要和真实 SQL 别名一致，例如 `d.dept_id`、`u.create_by`。 - `ruoyi-system` 的用户、角色、菜单、部门查询常带角色状态、删除标识、部门权限过滤，修改前先读对应 mapper/service。 diff --git a/.codex/skills/ruoyi-plus-ai-coding/SKILL.md b/.codex/skills/ruoyi-plus-ai-coding/SKILL.md index 3cfbc2940..5bbabd863 100644 --- a/.codex/skills/ruoyi-plus-ai-coding/SKILL.md +++ b/.codex/skills/ruoyi-plus-ai-coding/SKILL.md @@ -1,6 +1,6 @@ --- name: ruoyi-plus-ai-coding -description: 在仓库内按代码生成器模板和项目既有约定生成或修改代码。用于新增或修改 CRUD 模块、controller/service/mapper/BO/VO/entity、MyBatis-Plus/MPJ 查询、数据权限、缓存、翻译/JSON 增强、公共 common 模块能力、JavaDoc 注释，以及与后端接口配套的 Vue 3 + TypeScript 页面、types 和 api 文件。 +description: 在仓库内按代码生成器模板、项目 reference 文档和既有约定生成或修改代码。用于新增或修改 CRUD 模块、controller/service/mapper/BO/VO/entity、MyBatis-Plus/MPJ 查询、数据权限、缓存、翻译/JSON 增强、公共 common 模块能力、JavaDoc 注释，以及与后端接口配套的 Vue 3 + TypeScript 页面、types 和 api 文件；触发后应先按任务类型读取对应 references，再阅读目标模块真实代码和 generator 模板。 --- # RuoYi Plus AI 编码规范 @@ -30,14 +30,25 @@ description: 在仓库内按代码生成器模板和项目既有约定生成或 ## 执行流程 -1. 先确认目标模块，优先复用同模块中最近似功能的写法。 -2. 新增标准 CRUD 代码前，先读取 `ruoyi-modules/ruoyi-gen/src/main/resources/vm/` 下的模板。 -3. 命名和分层保持与仓库一致： +1. 先判断任务类型，并按“文档读取规则”读取当前任务需要的 reference。 +2. 确认目标模块，优先复用同模块中最近似功能的写法。 +3. 新增标准 CRUD 代码前，先读取 `ruoyi-modules/ruoyi-gen/src/main/resources/vm/` 下的模板。 +4. 命名和分层保持与仓库一致： `domain` entity、`domain.bo`、`domain.vo`、`mapper`、`service`、`service.impl`、`controller`。 -4. 优先在生成器结构上扩展，不要自行发明新的分层。 -5. 修改 `ruoyi-system` 这类复杂模块前，先阅读同类现有实现，因为这些模块通常比生成器默认产物多出数据权限、联表、缓存、安全校验等逻辑。 -6. 修改 `ruoyi-common` 公共模块前，先阅读同包接口、实现类和调用点，优先保持已有 API 语义与兼容性。 -7. 只补注释或文档时，不运行无关格式化，不重排 import，不改代码逻辑。 +5. 优先在生成器结构上扩展，不要自行发明新的分层。 +6. 修改 `ruoyi-system` 这类复杂模块前，先阅读同类现有实现，因为这些模块通常比生成器默认产物多出数据权限、联表、缓存、安全校验等逻辑。 +7. 修改 `ruoyi-common` 公共模块前，先阅读同包接口、实现类和调用点，优先保持已有 API 语义与兼容性。 +8. 只补注释或文档时，不运行无关格式化，不重排 import，不改代码逻辑。 + +## 文档读取规则 + +使用本 skill 时，先按任务类型读取适用 reference，不一次性展开所有文档： + +- 后端 Java、Mapper、Service、Controller、BO、VO、Entity、权限、查询、公共模块或 JavaDoc 任务，先读 [references/backend.md](references/backend.md)。 +- 前端 Vue、TypeScript、api、types 或页面任务，先读 [references/frontend.md](references/frontend.md)。 +- 不确定任务边界、需要标准调用方式或需要对照典型场景时，再读 [references/examples.md](references/examples.md)。 + +reference 用来约束实现方式和自检范围；发生冲突时，仍以当前模块真实代码和实际调用点为准。 ## 优先级规则 diff --git a/.codex/skills/ruoyi-plus-ai-coding/agents/openai.yaml b/.codex/skills/ruoyi-plus-ai-coding/agents/openai.yaml index d5977d1a9..9f0080421 100644 --- a/.codex/skills/ruoyi-plus-ai-coding/agents/openai.yaml +++ b/.codex/skills/ruoyi-plus-ai-coding/agents/openai.yaml @@ -1,7 +1,7 @@ interface: display_name: "RuoYi Plus 编码" - short_description: "按生成器、common 与仓库约定编写代码" - default_prompt: "使用 $ruoyi-plus-ai-coding 在这个仓库里按现有约定实现代码修改，保持生成器、公共模块和业务模块风格一致。" + short_description: "先读适用 reference，再按生成器与仓库约定编码" + default_prompt: "使用 $ruoyi-plus-ai-coding 在这个仓库里先读取适用 reference，再按生成器、公共模块和业务模块风格实现代码修改。" policy: allow_implicit_invocation: true diff --git a/.codex/skills/ruoyi-plus-ai-coding/references/backend.md b/.codex/skills/ruoyi-plus-ai-coding/references/backend.md index 3a86cc759..0c84848d4 100644 --- a/.codex/skills/ruoyi-plus-ai-coding/references/backend.md +++ b/.codex/skills/ruoyi-plus-ai-coding/references/backend.md @@ -5,6 +5,7 @@ - `ruoyi-modules/ruoyi-gen/src/main/resources/vm/java/*.vm` - `ruoyi-modules/ruoyi-demo/...` - `ruoyi-modules/ruoyi-system/...` +- `ruoyi-modules/ruoyi-workflow/...` - `ruoyi-common/ruoyi-common-mybatis/...` ## 决策顺序 @@ -62,7 +63,7 @@ - 默认形式是 `interface XxxMapper extends BaseMapperPlus`。 - 不要为简单的 entity 转 vo 手写重复代码，优先依赖 `BaseMapperPlus`。 - 模块已经使用 `@DataPermission` 时，在重写方法和自定义查询上继续保留。 -- 复杂模块里 mapper 可能同时继承 `MPJBaseMapper` 并使用 `JoinWrappers.lambda(...)`，遇到这种风格要延续，不要换一种写法。 +- 复杂模块里 mapper 可能同时继承 `MPJBaseMapper` 并使用 `QueryBuilder.lambdaJoin(...)` 构造 MPJ 查询，遇到这种风格要延续，不要换一种写法。 - 只有在 `selectVoList/selectVoPage` 不够用时，才补 XML 或自定义 mapper 方法。 - Mapper 默认方法可以承载短小的 wrapper 查询；涉及复杂业务编排、缓存、事务或跨 mapper 写入时放到 service。 - `ruoyi-system` 的用户、角色、菜单、部门等模块常带数据权限、MPJ 联表、角色状态过滤，修改前先读对应 mapper/service。 @@ -93,8 +94,8 @@ - 如果去掉前缀会产生歧义或命名冲突，保留必要前缀。 - 读操作通常返回 `Vo`、`List` 或 `PageResult`。 - BO 转实体用 `MapstructUtils.convert(bo, Entity.class)`。 -- 查询条件优先用 `LambdaQueryWrapper` 和 `Wrappers.lambdaQuery()`。 -- 在 wrapper 条件里直接写 `StringUtils.isNotBlank(...)` 和 null 判断。 +- 查询条件优先返回 `LambdaQueryWrapper`；新增 generator 风格代码优先用 `QueryBuilder.lambda(Entity.class)`，老模块已有 `Wrappers.lambdaQuery()` 时可继续保持。 +- 字符串和空值条件优先用 `eqIfText`、`likeIfText`、`eqIfPresent`、`inIfNotEmpty`、`betweenParams` 等项目扩展；老代码已有直接 `StringUtils.isNotBlank(...)` 和 null 判断时可增量保持。 - 分页查询优先采用： `Page result = entityMapper.selectVoPage(pageQuery.build(), lqw);` `return PageResult.build(result.getRecords(), result.getTotal());` @@ -119,10 +120,10 @@ ### 查询逻辑建议 -- 单表查询优先使用 `LambdaQueryWrapper`。 -- 条件判断直接放在 wrapper 上，不要额外写大量 if 套壳。 -- 日期范围统一从 `bo.getParams()` 取 begin/end。 -- 复杂联表查询优先查同模块是否已有 MPJ 风格可复用。 +- 单表查询优先返回 `LambdaQueryWrapper`，生成器风格优先通过 `QueryBuilder.lambda(Entity.class).build()` 构造。 +- 条件判断直接放在 wrapper 链式条件上，不要额外写大量 if 套壳。 +- 日期范围统一从 `bo.getParams()` 取 begin/end；生成器默认使用 `betweenParams(Entity::getField, params, "beginField", "endField")`。 +- 复杂联表查询优先查同模块是否已有 MPJ 风格可复用；新写法优先用 `QueryBuilder.lambdaJoin("u", Entity.class)`。 ### 写入逻辑建议 @@ -136,6 +137,7 @@ - 类上通常带 `@Validated`、`@RestController`、`@RequiredArgsConstructor`、`@RequestMapping`。 - 返回值使用 `R` 或 `R`。 - 标准 CRUD 接口通常是：`GET /list`、`POST /export`、`GET /{id}`、`POST`、`PUT`、`DELETE /{ids}`。 +- 树表接口通常不分页，`list` 返回 `R>`；导出路由以目标模块或 generator 模板为准，旧 demo 树表存在 `GET /export`，新版生成器通常是 `POST /export`。 - `@SaCheckPermission` 权限格式遵循 `${module}:${business}:${action}`。 - 写操作、导入导出接口通常加 `@Log(title = "...", businessType = BusinessType.X)`。 - 附近接口已有防重时，写接口继续使用 `@RepeatSubmit`。 @@ -166,14 +168,15 @@ - 优先使用项目工具类：`MapstructUtils`、`StringUtils`、`StreamUtils`、`ValidatorUtils`、`SpringUtils`、`RedisUtils`。 - 数组转列表按附近代码习惯使用 `List.of(ids)` 或 `Arrays.asList(ids)`。 - 日期范围查询通常从 `bo.getParams()` 中读取 `beginTime`、`endTime` 或 `beginFieldName`、`endFieldName`。 +- 构建查询优先识别 `QueryBuilder.lambda(...)`、`QueryBuilder.lambdaJoin(...)`、`BaseMapperPlus#lambda()` 三类入口，不要退回临时手写 SQL 或自造 wrapper。 ## common-mybatis 规则 -- 链式查询能力优先沿用 `BaseMapperPlus#lambda()`、`LambdaCrudChainWrapper`、`LambdaQueryBuilder`、`LambdaQueryCondition`。 -- 条件辅助方法使用项目已有命名：`eqIfPresent`、`eqIfText`、`likeIfText`、`betweenIfPresent`、`inIfNotEmpty`、`findInSetIfPresent`。 +- 链式查询能力优先沿用 `QueryBuilder.lambda(...)`、`QueryBuilder.lambdaJoin(...)`、`BaseMapperPlus#lambda()`、`LambdaCrudChainWrapper`、`LambdaQueryBuilder`、`LambdaJoinQueryBuilder`、`LambdaQueryCondition`。 +- 条件辅助方法使用项目已有命名：`eqIfPresent`、`eqIfText`、`neIfPresent`、`likeIfText`、`betweenIfPresent`、`betweenParams`、`inIfNotEmpty`、`findInSetIfPresent`。 - 新增 wrapper 方法时保持链式返回 `this` / `typedThis`，不要返回底层 `LambdaQueryWrapper` 破坏调用链。 - `LambdaCrudChainWrapper` 既承担查询又承担更新 set 片段，新增能力时要同时考虑 `getSqlSelect`、`getSqlSet`、`clear`、`instance` 的状态复制和清理。 -- MPJ 联表查询沿用别名风格，例如 `JoinWrappers.lambda("u", SysUser.class)`、`.leftJoin(..., "d", ...)`、`.eq("u", Entity::getField, value)`。 +- MPJ 联表查询沿用别名风格，例如 `QueryBuilder.lambdaJoin("u", SysUser.class)`、`.leftJoin(..., "d", ...)`、`.eq("u", Entity::getField, value)`。 - 数据权限注解使用 `@DataPermission` + `@DataColumn`，列名需和实际 SQL 别名一致，例如 `d.dept_id`、`u.create_by`。 ## translation / JSON 增强规则 @@ -187,8 +190,8 @@ ## 缓存与异步/监听规则 -- 已有 service 使用 `@Cacheable`、`@CacheEvict`、`@Caching` 时，新增写操作要同步考虑缓存失效。 -- 部门、字典、OSS 配置等模块已有缓存初始化或失效逻辑，不要只改数据库不处理缓存。 +- 已有 service 使用 `@Cacheable`、`@CachePut`、`@CacheEvict`、`@Caching` 或 `CacheUtils.evict/clear` 时，新增写操作要同步考虑缓存失效。 +- 部门、字典、OSS 配置等模块已有缓存初始化或失效逻辑，不要只改数据库不处理缓存；字典这类模块常同时维护 `CacheNames.SYS_DICT` 与 `CacheNames.SYS_DICT_TYPE`。 - Excel 导入监听器实现 `ExcelListener` 时，保留 `getExcelResult()` 的回执语义和错误聚合方式。 - 定时任务、MQTT、SSE、异步回调等框架方法一般按接口覆写语义实现，除非业务不直观，不要添加冗长注释。 diff --git a/.codex/skills/ruoyi-plus-ai-coding/references/frontend.md b/.codex/skills/ruoyi-plus-ai-coding/references/frontend.md index f77a22653..a4340306d 100644 --- a/.codex/skills/ruoyi-plus-ai-coding/references/frontend.md +++ b/.codex/skills/ruoyi-plus-ai-coding/references/frontend.md @@ -6,12 +6,13 @@ - `ruoyi-modules/ruoyi-gen/src/main/resources/vm/vue/*.vm` - 前端工程中与目标模块最接近的现有页面 -如果任务涉及前端，先看仓库里实际使用的前端目录和同类页面，不要直接套通用 Vue 习惯。 +当前 boot4 仓库通常只含后端与 generator 前端模板；如果前端工程不在当前 root，先以 generator 模板约定为准，再对照用户提供的前端目录或相邻仓库。 ## API 文件规则 - 从 `@/utils/request` 引入 `request`。 -- 从 `axios` 引入 `AxiosPromise`。 +- 从 `@/utils/api-types` 引入 `AxiosPromise`。 +- 从 `@/api/types` 引入 `PageResult`。 - 从 `@/api///types` 引入本模块类型。 - 列表接口通常返回 `AxiosPromise>`。 - 常规接口命名和路由保持： @@ -36,24 +37,24 @@ - 使用 `