hw-web/AGENTS.md

Repository Guidelines

文档定位

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

系统架构总览

• 工程形态：Maven 多模块单体应用，前后端分离（官网展示端 portal_website + 官网编辑端 portal_website_edit + Spring Boot 后端）。
• 前端职责分工：
  • portal_website：官网展示界面（展示消费端，非代码重点）。
  • portal_website_edit：官网内容编辑后台（当前前端改造重点）。
• 当前实现重点：portal_website_edit（前端编辑）+ ruoyi-portal（后端内容接口）。
• 模块分层：
  • ruoyi-admin：应用入口、Controller 暴露层。
  • ruoyi-framework：安全认证、AOP、拦截器、数据权限与限流实现层。
  • ruoyi-system：系统业务域（用户/角色/菜单/字典等）服务层。
  • ruoyi-common：跨模块基础设施与通用契约层。
  • ruoyi-quartz：任务调度能力层。
  • ruoyi-generator：代码生成能力层。
  • ruoyi-portal：官网内容与菜单相关后端业务模块（/portal/**）。
  • portal_website：官网展示前端（Vue2 + Element UI + 菜单/JSON 驱动页面引擎）。
  • portal_website_edit：官网内容编辑后台前端（Vue2 + Element UI + JSON 区块模板编辑器）。
• 关键依赖方向：admin -> framework -> system -> common，quartz/generator -> common；portal_website/portal_website_edit -> /portal/** -> ruoyi-portal。

官网编辑后台 portal_website_edit 深度分析

模块定位与边界

• portal_website_edit 是官网内容编辑后台，不负责官网最终展示页面渲染。
• 主要职责：维护官网页面 webJsonString、产品中心结构、产品详情模板块、下载文档与密钥。
• 数据写入目标：
  • hwWeb：通用页面 JSON（如首页 webCode=-1、产品中心配置 webCode=7）。
  • hwWeb1：产品详情 JSON（webCode + typeId + deviceId 三元键）。
  • hwWebDocument：下载文档地址、密钥与删除。
• 页面入口非常聚焦：仅 /editor 与 /productCenter/edit 两条核心路由。

前端技术栈（来自 portal_website_edit/package.json）

技术	版本	说明
Vue	2.5.2	编辑后台框架基线
Vue Router	3.0.1	路由管理（默认 hash 模式）
Element UI	2.15.14	表单、表格、弹窗、上传等编辑控件
Axios	1.7.9	HTTP 请求
js-cookie	3.0.5	读取 Admin-Token
Less	4.2.0	样式预处理
Swiper	11.1.15	轮播样式依赖
Quill	2.0.3	富文本样式依赖
AMap JS API Loader	1.0.1	地图 SDK（当前编辑页面使用较少）
ECharts	6.0.0	图表依赖（当前编辑页使用较少）
uuid	11.0.5	文档上传生成 UUID
Vue CLI Service	~5.0.0	主构建工具
Webpack	3.6.0	遗留构建链（dev/dev1/start 脚本）

规模与目录画像（快照统计）

• src 总计：33 文件，约 4611 行。
• 关键目录：
  • views：3 文件，约 1098 行（编辑器入口与产品中心编辑页）。
  • components/editEl：21 文件，约 3199 行（核心模板编辑组件）。
  • api：4 文件，约 186 行。
  • router：1 文件，约 17 行。
  • utils：1 文件，约 32 行。
• 大文件：
  • src/views/editPage/index.vue：639 行（主编辑器）。
  • src/components/editEl/editEl16.vue：325 行（多设备参数表 + 粘贴导入解析）。
  • src/components/editEl/classicCase.vue：301 行。
  • src/views/productCenter/edit/produceModel.vue：285 行。

运行与构建链路

• 入口：src/main.js，注册 ElementUI、全局样式依赖，并加载高德地图 SDK（含明文 key/securityJsCode）。
• 壳层：src/App.vue 仅保留 <router-view/>，并在 mounted 设置页面标题。
• 路由：src/router/index.js 将 / 重定向到 /editor，另有 /productCenter/edit。
• 请求层：src/utils/request.js 固定 baseURL='/prod-api'，请求头从 Cookie 注入 Authorization: Bearer <Admin-Token>，响应统一返回 res.data。
• 上传链路：
  • 图片上传：uploadEl.vue 直传 /prod-api/file/upload，写回 icon/url/banner... 字段。
  • 文件上传：uploadFile.vue 上传后调用 addHwWebDocument 持久化文档地址。
• 构建链路存在双轨：serve/build 走 Vue CLI；dev/dev1/start 走 legacy webpack-dev-server。

路由与页面职责（当前实现）

• /editor（views/editPage/index.vue）：
  • type='1'：行业方案/菜单页编辑。菜单来源 selectMenuTree() 中 webMenuId===4 子树，加载/保存走 getHwWeb/updateHwWeb。
  • type='2'：产品详情页编辑。菜单来源 getHwWeb(7) 的 productList，加载/保存走 listHwWeb1/updateHwWeb1。
  • type='3'：首页区块编辑。加载/保存 getHwWeb(-1)/updateHwWeb(webCode='-1')，编辑 ClassicCase 与 ProductCenter 两类组件。
  • 提供区块增删、上下移动、组件模板选择与保存上传。
• /productCenter/edit（views/productCenter/edit/index.vue）：
  • 编辑 webCode=7 的产品中心聚合配置（banner + 一级产品 tabs + 机型卡片）。
  • tabs 菜单来源 selectMenuTree() 中 webMenuId===7 子树。
  • 子组件 produceModel.vue 提供“二级分类 + 设备卡片”编辑，并跳转到 /editor?type=2&id=... 编辑详情模板。

核心机制：三种编辑模式 + JSON 模板池

• componentsM 是主编辑器的模板池，定义 carousel 与 type=1..16 的默认 JSON 结构。
• 渲染映射：
  • type='carousel' -> components/editEl/carousel.vue
  • type=1..16 -> components/editEl/editEl1.vue ... editEl16.vue
• 组件编辑方式：
  • 文本：以 contenteditable + blur 直接写回 this.$props.data。
  • 集合：push/splice 原地增删。
  • 排序：moveUp/moveDown 通过数组重排。
• 保存方式：统一 JSON.stringify(components) 写入后端 webJsonString。

components/editEl 数据契约（高频）

类型/组件	主要字段结构（value）	说明
carousel	list[{icon,title,value}]	首页/详情轮播编辑
editEl1	title,subTitle,list[{icon,title,value}]	图标卡片（4列栅格）
editEl2	title,subTitle,contentSubTitle,contentTitle,contentInfo,icon	左文右图
editEl3	title,subTitle,list[{icon,itemTitle,itemInfo}]	双列图标信息
editEl4	icon,list[{title,value}]	左大图右四格（最多4项）
editEl5	title,subTitle,icon	标题 + 大图
editEl6	title,subTitle,info,icon	标题说明 + 大图
editEl7	title,subTitle,list[{icon,title,value}]	3列图标块
editEl8	title,subTitle,list[{title,leftTitle,leftInfo,icon,infos[{title,info}]}]	Tab + 左图右参数列表
editEl9	title,subTitle,list[{icon,value}]	上图下文卡片
editEl10	title,subTitle,list[{icon,...}]	三列图集（当前只展示图片）
editEl11	title,subTitle,list[{icon,title,value}]	大图标三列
editEl12	imgList[{url}],features[{name}]	产品图册 + 特点清单
editEl13	params[{title,list[{name,value}]}]	简单参数表
editEl14	fileList[{name,value,url,fileName,uuid}]	资料下载 + 上传 + 密钥设置
editEl15	banner,banner1,bannerTitle,bannerValue	产品 banner 双图文
editEl16	params[{title,columns[],rows[{name,values[],merge}]}]	多设备对比参数表，支持“粘贴导入表格”

• 首页专用编辑组件：
  • classicCase.vue：编辑 classicCaseData[{homeConfigTypeName,caseInfoTitle,caseInfoDesc,caseInfoPic,configTypeId}]。
  • productCenter.vue：编辑 productCenterData[{homeConfigTypePic,configTypeDesc,homeConfigTypeName,linkData}]。
  • views/productCenter/edit/produceModel.vue：编辑产品分类及设备卡片，并路由到详情模板编辑。
• 公共上传组件：
  • uploadEl.vue：图片上传 + 字段回填（默认 icon）。
  • uploadFile.vue：文件上传 + UUID 建档（addHwWebDocument）。

API 域与后端契约

• src/api/hwWeb.js：
  • /portal/hwWeb/*：页面 JSON CRUD。
  • /portal/hwWeb1/*：产品详情 JSON 查询/更新。
• src/api/hwWebMenu.js：/portal/hwWebMenu/* 与 selectMenuTree。
• src/api/hwWebDocument.js：/portal/hwWebDocument/* + getSecureDocumentAddress。
• src/api/productCenter.js：/portal/portal/* 产品中心聚合接口 + 菜单树查询。
• 约定：页面层统一走 utils/request.js，不要直接使用裸 axios。

hw_web.sql 核心表结构与数据快照（重点）

• 数据来源：根目录 hw_web.sql（当前使用中的 MySQL 结构与种子数据，后续会继续演进）。
• 关注重点表：hw_web_menu、hw_web、hw_web1、hw_web_document。
• 其余 hw_* 表可能存在历史保留/阶段性未使用场景，排查问题时优先从上述 4 表入手。
• 快照插入行数（按 dump 中 INSERT INTO 统计）：
  • hw_web：38
  • hw_web1：31
  • hw_web_menu：28
  • hw_web_document：11

表职责与关键字段（按当前实现）

表名	主要用途	主键	关键字段（高频）	说明
hw_web_menu	官网一级/多级菜单树	web_menu_id	parent,ancestors,web_menu_name,web_menu_type,is_delete	前后端主菜单树来源（/portal/hwWebMenu/selectMenuTree）
hw_web	通用页面 JSON（菜单页/首页/产品中心聚合）	web_id	web_code,web_json_string,is_delete,web_json_english	web_code 常与菜单 id 对齐；首页常用 -1，产品中心聚合常用 7
hw_web1	产品详情 JSON（设备维度）	web_id	web_code,typeId,device_id,web_json_string,is_delete	portal_website_edit 的详情编辑核心落表
hw_web_document	下载文件地址与密钥	document_id(varchar/UUID)	document_address,secretKey,web_code,type,is_delete	editEl14 上传资料与密钥校验依赖该表

字段层面注意点（基于 DDL）

• hw_web_menu.web_menu__pic 列名带双下划线，属历史命名，代码中已按该列映射。
• hw_web1 存在 secret_ket（疑似 typo）字段，当前 HwWeb1 领域对象与 Mapper 未使用该列。
• hw_web_document.secretKey 列名采用驼峰，Mapper XML 也按驼峰字段写 SQL。
• 4 张表均采用 is_delete 逻辑删除；Mapper 查询统一过滤 is_delete = '0'。
• 目前这些表仅主键索引，无 web_code 或 (web_code,typeId,device_id) 唯一索引。

与 ruoyi-portal / portal_website_edit 的映射关系

• hw_web_menu：
  • 后端：HwWebMenuController(/portal/hwWebMenu) + selectMenuTree。
  • 前端：portal_website_edit/src/api/hwWebMenu.js 与 src/api/productCenter.js 均调用菜单树。
  • 关键耦合：编辑端硬编码依赖 webMenuId===4/7。
• hw_web：
  • 后端：HwWebController(/portal/hwWeb)。
  • 前端：getHwWeb / updateHwWeb。
  • 典型约定：getHwWeb(-1) 首页配置，getHwWeb(7) 产品中心聚合配置。
• hw_web1：
  • 后端：HwWebController1(/portal/hwWeb1)。
  • 前端：listHwWeb1({ webCode, typeId, deviceId }) 与 updateHwWeb1(...)。
  • 业务键约定：web_code + typeId + device_id。
• hw_web_document：
  • 后端：HwWebDocumentController(/portal/hwWebDocument) + /getSecureDocumentAddress。
  • 前端：uploadFile.vue 上传后写入 document_id(document uuid) + document_address；editEl14 支持密钥设置/删除。

当前实现行为与风险（改动前必读）

• hw_web / hw_web1 在 Service 层采用“版本化写入”：
  • 先按业务键查旧记录并逻辑删除；
  • 再插入新记录（新 web_id）。
• 这会导致同一业务键在库内积累多条历史记录（is_delete='1'），属于预期行为。
• 由于无唯一索引，业务键唯一性由应用层保证；批量并发写入时需注意竞态。
• hw_web_document 密钥逻辑：
  • 查询列表/详情时会隐藏 secretKey，并在有密钥时隐藏 documentAddress；
  • /getSecureDocumentAddress 通过 document_id + providedKey 校验后返回真实地址。

样式与组件组织约定

• 全局 Less 变量：src/style.less（当前仅 @top-height/@standard-color）。
• 样式单位以 vw 为主，默认面向 PC 可视化编辑场景。
• 组件样式普遍采用 scoped + /deep/ 覆盖 Element UI。
• 模板组件集中放在 src/components/editEl，页面编排在 src/views。

已识别实现特征与风险（修改前先知晓）

• 环境与请求基址双轨：
  • .env.development 是 VUE_APP_BASE_API=/dev-api。
  • 但 request.js/上传组件都固定 /prod-api，且 vue.config.js 仅代理 /prod-api。
• 强耦合硬编码：
  • getHwWeb(7)（产品中心配置）、getHwWeb(-1)（首页配置）。
  • selectMenuTree 中写死 webMenuId===4/7。
• 鉴权依赖 Cookie：所有请求默认拼接 Admin-Token，无 token 刷新或兜底逻辑。
• 地图安全配置明文：main.js 暴露 key/securityJsCode。
• 编辑方式是“直接改对象”：
  • 大量 contenteditable + blur + this.$props.data 原地改值，缺少 schema 校验与输入过滤。
• 局部实现细节需注意：
  • editEl8.vue 子项删除使用 splice(k, 1)（应关注内层索引 kk 语义）。
  • productCenter.vue 的 pageChange 同时写 this.$props.data.productCenterData.linkData，语义上是数组级字段。
• 构建链路老旧混用：Vue CLI 5 与 Webpack 3 脚本并存，升级依赖时需同时验证。

写 portal_website_edit 代码时的实用提示

• 新增区块模板时必须同步修改：
  • src/views/editPage/index.vue：注册组件、componentsM 模板、弹窗入口。
  • src/components/editEl/：新增模板实现文件。
  • （若依赖产品详情链路）验证 type=2 下 listHwWeb1/updateHwWeb1 的入参与保存。
• 保持 JSON 契约稳定：优先在现有字段上演进，避免随意变更 webJsonString 结构。
• 涉及资料下载能力时优先复用 editEl14 + uploadFile + hwWebDocument，避免页面内重复上传逻辑。
• 导航/菜单改造时至少联动验证三处：
  • /editor 的 typeChange/pageChange。
  • /productCenter/edit 的 tabs 与 produceModel 跳转参数。
  • classicCase/productCenter 两个首页编辑组件的菜单绑定行为。
• 若要补充展示端能力，优先先确认消费端（已脱离本仓库）是否支持新增 type 与字段结构。

官网前端 portal_website 模块说明（恢复）

定位说明：portal_website 主要用于官网展示界面，不是当前代码改造重点；实际开发优先关注 portal_website_edit 与 ruoyi-portal。

模块定位与边界

• portal_website 是独立官网展示前端，不复用后台管理逻辑。
• 主要职责：官网内容展示、产品/方案详情渲染、资料下载、联系信息提交、导航与客服浮窗。
• 数据来源：后端 /portal/** 系列接口（重点是 hwWebMenu 菜单树 + hwWeb/hwWeb1 JSON 页面数据）。

前端技术栈（来自 portal_website/package.json）

技术	版本	说明
Vue	2.5.2	官网框架基线
Vue Router	3.0.1	路由管理（history 未开启，默认 hash 模式）
Element UI	2.15.14	UI 组件库
Axios	1.7.9	HTTP 请求
Less	4.2.0	样式预处理
Swiper	11.1.15	轮播/滑动
Quill	2.0.3	富文本样式依赖
AMap JS API Loader	1.0.1	地图加载
ECharts	6.0.0	图表能力（当前业务页使用较少）
Vue CLI Service	~5.0.0	主构建工具
Webpack	3.6.0	遗留构建依赖（用于 dev/dev1 脚本链路）

路由与页面职责（现有约定）

• /index：首页聚合（轮播、典型案例、产品中心、联系区块）。
• /productCenter：产品聚合页（顶部 banner + 一级产品 tab）。
• /productCenter/detail：基于 JSON 区块（el1~el16）动态渲染产品详情。
• /industrySolutions：方案列表卡片页（跳转 /test?id=xx）。
• /contactUs：关于海威聚合页（公司概况/合作伙伴/媒体中心/资质）。
• /contactUs/MediaCenterDetail：媒体详情静态内容页。
• /serviceSupport：服务支持聚合（售前/问答/下载等）。
• /test：菜单驱动动态页渲染（getHwWeb(id)）。

核心机制：菜单树 + JSON 区块渲染

• 顶部导航来源：selectMenuTree()，webMenuId 驱动路由跳转。
• 动态页面来源：
  • /test 页面：getHwWeb(id) 读取 webJsonString，按 type 映射到 components/el/*。
  • 产品详情页：listHwWeb1({ webCode, typeId, deviceId }) 读取 JSON 同样映射区块。
• 区块映射：type === 1..16 -> el1..el16；type === 'carousel' -> components/el/carousel.vue。

components/el 数据契约（高频）

• 通用字段：大量区块约定 title/subTitle/list/icon/value。
• 典型结构：
  • el1/el3/el7/el11：图标 + 文本列表。
  • el2/el4：左右分栏图文。
  • el5/el6/el10：大图/图集展示。
  • el8：Tab + 左侧主图 + 右侧参数列表。
  • el12：产品图册 + 特点列表。
  • el13/el16：参数表（支持 columns/rows，含合并行策略）。
  • el14：资料下载（含密钥弹窗与 getSecureDocumentAddress）。
  • el15：Banner 双图文。
• 新增区块类型时，需同步修改：
  • src/views/page/index.vue
  • src/views/productCenter/detail.vue
  • src/components/el/ 新增实现文件

API 域与后端契约

• 门户聚合接口：/portal/portal/*（首页、案例、联系、关于等）。
• 菜单接口：/portal/hwWebMenu/*（导航树与菜单管理）。
• JSON 页面接口：/portal/hwWeb*（页面区块 JSON 存储与查询）。
• 资料接口：/portal/hwWebDocument/*（文档列表、密钥校验、下载地址）。
• 前端调用统一以 request.js 为入口，业务层不要直接使用裸 axios。

已识别实现特征与风险（展示端）

• 环境变量与请求基址可能存在双轨：.env 与 request.js 固定 baseURL 需联动核对。
• 菜单跳转较依赖硬编码 webMenuId；后台菜单 ID 变化会影响导航。
• 展示页历史上存在静态兜底数据；新增接口时优先替换静态块而非叠加分支。
• main.js 的地图 key/securityJsCode 曾采用明文硬编码，建议统一收敛到环境变量。

写展示端代码时的实用提示（聚焦 portal_website）

• 新增官网内容优先走“菜单树 + JSON 区块”机制，避免继续堆叠 hardcode 页面。
• 需要可复用展示块时，优先扩展 components/el，并保持 data 契约稳定。
• API 返回统一按 res.code/res.data/res.rows 结构处理，避免页面层自行兼容多形态。
• 处理路由参数时复用既有约定：id（菜单/设备）、type（产品线）、typeId（子分类）。

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（跨模块复用）还是业务模块（仅单域使用）。

项目记忆规则（私人助理模式）

重要：每次完成任务后，必须将任务记录追加到项目记忆文件 {项目根目录名称}_memory.md ，内容集中于三方面:我们在解决什么问题、找到了哪些相关文件（精确到行号）、当前的理解是什么

记录格式：

## {YYYY-MM-DD}(北京时间)
### 1、执行清单 (Execution)
- **任务目标**：{描述具体需求，描述本次解决了什么业务问题}
- **关键产出**：{列出新增/修改的核心文件路径、API 路径或组件名称}
### 2、技术洞察与复盘 (Tech Insights)
- **核心逻辑模式**：{说明本次采用了什么设计模式或架构思路，如：策略模式实现多工厂算法、MPJ 实现多表关联等}
- **为什么这样写 (The Why)**：{对比普通写法，解释当前方案在可维护性或扩展性上的优势}
- **潜在风险提醒**：{记录 AI 在实现过程中发现的风险点，如：大表关联性能、并发冲突风险等}
### 3、专属学习区 (Learning Log)
- **今日新见识**：{从本次代码中抽取 1 个用户可能不熟悉的知识点，如：某个 TS 特性、Java 17 新语法或 MPJ 高级用法}
- **1分钟本质理解**：{用最通俗的话解释这个知识点的本质，帮用户快速建立直觉}
### 4、下一步建议 (Next Steps)
- **遗留问题**：{如有}
- **进阶方向**：{建议用户接下来可以深入阅读哪方面的文档或优化哪个模块}
---