hw-web/AGENTS.md

# Repository Guidelines

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

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

## 官网前端 `portal_website` 深度分析（2026-02-28）

### 模块定位与边界
- `portal_website` 是独立官网展示前端，不复用 `ruoyi-ui` 的后台管理逻辑。
- 主要职责：官网内容展示、产品/方案详情渲染、资料下载、联系信息提交、导航与客服浮窗。
- 数据来源：后端 `/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` 脚本链路） |

### 规模与目录画像（快照统计）
- 代码规模（`src`）：
  - `views`：`32` 文件，约 `4509` 行。
  - `components`：`23` 文件，约 `3093` 行。
  - `api`：`8` 文件，约 `257` 行。
  - `router/utils`：`2` 文件，约 `88` 行。
- `views` 分域：
  - `index`（首页）`7` 文件。
  - `contactUs`（关于海威）`8` 文件。
  - `serviceSupport`（服务支持）`6` 文件。
  - `productCenter`（产品中心）`3` 文件。
  - `industrySolutions`（行业方案）`1` 文件。
  - `page`（菜单驱动 JSON 页面）`1` 文件。
  - `a`（实验/演示页面）`6` 文件。
- `components` 分域：
  - `el`（动态区块引擎）`17` 文件（含 `carousel` 与 `el1`~`el16`）。
  - `menu` `2` 文件（当前主要使用 `index.vue`）。
  - `chat` `1` 文件（全局浮窗客服）。

### 运行与构建链路
- 入口：`src/main.js`，注册 `ElementUI`、全局样式，并加载高德地图 SDK。
- 壳层：`src/layout/index.vue`，包含顶栏菜单、固定浮窗、`<router-view>` 与全局 `Chat`。
- 路由：`src/router/index.js`，主入口 `/` 下挂各业务页面，另有 `/a` 调试页。
- 请求层：`src/utils/request.js` 对 Axios 二次封装，统一返回 `res.data`。
- API 层：`src/api/*.js` 以业务域拆分，统一走 `request`。

### 路由与页面职责（当前实现）
- `/index`：首页聚合（轮播、典型案例、产品中心、联系区块）。
- `/productCenter`：产品聚合页（顶部 banner + 一级产品 tab）。
- `/productCenter/detail`：基于 JSON 区块（`el1`~`el16`）动态渲染产品详情。
- `/industrySolutions`：方案列表卡片页（跳转 `/test?id=xx`）。
- `/contactUs`：关于海威聚合页（公司概况/合作伙伴/媒体中心/资质）。
- `/contactUs/MediaCenterDetail`：媒体详情静态内容页。
- `/serviceSupport`：服务支持聚合（售前/问答/下载等模块，当前启用较少）。
- `/test`：菜单驱动动态页渲染（`getHwWeb(id)`）。
- `/a`：实验性质页面，不属于官网核心链路。

### 核心机制：菜单树 + 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`。

### 样式与组件组织约定
- 全局变量：`src/style.less`（当前维护 `@top-height/@standard-color`）。
- 页面样式单位以 `vw` 为主，倾向 PC 大屏视觉；`scoped + /deep/` 覆盖 Element UI。
- 复用组件优先放 `src/components`；业务拼装放 `src/views/<domain>`。
- 图片资源优先走接口返回 URL；本地 `assets` 用于 logo、兜底图、静态素材。

### 已识别实现特征与风险（修改前先知晓）
- 环境变量与请求基址存在双轨：
  - `.env.development` 配置 `VUE_APP_BASE_API=/dev-api`，但 `request.js` 固定 `baseURL='/prod-api'`。
  - `vue.config.js` 仅代理 `/dev-api`，本地联调时需先确认实际代理链路。
- 路由中 `index` 子路由定义重复一次；修改路由时需先清理重复配置再扩展。
- 菜单跳转强依赖硬编码 `webMenuId`（如 `1/2/4/7/24`）；后台菜单 ID 变化会影响导航。
- 页面中存在较多静态兜底数据与占位实现（特别是 `serviceSupport` 与部分 `contactUs` 子页），新增接口时优先替换静态块而非叠加分支。
- `main.js` 中高德 `key/securityJsCode` 为明文硬编码，后续建议迁移到环境变量。

### 写官网前端代码时的实用提示（聚焦 `portal_website`）
- 新增官网内容优先走“菜单树 + JSON 区块”机制，避免继续堆叠 hardcode 页面。
- 需要可复用展示块时，优先扩展 `components/el`，并保持 `data` 契约稳定。
- API 返回统一按 `res.code/res.data/res.rows` 结构处理，避免页面层自行兼容多形态。
- 处理路由参数时复用既有约定：`id`（菜单/设备）、`type`（产品线）、`typeId`（子分类）。
- 导航相关改造需同时验证：
  - `components/menu/index.vue` 的 `toLink` 映射。
  - `views/productCenter/index.vue` 与 `views/contactUs/index.vue` 的 query 解析。
  - 动态页 `views/page/index.vue` 与详情页 `views/productCenter/detail.vue` 的 JSON 加载逻辑。

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