hw-web/AGENTS.md

# Repository Guidelines

## 文档定位
本文件聚焦“写代码时需要的架构与模块提示信息”，不包含 Git 流程、编译或测试命令。

## 系统架构总览
- 工程形态：Maven 多模块单体应用，前后端分离（`ruoyi-ui` + Spring Boot 后端）。
- 模块分层：
  - `ruoyi-admin`：应用入口、Controller 暴露层。
  - `ruoyi-framework`：安全认证、AOP、拦截器、数据权限与限流实现层。
  - `ruoyi-system`：系统业务域（用户/角色/菜单/字典等）服务层。
  - `ruoyi-common`：跨模块基础设施与通用契约层。
  - `ruoyi-quartz`：任务调度能力层。
  - `ruoyi-generator`：代码生成能力层。
- 关键依赖方向：`admin -> framework -> system -> common`，`quartz/generator -> common`。

## Backend Tech Stack (With Versions)
版本来源：根 `pom.xml` 的 `properties` 与 `dependencyManagement`。

| 技术 | 版本 | 说明 |
|---|---:|---|
| Java | 17 | 语言与运行时基线 |
| Spring Boot BOM | 3.5.8 | Spring 生态版本管理 |
| MyBatis Spring Boot Starter | 3.0.5 | ORM/Mapper |
| Druid Spring Boot 3 Starter | 1.2.27 | 数据源与连接池 |
| PageHelper Starter | 2.1.1 | 分页 |
| MySQL Connector/J | 8.2.0 | MySQL 驱动 |
| SpringDoc OpenAPI | 2.8.14 | API 文档 |
| Spring Security | 由 Boot 3.5.8 管理 | 认证鉴权 |
| Spring Data Redis | 由 Boot 3.5.8 管理 | 缓存/会话 |
| JJWT | 0.9.1 | JWT |
| Quartz | 2.5.2 | 定时任务 |
| Fastjson2 | 2.0.60 | JSON |
| Apache POI | 4.1.2 | Excel 导入导出 |
| Velocity | 2.3 | 代码生成模板 |
| Kaptcha | 2.3.3 | 验证码 |
| YAUAA | 7.32.0 | User-Agent 解析 |
| OSHI | 6.9.1 | 主机监控信息 |
| Commons IO | 2.21.0 | IO 工具 |
| Jakarta Servlet API | 6.0.0 | Servlet 规范 |

## ruoyi-common 模块深度分析

### 模块定位与边界
- `ruoyi-common` 是后端基础设施层，提供统一契约、基类、工具和安全过滤，不承载业务流程。
- 当前约 `109` 个 Java 类，属于项目复用中心模块。

### 包结构概览（一级包）
- `utils`（36）：通用工具主集合。
- `core`（22）：Controller/Domain/Page/Redis/Text 基础抽象。
- `exception`（18）：统一异常体系。
- `annotation`（9）：横切能力注解契约。
- `constant`（6）/`enums`（8）：常量与策略枚举。
- `filter`（6）/`xss`（2）：请求过滤与输入安全。
- `config`（2）：通用配置与序列化器。

### 架构中心性（跨模块复用）
- `ruoyi-framework`: 148 次 `import com.ruoyi.common.*`
- `ruoyi-admin`: 138 次
- `ruoyi-system`: 86 次
- `ruoyi-quartz`: 40 次
- `ruoyi-generator`: 25 次
- 高频类：`StringUtils`、`AjaxResult`、`Constants`、`BaseController`、`SecurityUtils`、`ExcelUtil`。

### 设计机制（写代码时重点）
- 契约与实现分离：`@DataScope/@RateLimiter/@RepeatSubmit/@Log` 定义在 common，实现放在 framework 的 Aspect/Interceptor。
- 统一返回规范：Controller 继承 `BaseController`，统一输出 `AjaxResult`/`TableDataInfo`。
- 统一实体扩展位：`BaseEntity.params` 用于数据权限 SQL 片段等横切参数传递。
- 统一安全输入链路：`SqlUtil`、`XssFilter`、`XssValidator`、`RepeatableFilter` 负责请求与参数安全治理。

## ruoyi-common 类级别索引清单（按包）

### `annotation`
| 类 | 使用场景 |
|---|---|
| `Anonymous` | 标记匿名可访问接口 |
| `DataScope` | 服务查询方法注入数据权限条件 |
| `DataSource` | 动态切换主从数据源 |
| `Excel`/`Excels` | 实体字段导入导出映射 |
| `Log` | 业务操作日志切面采集 |
| `RateLimiter` | 接口限流（全局或按 IP） |
| `RepeatSubmit` | 防重复提交 |
| `Sensitive` | 返回字段脱敏 |

### `config`
| 类 | 使用场景 |
|---|---|
| `RuoYiConfig` | 读取 `ruoyi.*` 业务基础配置（上传路径、验证码类型等） |
| `SensitiveJsonSerializer` | 配合 `@Sensitive` 做序列化脱敏 |

### `constant`
| 类 | 使用场景 |
|---|---|
| `Constants` | 全局常量（JWT 字段、权限标识、资源前缀等） |
| `CacheConstants` | Redis key 前缀统一管理 |
| `HttpStatus` | 返回状态码常量 |
| `GenConstants` | 代码生成器常量 |
| `ScheduleConstants` | 调度任务常量 |
| `UserConstants` | 用户/角色状态常量 |

### `core.controller`
| 类 | 使用场景 |
|---|---|
| `BaseController` | 分页、排序、安全用户获取、统一响应快捷方法 |

### `core.domain`
| 类 | 使用场景 |
|---|---|
| `AjaxResult` | 标准接口返回体（Map 风格） |
| `R<T>` | 泛型响应体（类型化返回） |
| `BaseEntity` | 审计字段与 `params` 扩展参数 |
| `TreeEntity`/`TreeSelect` | 树结构实体与前端下拉树数据 |

### `core.domain.entity`
| 类 | 使用场景 |
|---|---|
| `SysUser` | 用户领域共享实体（含校验、Excel 注解） |
| `SysRole` | 角色与数据权限范围 |
| `SysDept` | 部门树领域实体 |
| `SysMenu` | 菜单与权限节点 |
| `SysDictType`/`SysDictData` | 字典类型与字典项 |

### `core.domain.model`
| 类 | 使用场景 |
|---|---|
| `LoginBody` | 登录请求体 |
| `RegisterBody` | 注册请求体 |
| `LoginUser` | 安全上下文主体（token、权限、登录态） |

### `core.page`
| 类 | 使用场景 |
|---|---|
| `PageDomain` | 分页参数承载 |
| `TableSupport` | 从请求提取分页参数 |
| `TableDataInfo` | 表格分页响应结构 |

### `core.redis`
| 类 | 使用场景 |
|---|---|
| `RedisCache` | 对 `RedisTemplate` 的统一封装（对象/列表/集合/Map/过期） |

### `core.text`
| 类 | 使用场景 |
|---|---|
| `Convert` | 安全类型转换 |
| `StrFormatter` | `{}` 占位符格式化 |
| `CharsetKit` | 字符集处理 |

### `enums`
| 类 | 使用场景 |
|---|---|
| `BusinessType`/`OperatorType` | 操作日志分类 |
| `DataSourceType` | 主从数据源策略 |
| `LimitType` | 限流维度（默认/IP） |
| `HttpMethod` | 请求方法匹配 |
| `UserStatus`/`BusinessStatus` | 状态语义统一 |
| `DesensitizedType` | 脱敏策略函数集合 |

### `exception`
| 类 | 使用场景 |
|---|---|
| `BaseException` | 业务基础异常（支持国际化 code） |
| `ServiceException` | 服务层运行时异常（可带状态码） |
| `UtilException` | 工具类异常 |
| `DemoModeException`/`GlobalException` | 演示模式与全局业务异常 |
| `file.*` | 文件上传、大小、扩展名异常 |
| `user.*` | 登录、验证码、密码重试、黑名单异常 |
| `job.TaskException` | 定时任务执行异常 |

### `filter`
| 类 | 使用场景 |
|---|---|
| `RepeatableFilter`/`RepeatedlyRequestWrapper` | JSON 请求体可重复读取 |
| `XssFilter`/`XssHttpServletRequestWrapper` | 请求参数与 JSON 体 XSS 清洗 |
| `RefererFilter` | 防盗链 Referer 校验 |
| `PropertyPreExcludeFilter` | JSON 属性排除辅助 |

### `utils`（重点工具类补充）
| 类 | 使用场景 |
|---|---|
| `StringUtils` | 字符串/集合空判断、模板格式化、命名转换 |
| `DateUtils` | 日期解析与格式化 |
| `SecurityUtils` | 获取当前用户、权限匹配、密码加密 |
| `ServletUtils` | request/response/session 获取与渲染 |
| `PageUtils` | 分页启动与清理 |
| `DictUtils` | 字典缓存读写与标签值转换 |
| `FileUploadUtils` | 统一上传路径、命名、扩展名校验 |
| `FileUtils`/`ImageUtils`/`MimeTypeUtils` | 文件读写、图片处理、类型识别 |
| `ExcelUtil` | Excel 导入导出核心工具 |
| `SqlUtil` | orderBy 白名单校验与关键字过滤 |
| `IpUtils`/`AddressUtils` | IP 解析与归属地查询 |
| `HttpUtils`/`HttpHelper`/`UserAgentUtils` | HTTP 调用、请求体读取、UA 解析 |
| `SpringUtils` | 非托管代码获取 Bean/环境信息 |
| `BeanUtils`/`BeanValidators`/`ReflectUtils` | Bean 复制、校验、反射访问 |
| `IdUtils`/`UUID`/`Seq` | 唯一 ID 与序列号 |
| `Md5Utils`/`Base64` | 摘要与编码 |

### `xss`
| 类 | 使用场景 |
|---|---|
| `Xss` | 字段级 XSS 校验注解 |
| `XssValidator` | XSS 校验实现 |

## 写代码时的实用提示（聚焦 common）
- 返回值统一：优先使用 `AjaxResult`/`TableDataInfo`，避免模块间返回结构不一致。
- 分页与排序安全：动态排序字段必须走 `SqlUtil.escapeOrderBySql` 逻辑。
- Redis key 必须使用 `CacheConstants` 前缀，避免不同模块 key 冲突。
- 上传逻辑优先复用 `FileUploadUtils`，不要在业务层重复拼接文件路径。
- 涉及脱敏字段优先用 `@Sensitive`，不要在 Controller 手工字符串处理。
- 新增通用能力时，先判断是否应放在 `ruoyi-common`（跨模块复用）还是业务模块（仅单域使用）。
-												初始化

- 添加 AGENTS.md 项目架构指南文档
- 添加 ruoyi-ui 前端项目的 .editorconfig 代码规范配置
- 添加 ruoyi-ui 项目的 .env.development、.env.production、.env.staging 环境变量配置文件
- 添加前后端项目的 .gitignore 忽略文件配置
- 添加 ruoyi-ui 前端 401 和 404 错误页面组件
- 添加 quartz 任务调度抽象基类和 IP 地址获取工具类
- 添加 AjaxResult 统一响应结果类和 Anonymous 匿名访问注解
- 添加 代码生成器 API 模板文件
- 添加 Vue 应用程序入口和状态管理配置
- 添加 后端 application.yml 主配置文件

											
										
										
											3 weeks ago
+								# Repository Guidelines
 								## 文档定位
 								本文件聚焦“写代码时需要的架构与模块提示信息”，不包含 Git 流程、编译或测试命令。
 								## 系统架构总览
 								- 工程形态：Maven 多模块单体应用，前后端分离（`ruoyi-ui` + Spring Boot 后端）。
 								- 模块分层：
 								  - `ruoyi-admin`：应用入口、Controller 暴露层。
 								  - `ruoyi-framework`：安全认证、AOP、拦截器、数据权限与限流实现层。
 								  - `ruoyi-system`：系统业务域（用户/角色/菜单/字典等）服务层。
 								  - `ruoyi-common`：跨模块基础设施与通用契约层。
 								  - `ruoyi-quartz`：任务调度能力层。
 								  - `ruoyi-generator`：代码生成能力层。
 								- 关键依赖方向：`admin -> framework -> system -> common`，`quartz/generator -> common`。
 								## Backend Tech Stack (With Versions)
 								版本来源：根 `pom.xml` 的 `properties` 与 `dependencyManagement`。
 								| 技术 | 版本 | 说明 |
 								|---|---:|---|
 								| Java | 17 | 语言与运行时基线 |
 								| Spring Boot BOM | 3.5.8 | Spring 生态版本管理 |
 								| MyBatis Spring Boot Starter | 3.0.5 | ORM/Mapper |
 								| Druid Spring Boot 3 Starter | 1.2.27 | 数据源与连接池 |
 								| PageHelper Starter | 2.1.1 | 分页 |
 								| MySQL Connector/J | 8.2.0 | MySQL 驱动 |
 								| SpringDoc OpenAPI | 2.8.14 | API 文档 |
 								| Spring Security | 由 Boot 3.5.8 管理 | 认证鉴权 |
 								| Spring Data Redis | 由 Boot 3.5.8 管理 | 缓存/会话 |
 								| JJWT | 0.9.1 | JWT |
 								| Quartz | 2.5.2 | 定时任务 |
 								| Fastjson2 | 2.0.60 | JSON |
 								| Apache POI | 4.1.2 | Excel 导入导出 |
 								| Velocity | 2.3 | 代码生成模板 |
 								| Kaptcha | 2.3.3 | 验证码 |
 								| YAUAA | 7.32.0 | User-Agent 解析 |
 								| OSHI | 6.9.1 | 主机监控信息 |
 								| Commons IO | 2.21.0 | IO 工具 |
 								| Jakarta Servlet API | 6.0.0 | Servlet 规范 |
 								## ruoyi-common 模块深度分析
 								### 模块定位与边界
 								- `ruoyi-common` 是后端基础设施层，提供统一契约、基类、工具和安全过滤，不承载业务流程。
 								- 当前约 `109` 个 Java 类，属于项目复用中心模块。
 								### 包结构概览（一级包）
 								- `utils`（36）：通用工具主集合。
 								- `core`（22）：Controller/Domain/Page/Redis/Text 基础抽象。
 								- `exception`（18）：统一异常体系。
 								- `annotation`（9）：横切能力注解契约。
 								- `constant`（6）/`enums`（8）：常量与策略枚举。
 								- `filter`（6）/`xss`（2）：请求过滤与输入安全。
 								- `config`（2）：通用配置与序列化器。
 								### 架构中心性（跨模块复用）
 								- `ruoyi-framework`: 148 次 `import com.ruoyi.common.*`
 								- `ruoyi-admin`: 138 次
 								- `ruoyi-system`: 86 次
 								- `ruoyi-quartz`: 40 次
 								- `ruoyi-generator`: 25 次
 								- 高频类：`StringUtils`、`AjaxResult`、`Constants`、`BaseController`、`SecurityUtils`、`ExcelUtil`。
 								### 设计机制（写代码时重点）
 								- 契约与实现分离：`@DataScope/@RateLimiter/@RepeatSubmit/@Log` 定义在 common，实现放在 framework 的 Aspect/Interceptor。
 								- 统一返回规范：Controller 继承 `BaseController`，统一输出 `AjaxResult`/`TableDataInfo`。
 								- 统一实体扩展位：`BaseEntity.params` 用于数据权限 SQL 片段等横切参数传递。
 								- 统一安全输入链路：`SqlUtil`、`XssFilter`、`XssValidator`、`RepeatableFilter` 负责请求与参数安全治理。
 								## ruoyi-common 类级别索引清单（按包）
 								### `annotation`
 								| 类 | 使用场景 |
 								|---|---|
 								| `Anonymous` | 标记匿名可访问接口 |
 								| `DataScope` | 服务查询方法注入数据权限条件 |
 								| `DataSource` | 动态切换主从数据源 |
 								| `Excel`/`Excels` | 实体字段导入导出映射 |
 								| `Log` | 业务操作日志切面采集 |
 								| `RateLimiter` | 接口限流（全局或按 IP） |
 								| `RepeatSubmit` | 防重复提交 |
 								| `Sensitive` | 返回字段脱敏 |
 								### `config`
 								| 类 | 使用场景 |
 								|---|---|
 								| `RuoYiConfig` | 读取 `ruoyi.*` 业务基础配置（上传路径、验证码类型等） |
 								| `SensitiveJsonSerializer` | 配合 `@Sensitive` 做序列化脱敏 |
 								### `constant`
 								| 类 | 使用场景 |
 								|---|---|
 								| `Constants` | 全局常量（JWT 字段、权限标识、资源前缀等） |
 								| `CacheConstants` | Redis key 前缀统一管理 |
 								| `HttpStatus` | 返回状态码常量 |
 								| `GenConstants` | 代码生成器常量 |
 								| `ScheduleConstants` | 调度任务常量 |
 								| `UserConstants` | 用户/角色状态常量 |
 								### `core.controller`
 								| 类 | 使用场景 |
 								|---|---|
 								| `BaseController` | 分页、排序、安全用户获取、统一响应快捷方法 |
 								### `core.domain`
 								| 类 | 使用场景 |
 								|---|---|
 								| `AjaxResult` | 标准接口返回体（Map 风格） |
 								| `R<T>` | 泛型响应体（类型化返回） |
 								| `BaseEntity` | 审计字段与 `params` 扩展参数 |
 								| `TreeEntity`/`TreeSelect` | 树结构实体与前端下拉树数据 |
 								### `core.domain.entity`
 								| 类 | 使用场景 |
 								|---|---|
 								| `SysUser` | 用户领域共享实体（含校验、Excel 注解） |
 								| `SysRole` | 角色与数据权限范围 |
 								| `SysDept` | 部门树领域实体 |
 								| `SysMenu` | 菜单与权限节点 |
 								| `SysDictType`/`SysDictData` | 字典类型与字典项 |
 								### `core.domain.model`
 								| 类 | 使用场景 |
 								|---|---|
 								| `LoginBody` | 登录请求体 |
 								| `RegisterBody` | 注册请求体 |
 								| `LoginUser` | 安全上下文主体（token、权限、登录态） |
 								### `core.page`
 								| 类 | 使用场景 |
 								|---|---|
 								| `PageDomain` | 分页参数承载 |
 								| `TableSupport` | 从请求提取分页参数 |
 								| `TableDataInfo` | 表格分页响应结构 |
 								### `core.redis`
 								| 类 | 使用场景 |
 								|---|---|
 								| `RedisCache` | 对 `RedisTemplate` 的统一封装（对象/列表/集合/Map/过期） |
 								### `core.text`
 								| 类 | 使用场景 |
 								|---|---|
 								| `Convert` | 安全类型转换 |
 								| `StrFormatter` | `{}` 占位符格式化 |
 								| `CharsetKit` | 字符集处理 |
 								### `enums`
 								| 类 | 使用场景 |
 								|---|---|
 								| `BusinessType`/`OperatorType` | 操作日志分类 |
 								| `DataSourceType` | 主从数据源策略 |
 								| `LimitType` | 限流维度（默认/IP） |
 								| `HttpMethod` | 请求方法匹配 |
 								| `UserStatus`/`BusinessStatus` | 状态语义统一 |
 								| `DesensitizedType` | 脱敏策略函数集合 |
 								### `exception`
 								| 类 | 使用场景 |
 								|---|---|
 								| `BaseException` | 业务基础异常（支持国际化 code） |
 								| `ServiceException` | 服务层运行时异常（可带状态码） |
 								| `UtilException` | 工具类异常 |
 								| `DemoModeException`/`GlobalException` | 演示模式与全局业务异常 |
 								| `file.*` | 文件上传、大小、扩展名异常 |
 								| `user.*` | 登录、验证码、密码重试、黑名单异常 |
 								| `job.TaskException` | 定时任务执行异常 |
 								### `filter`
 								| 类 | 使用场景 |
 								|---|---|
 								| `RepeatableFilter`/`RepeatedlyRequestWrapper` | JSON 请求体可重复读取 |
 								| `XssFilter`/`XssHttpServletRequestWrapper` | 请求参数与 JSON 体 XSS 清洗 |
 								| `RefererFilter` | 防盗链 Referer 校验 |
 								| `PropertyPreExcludeFilter` | JSON 属性排除辅助 |
 								### `utils`（重点工具类补充）
 								| 类 | 使用场景 |
 								|---|---|
 								| `StringUtils` | 字符串/集合空判断、模板格式化、命名转换 |
 								| `DateUtils` | 日期解析与格式化 |
 								| `SecurityUtils` | 获取当前用户、权限匹配、密码加密 |
 								| `ServletUtils` | request/response/session 获取与渲染 |
 								| `PageUtils` | 分页启动与清理 |
 								| `DictUtils` | 字典缓存读写与标签值转换 |
 								| `FileUploadUtils` | 统一上传路径、命名、扩展名校验 |
 								| `FileUtils`/`ImageUtils`/`MimeTypeUtils` | 文件读写、图片处理、类型识别 |
 								| `ExcelUtil` | Excel 导入导出核心工具 |
 								| `SqlUtil` | orderBy 白名单校验与关键字过滤 |
 								| `IpUtils`/`AddressUtils` | IP 解析与归属地查询 |
 								| `HttpUtils`/`HttpHelper`/`UserAgentUtils` | HTTP 调用、请求体读取、UA 解析 |
 								| `SpringUtils` | 非托管代码获取 Bean/环境信息 |
 								| `BeanUtils`/`BeanValidators`/`ReflectUtils` | Bean 复制、校验、反射访问 |
 								| `IdUtils`/`UUID`/`Seq` | 唯一 ID 与序列号 |
 								| `Md5Utils`/`Base64` | 摘要与编码 |
 								### `xss`
 								| 类 | 使用场景 |
 								|---|---|
 								| `Xss` | 字段级 XSS 校验注解 |
 								| `XssValidator` | XSS 校验实现 |
 								## 写代码时的实用提示（聚焦 common）
 								- 返回值统一：优先使用 `AjaxResult`/`TableDataInfo`，避免模块间返回结构不一致。
 								- 分页与排序安全：动态排序字段必须走 `SqlUtil.escapeOrderBySql` 逻辑。
 								- Redis key 必须使用 `CacheConstants` 前缀，避免不同模块 key 冲突。
 								- 上传逻辑优先复用 `FileUploadUtils`，不要在业务层重复拼接文件路径。
 								- 涉及脱敏字段优先用 `@Sensitive`，不要在 Controller 手工字符串处理。
 								- 新增通用能力时，先判断是否应放在 `ruoyi-common`（跨模块复用）还是业务模块（仅单域使用）。