init: 导入RuoYi‑Vue‑Plus 6.X完整代码

.codex/skills/ruoyi-plus-ai-coding/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: ruoyi-plus-ai-coding
+description: 在仓库内按代码生成器模板、项目 reference 文档和既有约定生成或修改代码。用于新增或修改 CRUD 模块、controller/service/mapper/BO/VO/entity、MyBatis-Plus/MPJ 查询、数据权限、缓存、翻译/JSON 增强、公共 common 模块能力、JavaDoc 注释，以及与后端接口配套的 Vue 或 React 前端页面、types 和 api 文件；触发后应先按任务类型读取对应 references，再阅读目标模块真实代码和 generator 模板。
+---
+
+# RuoYi Plus AI 编码规范
+
+先对齐代码生成器产物，再叠加仓库里真实业务代码已经形成的更强约定。
+
+## 适用场景
+
+在下面这些任务里优先使用此 skill：
+
+- 新增标准 CRUD 模块。
+- 根据新表结构补齐 entity、bo、vo、mapper、service、controller。
+- 修改已有模块的查询、校验、导入导出、数据权限、事务逻辑。
+- 修改 `ruoyi-common` 公共能力，例如 mybatis 查询构造器、translation、json enhance、excel、oss、redis、web 配置。
+- 补充或修正 JavaDoc 注释，尤其是公共 API、接口、BO/VO/Entity 字段、Mapper 默认方法、Service/Controller 方法。
+- 在系统、监控、工作流、demo 等模块内按现有约定扩展业务代码。
+- 为后端新增接口同步补前端 `api/types` 和 Vue `index.vue` 或 React `index.tsx` 页面骨架。
+
+## 不适用场景
+
+下面这些任务不要机械套用本 skill 的 CRUD 规则：
+
+- 基础框架升级、Spring Boot 主版本迁移。
+- 与当前分层明显不同的实验性模块。
+- 第三方中间件深度接入、基础设施改造。
+- 完全脱离 generator 体系的独立子系统。
+
+## 执行流程
+
+1. 先判断任务类型，并按“文档读取规则”读取当前任务需要的 reference。
+2. 确认目标模块，优先复用同模块中最近似功能的写法。
+3. 新增标准 CRUD 代码前，先读取 `ruoyi-modules/ruoyi-gen/src/main/resources/fm/` 下的 FreeMarker 模板。
+4. 命名和分层保持与仓库一致：
+   `domain` entity、`domain.bo`、`domain.vo`、`mapper`、`service`、`service.impl`、`controller`。
+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、React、TypeScript、api、types 或页面任务，先读 [references/frontend.md](references/frontend.md)。
+- 不确定任务边界、需要标准调用方式或需要对照典型场景时，再读 [references/examples.md](references/examples.md)。
+
+reference 用来约束实现方式和自检范围；发生冲突时，仍以当前模块真实代码和实际调用点为准。
+
+## 优先级规则
+
+发生冲突时按下面顺序决策：
+
+1. 当前模块内最近似业务代码。
+2. 当前仓库公共基础模块约定，例如 `common-mybatis`、`common-core`、`common-web`。
+3. 代码生成器模板。
+4. 通用 Spring Boot / MyBatis-Plus 习惯。
+
+也就是说：
+
+- 同模块已有成熟实现时，优先复用该实现。
+- 同模块没有现成代码时，再参考 generator 模板。
+- 不要因为“更通用”就覆盖掉项目已形成的强约定。
+
+## 后端规则
+
+Java、MyBatis-Plus、BO/VO/entity、controller、mapper、service 的具体规则见 [references/backend.md](references/backend.md)。
+
+## 前端规则
+
+Vue 3、React、TypeScript API 文件、生成式列表页、表单状态、字典和日期范围约定见 [references/frontend.md](references/frontend.md)。
+
+## 使用案例
+
+具体调用方式见 [references/examples.md](references/examples.md)。
+
+## 仓库通用规则
+
+- 遵循 [`.editorconfig`](../../../.editorconfig)：UTF-8、LF，默认 4 空格，JSON/YAML 为 2 空格。
+- 不要把 `BaseMapperPlus`、`PageQuery`、`PageResult`、`R`、`MapstructUtils` 或项目工具类替换成临时自造方案。
+- 仓库已使用 `List.of(...)` 的地方，数组转列表优先继续沿用。
+- import、注解顺序、文件结构以附近代码为准，不要顺手重排整个文件。
+- 只有在业务逻辑不直观时才加简短注释。
+
+## 决策规则
+
+- 如果任务是围绕单表的标准 CRUD，尽量贴近生成器默认产物。
+- 如果目标模块已经存在自定义校验、数据权限、事务、缓存、Excel 导入导出、联表查询等逻辑，应在此基础上扩展，不要为了“简洁”把它们削平。
+- 如果附近 controller 接口已经带有权限、日志、防重、加密、分组校验等注解，新接口默认同步保持一致，除非有明确理由不这样做。
+- 如果 BO 或 VO 需要字段校验、翻译、Excel 注解，应优先参考同模块同用途对象，不要机械套通用注解。
+- 如果修改公共基础模块，优先保持公开 API 兼容，新增能力要查调用点和同包风格。
+- 如果任务只涉及注释，默认补 JavaDoc 并保持实现不变；框架覆写方法不强行重复注释，除非业务语义不直观。
+
+## 目录映射规则
+
+标准后端模块通常按下面结构组织：
+
+- `src/main/java/.../domain/Entity.java`
+- `src/main/java/.../domain/bo/EntityBo.java`
+- `src/main/java/.../domain/vo/EntityVo.java`
+- `src/main/java/.../mapper/EntityMapper.java`
+- `src/main/java/.../service/IEntityService.java`
+- `src/main/java/.../service/impl/EntityServiceImpl.java`
+- `src/main/java/.../controller/EntityController.java`
+
+标准生成器模板通常对应：
+
+- `fm/java/domain.java.ftl` -> entity
+- `fm/java/bo.java.ftl` -> bo
+- `fm/java/vo.java.ftl` -> vo
+- `fm/java/mapper.java.ftl` -> mapper
+- `fm/java/service.java.ftl` -> service interface
+- `fm/java/serviceImpl.java.ftl` -> service impl
+- `fm/java/controller.java.ftl` -> controller
+- `fm/xml/mapper.xml.ftl` -> 自定义 XML mapper 起点
+
+## 任务分型
+
+### 1. 标准单表 CRUD
+
+优先按 generator 模板落骨架，再补校验、权限、导出、翻译等项目约定。
+
+### 2. 强业务模块扩展
+
+如果目标模块像 `system`、`workflow` 一样已经有复杂逻辑，优先增量修改，不要回退成模板式简化代码。
+
+### 3. 基础能力复用
+
+如果涉及数据权限、缓存、事务、导入导出、字典、翻译、加密、分组校验，优先查项目已有做法并复用公共能力。
+
+### 4. 公共基础模块修改
+
+修改 `ruoyi-common` 下的基础能力时，优先保证二进制/API 兼容：不要轻易改公开方法签名、泛型、返回值或异常语义。新增注释和小范围能力时，先查同包现有风格，例如 `common-mybatis` 的链式 wrapper、`common-translation` 的 `TranslationInterface` 实现、`common-json` 的字段处理器。
+
+### 5. 注释修正任务
+
+只要求“加注释/完善注释”时，默认补 JavaDoc，不改实现。优先补公共 API、接口方法、字段含义、复杂私有辅助方法；覆写框架回调方法只有在当前文件已有注释风格或业务语义不直观时才补。
+
+## 输出要求
+
+使用本 skill 时，默认期望产出应满足：
+
+- 后端分层完整，不直接在 controller 里堆业务逻辑。
+- `BO/VO/Entity` 职责分明。
+- 查询、分页、删除校验、写入校验逻辑闭环完整。
+- 权限、日志、防重、事务、数据权限尽量贴近同模块现有实现。
+- 如果同步改前端，前端 API 路径和后端接口保持一致。
+
+## 快速检查清单
+
+- 包路径和 `@RequestMapping` 与模块保持一致。
+- 权限标识遵循 `${module}:${business}:${action}`。
+- Mapper 继承 `BaseMapperPlus<Entity, Vo>`。
+- 手写 Service 注入 Mapper 时使用具体业务短名；代码生成器模板按类名首字母小写命名，例如 `SysRoleMapper` 生成 `sysRoleMapper`。
+- Service 按场景返回 `PageResult` 或 `List<Vo>`。
+- 查询代码优先使用 `LambdaQueryWrapper`，复杂模块沿用既有 MPJ 联表风格。
+- 公共 Mapper 链式能力优先沿用 `LambdaCrudChainWrapper`、`LambdaQueryBuilder`、`LambdaQueryCondition` 的 `IfPresent` / `IfText` / `IfNotEmpty` 风格。
+- 翻译能力优先沿用 `TranslationInterface` + `@TranslationType` + `@Translation`，批量翻译实现 `translationBatch`，避免退化成逐条查询。
+- JSON 响应增强优先沿用 `JsonFieldProcessor` 的 `collect` / `prepare` / `process` 三阶段模型。
+- BO 使用 `@AutoMapper(target = Entity.class, reverseConvertGenerate = false)`。
+- VO 使用 `@AutoMapper(target = Entity.class)`。
+- 前端 API 路径与后端路由完全对应。
+- 前端列表页继续使用对应前端工程已有工具：Vue 侧如 `proxy?.addDateRange`、`proxy?.$modal`、`proxy?.download`、`useDict`、`pagination`；React 侧如 `ProTable`、`ModalForm`、`useTableSelection`、`useDateRangeQuery`、`useTableExport`。
+
+## 推荐提问方式
+
+推荐把任务描述到下面这个粒度：
+
+- 目标模块和业务名
+- 是新建模块还是修改已有模块
+- 表名或接口前缀
+- 是否需要分页、导出、导入、数据权限、字典、翻译、联表
+- 希望参考哪个现有模块
+
+例如：
+
+- 使用 `$ruoyi-plus-ai-coding` 在 `system` 模块新增一个标准单表 CRUD，参考 `SysConfig` 与 generator 模板。
+- 使用 `$ruoyi-plus-ai-coding` 修改 `workflow/category` 的查询和导出逻辑，保持现有模块风格。

.codex/skills/ruoyi-plus-ai-coding/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "RuoYi Plus 编码"
+  short_description: "先读适用 reference，再按生成器与仓库约定编码"
+  default_prompt: "使用 $ruoyi-plus-ai-coding 在这个仓库里先读取适用 reference，再按生成器、公共模块和业务模块风格实现代码修改。"
+
+policy:
+  allow_implicit_invocation: true

.codex/skills/ruoyi-plus-ai-coding/references/backend.md

@@ -0,0 +1,268 @@
+# 后端约定
+
+## 优先参考的代码来源
+
+- `ruoyi-modules/ruoyi-gen/src/main/resources/fm/java/*.ftl`
+- `ruoyi-modules/ruoyi-demo/...`
+- `ruoyi-modules/ruoyi-system/...`
+- `ruoyi-modules/ruoyi-workflow/...`
+- `ruoyi-common/ruoyi-common-mybatis/...`
+
+## 决策顺序
+
+写代码时按下面顺序取样：
+
+1. 当前业务模块下最近似实现。
+2. 当前仓库公共能力模块中的统一约定。
+3. generator 模板。
+4. 通用 Spring / MyBatis-Plus 默认习惯。
+
+如果规则冲突，优先相信当前仓库真实代码。
+
+## 分层结构
+
+标准 CRUD 代码应优先遵循下面这套结构：
+
+- `domain/Entity.java`
+- `domain/bo/EntityBo.java`
+- `domain/vo/EntityVo.java`
+- `mapper/EntityMapper.java`
+- `service/IEntityService.java`
+- `service/impl/EntityServiceImpl.java`
+- `controller/EntityController.java`
+
+## Entity 规则
+
+- 除非所在模块明显另有约定，否则实体类继承 `org.dromara.common.mybatis.core.domain.BaseEntity`。
+- 使用 Lombok `@Data` 和 `@EqualsAndHashCode(callSuper = true)`。
+- 使用 `@TableName("table_name")`。
+- 主键使用 `@TableId`。
+- 存在 `delFlag` 时保留 `@TableLogic`，存在乐观锁字段时保留 `@Version`。
+- 如果附近实体已经使用 `@OrderBy` 等额外注解，应继续保持。
+
+## BO 规则
+
+- 实现 `Serializable`。
+- 添加 `@AutoMapper(target = Entity.class, reverseConvertGenerate = false)`。
+- 请求专用字段、查询专用字段放在 BO 中，包括 `params`。
+- 在生成器或附近代码已有分组校验时，继续使用：`AddGroup`、`EditGroup`、`QueryGroup`。
+- `@Xss`、`@Email`、`@Size`、`@NotBlank`、`@NotNull` 要按真实业务语义添加，不要一股脑全套上。
+- 查询存在日期范围或扩展条件时，保留 `params = new HashMap<>()`。
+
+## VO 规则
+
+- 实现 `Serializable`。
+- 添加 `@AutoMapper(target = Entity.class)`。
+- 生成器风格的导出对象通常带 `@ExcelIgnoreUnannotated`。
+- `@ExcelProperty`、`@ExcelDictFormat`、`ExcelDictConvert`、`@ExcelRequired`、`@ExcelNotation`、`@DateTimeFormat` 只在导入导出场景下使用。
+- 如果附近代码会把 ID 翻译成展示字段，沿用 `@Translation(type = TransConstant.USER_ID_TO_NAME, mapper = "createBy")` 这类写法。
+- 展示型派生字段放在 VO，不放在 Entity。
+
+## Mapper 规则
+
+- 默认形式是 `interface XxxMapper extends BaseMapperPlus<Xxx, XxxVo>`。
+- 不要为简单的 entity 转 vo 手写重复代码，优先依赖 `BaseMapperPlus`。
+- 模块已经使用 `@DataPermission` 时，在重写方法和自定义查询上继续保留。
+- 复杂模块里 mapper 可能同时继承 `MPJBaseMapper<Entity>` 并使用 `QueryBuilder.lambdaJoin(...)` 构造 MPJ 查询，遇到这种风格要延续，不要换一种写法。
+- 只有在 `selectVoList/selectVoPage` 不够用时，才补 XML 或自定义 mapper 方法。
+- Mapper 默认方法可以承载短小的 wrapper 查询；涉及复杂业务编排、缓存、事务或跨 mapper 写入时放到 service。
+- `ruoyi-system` 的用户、角色、菜单、部门等模块常带数据权限、MPJ 联表、角色状态过滤，修改前先读对应 mapper/service。
+
+### Mapper 建议结构
+
+标准 mapper 一般按这个顺序组织：
+
+1. 接口声明
+2. 默认查询方法
+3. 自定义分页或列表方法
+4. 特殊数据权限重写
+5. 辅助构造方法
+
+### 什么时候需要 XML
+
+- 复杂联表 SQL 无法仅靠 wrapper 清晰表达时。
+- 需要手写查询列和结果映射时。
+- 项目当前模块已经大量使用 XML 时。
+
+如果 `BaseMapperPlus + wrapper` 已足够，优先不要补 XML。
+
+## Service 规则
+
+- 类声明通常是 `@RequiredArgsConstructor`、`@Service`，按需补 `@Slf4j`。
+- 手写 mapper 注入字段使用具体业务短名；代码生成器模板按类名首字母小写命名。
+- 命名时去掉清晰的模块/系统前缀后使用 lowerCamel + `Mapper`，例如 `SysRoleMapper` -> `roleMapper`、`SysDictDataMapper` -> `dictDataMapper`。
+- 如果去掉前缀会产生歧义或命名冲突，保留必要前缀。
+- 读操作通常返回 `Vo`、`List<Vo>` 或 `PageResult<Vo>`。
+- BO 转实体用 `MapstructUtils.convert(bo, Entity.class)`。
+- 查询条件优先返回 `LambdaQueryWrapper`；新增 generator 风格代码优先用 `QueryBuilder.lambda(Entity.class)`，老模块已有 `Wrappers.lambdaQuery()` 时可继续保持。
+- 字符串和空值条件优先用 `eqIfText`、`likeIfText`、`eqIfPresent`、`inIfNotEmpty`、`betweenParams` 等项目扩展；老代码已有直接 `StringUtils.isNotBlank(...)` 和 null 判断时可增量保持。
+- 分页查询优先采用：
+  `Page<Vo> result = entityMapper.selectVoPage(pageQuery.build(), lqw);`
+  `return PageResult.build(result.getRecords(), result.getTotal());`
+- 生成器风格模块保留 `validEntityBeforeSave(...)` 这种扩展点。
+- 多表写操作使用 `@Transactional(rollbackFor = Exception.class)`。
+- 明确的业务失败，尤其是权限、数据完整性、删除校验，使用 `ServiceException`。
+- 不要绕过模块现有的数据权限、角色校验、删除前校验。
+
+### Service 建议结构
+
+标准 service impl 一般按下面顺序组织：
+
+1. 查询单条
+2. 分页查询
+3. 列表查询
+4. 构建查询条件
+5. 新增
+6. 修改
+7. 保存前校验
+8. 删除前校验与删除
+9. 其他扩展业务方法
+
+### 查询逻辑建议
+
+- 单表查询优先返回 `LambdaQueryWrapper`，生成器风格优先通过 `QueryBuilder.lambda(Entity.class).build()` 构造。
+- 条件判断直接放在 wrapper 链式条件上，不要额外写大量 if 套壳。
+- 日期范围统一从 `bo.getParams()` 取 begin/end；生成器默认使用 `betweenParams(Entity::getField, params, "beginField", "endField")`。
+- 复杂联表查询优先查同模块是否已有 MPJ 风格可复用；新写法优先用 `QueryBuilder.lambdaJoin("u", Entity.class)`。
+
+### 写入逻辑建议
+
+- BO 转实体统一走 `MapstructUtils.convert`。
+- 批量关系维护时优先拆成私有方法，例如角色、岗位、用户关联。
+- 修改前优先保留已有防误删、防越权、防并发覆盖逻辑。
+
+## Controller 规则
+
+- 继承 `BaseController`。
+- 类上通常带 `@Validated`、`@RestController`、`@RequiredArgsConstructor`、`@RequestMapping`。
+- 返回值使用 `R<T>` 或 `R<Void>`。
+- 标准 CRUD 接口通常是：`GET /list`、`POST /export`、`GET /{id}`、`POST`、`PUT`、`DELETE /{ids}`。
+- 树表接口通常不分页，`list` 返回 `R<List<Vo>>`；导出路由以目标模块或 generator 模板为准，旧 demo 树表存在 `GET /export`，新版生成器通常是 `POST /export`。
+- `@SaCheckPermission` 权限格式遵循 `${module}:${business}:${action}`。
+- 写操作、导入导出接口通常加 `@Log(title = "...", businessType = BusinessType.X)`。
+- 附近接口已有防重时，写接口继续使用 `@RepeatSubmit`。
+- 适合分组校验时，使用 `@Validated(AddGroup.class)` 和 `@Validated(EditGroup.class)`。
+- 特殊接口直接复用模块内现成做法，例如导入导出、`@ApiEncrypt`、multipart 上传、数据权限检查、写入前唯一性校验。
+
+### Controller 建议结构
+
+标准 controller 一般按下面顺序组织：
+
+1. 列表
+2. 导出
+3. 详情
+4. 新增
+5. 修改
+6. 删除
+7. 特殊接口
+
+### Controller 边界
+
+- controller 负责接参、校验、权限、日志、返回值转换。
+- 重业务逻辑尽量放 service，不要在 controller 里堆长逻辑。
+- 但前置权限检查、唯一性提示、显式业务失败提示可以留在 controller，前提是同模块已有这种习惯。
+
+## 查询与工具规则
+
+- 分页统一使用 `PageQuery` 和 `PageResult`，不要无故引入新的分页 DTO。
+- 优先使用项目工具类：`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 规则
+
+- 链式查询能力优先沿用 `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 联表查询沿用别名风格，例如 `QueryBuilder.lambdaJoin("u", SysUser.class)`、`.leftJoin(..., "d", ...)`、`.eq("u", Entity::getField, value)`。
+- 数据权限注解使用 `@DataPermission` + `@DataColumn`，列名需和实际 SQL 别名一致，例如 `d.dept_id`、`u.create_by`。
+
+## translation / JSON 增强规则
+
+- 翻译实现类实现 `TranslationInterface<T>` 并标注 `@TranslationType(type = ...)`。
+- 使用方在 VO 字段上通过 `@Translation(type = ..., mapper = "...", other = "...")` 指定翻译来源。
+- 批量翻译必须优先实现 `translationBatch(Set<Object> keys, String other)`，避免默认逐条查询。
+- 支持逗号分隔 ID 的翻译实现应复用 `collectLongIds`、`parseLongIds`、`joinMappedValues`。
+- `TranslationJsonFieldProcessor` 遵循三阶段：`collect` 收集待翻译值，`prepare` 批量查询，`process` 写入翻译结果；新增处理器也应优先套这个模型。
+- 翻译失败时保持降级返回原值或 `null` 的现有语义，不要让响应增强中断主流程。
+
+## 缓存与异步/监听规则
+
+- 已有 service 使用 `@Cacheable`、`@CachePut`、`@CacheEvict`、`@Caching` 或 `CacheUtils.evict/clear` 时，新增写操作要同步考虑缓存失效。
+- 部门、字典、OSS 配置等模块已有缓存初始化或失效逻辑，不要只改数据库不处理缓存；字典这类模块常同时维护 `CacheNames.SYS_DICT` 与 `CacheNames.SYS_DICT_TYPE`。
+- Excel 导入监听器实现 `ExcelListener` 时，保留 `getExcelResult()` 的回执语义和错误聚合方式。
+- 定时任务、MQTT、SSE、异步回调等框架方法一般按接口覆写语义实现，除非业务不直观，不要添加冗长注释。
+
+## 工作流模块规则
+
+- `ruoyi-workflow` 通常带 `@ConditionalOnEnable`，新增 workflow bean、controller、service 时检查同包是否需要该条件。
+- 流程分类、任务、实例等查询常带分类权限或用户维度过滤，先读同类 mapper/service 再改。
+- 工作流的翻译实现可以放在 workflow 模块内，例如流程分类 ID 到名称，仍应遵守 `TranslationInterface` 批量翻译规则。
+
+## JavaDoc 注释规则
+
+- 公共 API、接口、VO/BO/Entity 字段、Mapper 默认方法、Service/Controller 方法应有简洁 JavaDoc。
+- 注释描述“做什么”和关键参数语义，不复述显而易见的实现细节。
+- `void` 方法不要写 `@return`；返回布尔值时说明 `true/false` 含义。
+- 私有方法只有在业务规则、算法、映射关系不直观时补注释。
+- 框架覆写方法如果只是标准回调，可不重复注释；但当前文件已有统一注释风格时保持一致。
+- 只改注释时，不重排 import、不格式化全文件、不修改代码行为。
+
+## 前后端联动规则
+
+- 新增后端接口时，路径和权限前缀尽量保持 generator 约定，方便前端目录和 API 命名同步。
+- 新增日期范围查询时，记得保留 `bo.params` 结构，避免前端 `addDateRange` 无法对接。
+- 导出接口通常保持 `POST /export` 风格，便于前端直接复用现有下载逻辑。
+- 批量删除接口通常使用 `DELETE /{ids}`，便于前端直接传数组或逗号串。
+
+## 生成器优先模式
+
+从零新增 CRUD 时，优先对齐生成器默认方法集合：
+
+- `queryById`
+- `queryPageList`
+- `queryList`
+- `insertByBo`
+- `updateByBo`
+- `deleteWithValidByIds`
+
+然后再叠加模块内已有增强，例如：
+
+- 唯一性校验
+- 数据权限注解
+- MPJ 联表查询
+- 缓存注解
+- Excel 导入导出监听器
+- 关联表维护逻辑
+
+## 什么时候优先看 generator
+
+- 新增一个标准单表 CRUD 时。
+- 只有表结构和基本接口需求，没有现成业务模块可参考时。
+- 需要快速补齐整套骨架代码时。
+
+## 什么时候优先看现有模块
+
+- 目标模块已经有类似业务。
+- 涉及数据权限、联表、缓存、角色岗位关系、导入导出、工作流扩展时。
+- 任务是“修改已有模块”而不是“新建模块”时。
+
+## 避免事项
+
+- 不要在 controller 里直接暴露 entity 代替 BO/VO。
+- 不要给新的管理接口漏掉权限注解。
+- 没有明确必要时，不要从 `BaseMapperPlus` 风格退回手工映射。
+- 前端查询页用了日期范围时，不要删掉后端 `params` 相关处理。
+- 不要把 `ruoyi-system` 这类复杂逻辑强行简化成生成器式单表 CRUD。
+
+## 交付前自检
+
+交付前至少检查这些点：
+
+- CRUD 主链路是否完整。
+- BO / VO / Entity 职责是否清晰。
+- 分页、查询、删除校验是否与前端对得上。
+- 权限、日志、防重、事务是否遗漏。
+- 是否只是 generator 裸产物，如果是，需要继续补齐同模块已有增强。

.codex/skills/ruoyi-plus-ai-coding/references/examples.md

@@ -0,0 +1,101 @@
+# 使用案例
+
+## 案例 1：新增标准单表 CRUD
+
+### 用户提问示例
+
+```text
+使用 $ruoyi-plus-ai-coding 在 system 模块新增一个 client 管理的标准 CRUD。
+请参考 generator 模板和现有 system 模块写法，补齐 entity、bo、vo、mapper、service、controller。
+```
+
+### 期望执行方式
+
+- 先读 generator 的 `domain/bo/vo/service/serviceImpl/controller` 模板。
+- 再读 `system` 模块里最接近的现有管理模块。
+- 先生成骨架，再补权限、日志、校验、导出等细节。
+
+## 案例 2：修改已有复杂模块
+
+### 用户提问示例
+
+```text
+使用 $ruoyi-plus-ai-coding 修改 workflow/category 的查询和导出逻辑，保持现有模块风格，不要简化成模板式单表 CRUD。
+```
+
+### 期望执行方式
+
+- 先读当前 workflow 模块同类代码。
+- 判断这是“复杂模块增强”，不是“从零生成”。
+- 增量修改原逻辑，不要重写整个 service/controller。
+
+## 案例 3：补唯一性校验与删除前校验
+
+### 用户提问示例
+
+```text
+使用 $ruoyi-plus-ai-coding 为 demo/demo 模块补充新增和修改时的唯一性校验，并补充删除前校验。
+```
+
+### 期望执行方式
+
+- 优先修改 `validEntityBeforeSave(...)`。
+- 根据模块现有风格补 `ServiceException` 或显式失败返回。
+- 删除逻辑只补必要校验，不重构整套 CRUD。
+
+## 案例 4：补数据权限与联表查询
+
+### 用户提问示例
+
+```text
+使用 $ruoyi-plus-ai-coding 为 system 模块某个列表查询增加部门数据权限和联表字段返回，参考现有 user mapper 的 MPJ 与 DataPermission 写法。
+```
+
+### 期望执行方式
+
+- 先看 `SysUserMapper` 和相关 service。
+- 判断需要 `BaseMapperPlus` 重写还是 MPJ 联表。
+- 保持权限注解和联表风格一致。
+
+## 案例 5：新增后端接口并同步前端骨架
+
+### 用户提问示例
+
+```text
+使用 $ruoyi-plus-ai-coding 为 monitor/cache 新增一个导出接口，并同步补齐 Vue 或 React 前端 api/types 调用骨架。
+```
+
+### 期望执行方式
+
+- 先补后端 `controller/service`。
+- 再根据后端路由和目标前端类型补 `src/api` 或 generator 风格的前端骨架。
+- 保证导出接口路径和前端下载调用一致。
+
+## 案例 6：推荐的高质量任务描述
+
+下面这种描述最容易得到稳定结果：
+
+```text
+使用 $ruoyi-plus-ai-coding 在 workflow 模块新增一个标准列表管理功能：
+1. 需要分页、导出、详情、增删改
+2. 查询包含状态和创建时间范围
+3. 保持现有 workflow 模块风格
+4. 参考 generator 模板生成基础骨架
+5. 删除前需要做业务校验
+```
+
+## 不推荐的任务描述
+
+下面这种描述太模糊，容易导致产物偏离项目：
+
+```text
+帮我加个后端接口
+```
+
+更好的写法至少要补充：
+
+- 模块名
+- 表或业务名
+- 是新增还是修改
+- 是否需要分页、导出、权限、数据范围、联表
+- 想参考哪个现有模块

.codex/skills/ruoyi-plus-ai-coding/references/frontend.md

@@ -0,0 +1,101 @@
+# 前端约定
+
+## 优先参考的代码来源
+
+- `ruoyi-modules/ruoyi-gen/src/main/resources/fm/<frontendType>/*.ftl`
+- 默认 Vue 模板在 `fm/vue`，React 模板在 `fm/react`
+- 前端工程中与目标模块最接近的现有页面
+
+当前 boot4 仓库通常只含后端与 generator 前端模板；如果前端工程不在当前仓库根目录，先以 generator 模板约定为准，再对照用户提供的前端工程或官方前端分支：
+
+- Vue 前端：`https://gitee.com/JavaLionLi/plus-ui/tree/6.X-Vue`
+- React 前端：`https://gitee.com/JavaLionLi/plus-ui/tree/6.X-React`
+
+## 前端模板选择规则
+
+- `gen_table.frontend_type` 存字符串，值直接对应 `fm` 下的模板目录，例如 `vue`、`react`。
+- 生成器按 `fm/<frontendType>/api.ts.ftl`、`types.ts.ftl`、`index.*.ftl`、`index-tree.*.ftl` 查找模板。
+- 页面输出后缀由页面模板文件名决定：`index.vue.ftl` 输出 `index.vue`，`index.tsx.ftl` 输出 `index.tsx`。
+- 新增其他前端时优先只新增 `fm/<frontendType>` 目录和对应 FTL 文件，不在 Java 代码里增加数字枚举或硬编码分支。
+
+## API 文件规则
+
+- Vue 模板从 `@/utils/request` 引入 `request`，从 `@/utils/api-types` 引入 `AxiosPromise`，从 `@/api/types` 引入 `PageResult`。
+- React 模板从 `@/api/request` 引入 `request`，从 `@/api/types` 引入 `R`、`PageResult`。
+- 本模块类型：Vue 模板从 `@/api/<module>/<business>/types` 引入，React 模板从 `./types` 引入。
+- Vue 列表接口通常返回 `AxiosPromise<PageResult<Vo>>`；React 列表接口通常返回 `request<R<PageResult<Vo>>>(...)`。
+- 常规接口命名和路由保持：
+  `listXxx` -> `GET /<module>/<business>/list`
+  `getXxx` -> `GET /<module>/<business>/{id}`
+  `addXxx` -> `POST /<module>/<business>`
+  `updateXxx` -> `PUT /<module>/<business>`
+  `delXxx` -> `DELETE /<module>/<business>/{id or ids}`
+
+## 类型文件规则
+
+- 定义 `VO`、`Form`、`Query`。
+- `Form` 通常继承 `BaseEntity`。
+- 非树表页面的 `Query` 通常继承 `PageQuery`。
+- 各类 ID 字段通常用 `string | number`。
+- Java 数值类型通常映射为 `number`。
+- Boolean 映射为 `boolean`。
+- 其他生成字段默认多为 `string`。
+- 存在日期范围查询时保留 `params`：Vue 模板通常是 `params?: any`，React 模板通常是 `params?: Record<string, unknown>`。
+
+## Vue 页面规则
+
+- 使用 `<script setup lang="ts">`。
+- 常见 import 来自本模块 API 和本地 `types`。
+- 新版生成器优先使用 hooks：`useLoading`、`useSearchToggle`、`useSearchReset`、`useTableSelection`、`useFormDialog`，日期范围使用 `useDateRangeQuery`。
+- 字典通常通过 `toRefs<any>(useDict(...))` 解构。
+- 常见状态包括：列表数组、`loading`、`buttonLoading`、`showSearch`、`ids`、`single`、`multiple`、`total`。
+- 查询和表单状态通常放在 `reactive<PageData<Form, Query>>({...})` 中，并通过 `toRefs(data)` 暴露。
+- 弹窗状态优先由 `useFormDialog` 返回的 `dialog`、`openDialog`、`showDialog`、`closeDialog` 管理。
+- 表单引用通常命名为 `queryFormRef` 和 `<business>FormRef`。
+
+## React 页面规则
+
+- 使用 `index.tsx`，组件默认导出 `<BusinessName>Page`。
+- 页面主体优先沿用 Ant Design Pro：`PageContainer`、`ProTable`、`ModalForm`、`ProColumns`、`ActionType`。
+- 表单优先使用 `Form.useForm<Form>()`，弹窗开关优先使用 `ahooks` 的 `useBoolean`。
+- 权限通过 `useUserStore` 取 `userInfo`，再用 `hasPermi(userInfo, ['module:business:action'])` 生成 `canAdd`、`canEdit`、`canRemove`、`canExport`。
+- 表格选择使用 `useTableSelection<VO>(row => row.id)`；表格刷新使用 `actionRef.current?.reload()` 或 `reloadAndRest?.()`。
+- 字典使用 `useDict` 和 `dictOptions`，展示使用 `DictTag`。
+- 日期范围使用 `useDateRangeQuery`，在 `ProTable` 的 `request` 中由 `toPageQuery(params)` 转查询参数后再应用范围字段。
+- 导出使用 `useTableExport`，路径保持 `/<module>/<business>/export`。
+- 文件、图片、富文本组件使用 React 工程已有的 `FileUpload`、`ImageUpload`、`ImagePreview`、`RichTextEditor`。
+
+## Vue 页面行为规则
+
+- `getList` 负责通过 `withLoading` 设置 loading、处理日期范围参数、调用列表接口、回填 `rows` 和 `total`。
+- `handleQuery` 通常先把 `pageNum` 重置为 `1`，再重新查询。
+- `resetQuery` 优先使用 `useSearchReset`，通过 `resetExtras` 清空日期范围，再重新加载。
+- `handleSelectionChange` 优先使用 `useTableSelection` 返回的方法，更新 `ids`、`single`、`multiple`。
+- `handleAdd` 先重置表单，再通过 `openDialog` 打开弹窗。
+- `handleUpdate` 先重置并查详情，再 `Object.assign(form.value, res.data)`，最后通过 `showDialog` 打开弹窗。
+- `submitForm` 校验表单、切换 `buttonLoading`、根据主键判断调用新增还是更新、提示成功并刷新列表。
+- `handleDelete` 使用 `modal.confirm(...)` 确认，再调用删除接口并刷新。
+- `handleExport` 使用 `download as requestDownload` 从 `@/utils/request` 导出的下载方法。
+
+## React 页面行为规则
+
+- React `ProTable` 页面通过 `request` 回调加载列表并返回 `toTableData(res)`；新增、修改、删除成功后调用 `actionRef` 刷新。
+- React 弹窗提交函数根据主键判断调用新增还是更新，成功后 `message.success('操作成功')` 并重置表单。
+
+## 模板结构规则
+
+- 优先保持生成器的页面布局结构，不在 Vue 和 React 之间互相移植组件体系。
+- Vue 保留 `v-hasPermi="['module:business:add']"` 这类权限指令。
+- Vue 继续使用仓库已有组件：`right-toolbar`、`pagination`、`dict-tag`、`image-preview`、`image-upload`、`file-upload`、`editor`。
+- React 继续使用仓库已有组件：`RowActions`、`DictTag`、`ImagePreview`、`ImageUpload`、`FileUpload`、`RichTextEditor`。
+- 已有页面对时间列使用 `parseTime` 时，新页面保持一致。
+- Vue BETWEEN 日期查询继续使用 `el-date-picker`，脚本侧通过 `useDateRangeQuery` 生成 `dateRangeXxx`、`applyXxxDateRange`、`resetXxxDateRange`。
+- React BETWEEN 日期查询继续使用 `ProTable` 的 `dateTimeRange` 搜索列，查询侧通过 `useDateRangeQuery` 写入 `params`。
+
+## 避免事项
+
+- 生成器风格页面不要突然换成完全不同的状态管理方式，除非该前端目录本身已经这么做。
+- 模块已使用字典时，不要把选项文案硬编码到页面里。
+- 不要让 API 函数名和路由段偏离后端约定。
+- 后端 BO/service 依赖 begin/end 参数时，不要从查询对象里删掉 `params` 和日期范围处理。
+- 不要把 Vue 的 `proxy`、`v-hasPermi`、Element Plus 组件写进 React 页面，也不要把 React 的 `ProTable`、`ModalForm`、Ant Design 权限判断写进 Vue 页面。