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`** ，内容集中于三方面:我们在解决什么问题、找到了哪些相关文件（精确到行号）、当前的理解是什么

**记录格式**：
```markdown
## {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)
- **遗留问题**：{如有}
- **进阶方向**：{建议用户接下来可以深入阅读哪方面的文档或优化哪个模块}
---
```