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