# 睿能科技官网（rui-neng）项目文档

> 文档生成时间：2026-09-05
> 项目路径：`D:\phpstudy_pro\WWW\rui-neng`
> 代码仓库：https://git-online.zhco.com/wjd/rui-neng （默认分支 `master`）

---

## 1. 项目概述

本项目是**睿能科技**的企业官网，基于 **HuoCMS V3.5.1**（`version` 文件标识）二次开发而成。HuoCMS 是一款基于 ThinkPHP 6 的多站点、多语言内容管理系统（CMS），支持可视化建站、内容模型自定义、SEO 管理、询盘（Inquiry）收集等企业官网核心能力。

本项目当前主要服务于睿能科技官网的前台页面定制（产品、新闻、联系、关于等页面样式与跳转调整），并通过 HuoCMS 后台进行内容与站点管理。

### 核心特性

- **多站点 / 多语言**：支持简体中文（zh）、繁体中文（tc）、英文（en）三种语言版本，路由按站点 ID + 语言拆分文件管理。
- **可视化设计**：支持页面可视化设计器（Design）、主题管理（Theme）、主题文件编辑。
- **内容模型**：自定义内容模型（Module）与字段（ModuleField），栏目-内容树形结构。
- **询盘/表单**：询盘管理、自定义表单（DiyForm）、询盘邮件通知。
- **SEO**：关键词管理、Sitemap、robots、SEO 检测、Google 统计对接。
- **插件机制**：插件以独立目录形式组织（如 `user` 用户插件、`api` 插件），可扩展路由、控制器、模型。
- **多存储后端**：本地、七牛（Qiniu）、腾讯云 COS、阿里云 OSS。

---

## 2. 技术栈

| 分类 | 技术 | 版本要求 |
|---|---|---|
| 语言 | PHP | >= 7.2 |
| 框架 | ThinkPHP | ^6.0 |
| ORM | topthink/think-orm | ^2.0 |
| 数据库迁移 | topthink/think-migration | ^3.0 |
| 模板引擎 | topthink/think-template / think-view | ^2.0 / ^1.0 |
| HTTP 客户端 | guzzlehttp/guzzle | ~6.0 |
| Excel | phpoffice/phpspreadsheet | 1.18.0 |
| WebSocket/长连接 | workerman、workerman/phpsocket.io、workerman/mysql | ^4.0 / ^1.1 / ^1.0 |
| 对象存储 | qiniu/php-sdk、qcloud/cos-sdk-v5、aliyuncs/oss-sdk-php | — |
| 表单构建 | xaboy/form-builder | ~2.0 |
| 邮件 | yzh52521/think-mail、phpmailer/phpmailer | — |
| 短信 | alibabacloud/dysmsapi-20170525（阿里云短信） | 2.0.18 |
| JWT | easyswoole/jwt | ^2.0 |
| 简繁转换 | overtrue/pinyin、php-opencc（本地 extend） | — |
| 海报 | hedali/poster | dev-main |
| 爬虫/采集 | electrolinux/phpquery、zoujingli/ip2region | — |

**PHP 扩展依赖**：`xmlwriter`、`json`、`simplexml`、`zip`、`dom`、`xlswriter`、`openssl`、`bcmath`。

**运行环境**：本地使用 phpstudy_pro 部署（站点根目录为 `public/`），数据库为 MySQL（当前 `.env` 中库名 `rui_neng_test`，表前缀 `hc_`）。

---

## 3. 目录结构

```
rui-neng/
├── app/                        # 应用主目录（PSR-4: app\）
│   ├── controller/
│   │   ├── backend/            # 后台管理控制器（60+ 个）
│   │   ├── frontend/           # 前台控制器（列表、详情、搜索、表单、询盘、SEO、标签）
│   │   └── api/                # API 控制器
│   ├── model/                  # 数据模型（71 个，如 Content、Category、Inquiry…）
│   ├── service/                # 业务服务层（30+ 个，含 keywordMonitor、sms、upload 子目录）
│   ├── middleware/             # 中间件（登录、权限、禁用、插件路由）
│   ├── listener/               # 事件监听（管理员登录/操作日志）
│   ├── validate/               # 验证器
│   ├── command/                # 命令行任务（百度统计、Web 诊断、代码生成等）
│   ├── hcinterface/            # 系统设置接口（SysSettingInterface）
│   ├── hctrait/                # 公共 Trait
│   ├── common.php              # 公共函数
│   ├── event.php               # 事件定义
│   ├── provider.php            # 容器绑定
│   └── middleware.php          # 全局中间件
├── config/                     # 框架与业务配置（app、database、jwt、rbac、route、system 等）
├── route/                      # 路由定义
│   ├── admin.php               # 后台路由（安装、登录、各管理模块）
│   ├── index.php               # 前台公共路由（询盘、标签、搜索、表单、SEO 等）
│   ├── 1_zh_frontend.php       # 站点1 中文前台路由（域名绑定 ruineng.test.cc）
│   ├── 1_tc_frontend.php       # 站点1 繁体
│   ├── 1_en_frontend.php       # 站点1 英文
│   ├── 1_zh_plugin_api.php     # 站点1 插件 API 路由
│   ├── 4_*                     # 站点4 对应路由（多站点）
│   └── app.php                 # 默认示例路由
├── plugins/                    # 插件（PSR-4: plugins\）
│   ├── user/                   # 用户插件（含 install.sql、api/backend/模型/监听）
│   └── api/                    # API 插件
├── extend/                     # 扩展类库（helper、sys、traits、php-opencc）
├── view/                       # 后台视图（common：css/html/js）
├── public/                     # Web 根目录
│   ├── index.php               # 前台入口
│   ├── admin.php               # 后台入口
│   ├── themes/website/1/       # 站点1 主题模板（zh / en 两套语言目录）
│   ├── static/、customStatic/  # 静态资源
│   ├── storage/、system_file/  # 上传存储
│   └── tinymce/                # 富文本编辑器
├── data/、backup/              # 数据与备份
├── runtime/                    # 运行时缓存/日志
├── tests/                      # 测试
├── think                       # 命令行入口
├── composer.json               # 依赖管理
└── .env                        # 环境配置（APP/DATABASE/LANG）
```

---

## 4. 模块说明

### 4.1 后台管理（app/controller/backend）

通过 `public/admin.php` 入口 + `route/admin.php` 路由访问，主要功能模块：

| 分类 | 控制器 |
|---|---|
| 权限体系 | Admin（管理员）、Role（角色）、AdminMenu（菜单）、AdminLoginLog / AdminOptLog（登录与操作日志） |
| 站点管理 | Website（多站点）、WebsiteLang、WebsiteSetting、WebsiteServer、SysSetting（系统设置）、SystemInstall（安装向导） |
| 内容体系 | Category（栏目）、Content（内容）、ContentTag、Module / ModuleField（内容模型与字段）、Tag（标签）、RecycleBin（回收站） |
| 营销/展示 | Slide / SlideCate（轮播）、Advertisement（广告）、Link（友情链接）、Nav / NavCate（导航）、Material（素材）、Poster（海报）、SocialMarketing |
| 询盘/表单 | Inquiry / InquiryCategory / InquiryEmail（询盘及邮件）、Form（自定义表单）、Excel（导入导出） |
| 招聘 | Job / JobCate / JobCity |
| SEO | Keyword / KeywordQuery / KeywordWebsite、Seo / SeoAccount / SeoCheck / SeoSetting、SiteMap、GoogleStatistics |
| 其他 | Attachment / AttachmentCate（附件）、Database（数据库备份）、Theme / ThemeFile（主题）、Plugin（插件）、StaticFile（静态文件）、Dashboard（仪表盘）、Statistics / InnerChart（统计图表） |

### 4.2 前台（app/controller/frontend）

- `List`：栏目列表页（首页也是特定栏目的列表页，如站点1首页绑定栏目 id=36）
- `Detail`：内容详情页（URL 形如 `/栏目拼音/:id`）
- `Search`：站内搜索（含视频、公告等返回值）
- `Tag`：标签页（`/tag`、`/tagList/:id`）
- `Form`：自定义表单展示与提交（`/c/:code`、`/addFormData`、文件上传与下载）
- `Inquiry`：询盘提交（`POST /inquiry/save`）
- `Design`：可视化设计页面
- `Seo`：robots.txt、sitemap.xml、sitemap HTML 页

### 4.3 插件（plugins/）

- **user**：会员用户体系插件，含前台 API、后台管理、模型、验证器、`install.sql`。
- **api**：对外 API 插件。

插件路由由全局中间件 `PluginsMiddleware` 初始化，路由文件存放在各插件的 `route/` 目录，并合并进 `route/{站点}_{语言}_plugin_api.php` 体系。

### 4.4 中间件

| 中间件 | 作用 |
|---|---|
| `think\middleware\LoadLangPack` | 多语言加载（全局启用） |
| `think\middleware\SessionInit` | Session 初始化（全局启用） |
| `app\middleware\PluginsMiddleware` | 插件路由初始化（全局启用） |
| `app\middleware\LoginMiddleware` | 后台登录校验 |
| `app\middleware\AuthMiddleware` | 后台 RBAC 权限校验（配置见 `config/rbac.php`） |
| `app\middleware\ApiLoginMiddleware` | API 登录态校验（JWT，配置见 `config/jwt.php`） |
| `app\middleware\ForbiddenMiddleware` | 禁用/拦截校验 |

### 4.5 服务层（app/service）

核心服务：`ContentService`（内容）、`CategoryService`（栏目）、`ModuleService` / `ModuleFieldService`（模型字段）、`WebsiteService` / `WebsiteLangService`（站点与语言）、`ThemeService` / `ThemeFileService`（主题）、`SitemapService`、`EmailService`（邮件）、`ExcelService`、`MysqlBackupService`（数据库备份）、`TranslateService`（翻译/简繁）、`PluginService`、`CacheService`、`BeautifyHtmlService`（HTML 美化）等；子目录 `sms/`（短信）、`upload/`（多存储上传）、`keywordMonitor/`（关键词监控）。

### 4.6 命令行任务（app/command）

通过 `php think <command>` 执行：

- `BaiduTongji` — 百度统计数据采集
- `WebDiagnosis` / `WebDiagnosis2` / `WebDiagnosis3` — 网站诊断
- `CreateModel` / `CreateController` / `CreateLink` — 脚手架/代码生成

---

## 5. 路由设计

- **后台**：统一挂在 `route/admin.php`，格式为 `/<模块>/<action>` 映射到 `backend` 前缀控制器；安装向导与登录接口独立于权限中间件之外。
- **前台公共**：`route/index.php` 定义询盘、标签、搜索、表单、设计器、SEO 等公共路由。
- **站点路由**：按「站点ID_语言_frontend」命名（如 `1_zh_frontend.php`），使用 `Route::domain()` 绑定域名（如站点1中文绑定 `ruineng.test.cc`），栏目列表/详情路由由 CMS 根据栏目拼音自动生成（`List/index?id=栏目ID`、`Detail/index?cid=栏目ID`，详情 id 为数字）。
- **多语言**：zh / tc / en 三份路由文件，确保多语言 URL 独立。

---

## 6. 数据库

- 数据库连接配置于 `.env`（`[DATABASE]` 段）与 `config/database.php`；当前本地库：`rui_neng_test`，表前缀：`hc_`。
- 模型层共 71 个模型（`app/model`），核心表（按前缀 `hc_` 推断）：
  - 内容：`hc_content`、`hc_category`、`hc_model`（内容模型）、`hc_model_field`、`hc_content_tag`、`hc_tag`
  - 站点：`hc_website`、`hc_website_lang`、`hc_website_setting`
  - 权限：`hc_admin`、`hc_role`、`hc_admin_menu`、`hc_admin_login_log`、`hc_admin_opt_log`
  - 询盘/表单：`hc_inquiry`、`hc_inquiry_category`、`hc_inquiry_email`、`hc_diy_form`
  - 展示：`hc_slide`、`hc_advertisement`、`hc_link`、`hc_nav`、`hc_attachment`
  - 其他：`hc_job` 系列、`hc_keyword` 系列、用户插件表（见 `plugins/user/install.sql`）
- 数据库迁移使用 `topthink/think-migration`；后台提供数据库备份（`MysqlBackupService` / `DatabaseController`）。

---

## 7. 本地部署与开发

1. **环境**：phpstudy_pro（PHP >= 7.2，启用 `xlswriter`、`zip`、`bcmath`、`openssl`、`simplexml`、`xmlwriter`、`dom` 等扩展），MySQL。
2. **站点配置**：网站根目录指向 `D:\phpstudy_pro\WWW\rui-neng\public`，入口 `index.php`（前台）/ `admin.php`（后台）。
3. **依赖安装**：`composer install`（注意 `minimum-stability: dev`，`extend/php-opencc` 以 path 仓库引入）。
4. **环境配置**：复制/编辑 `.env`，配置 `[APP]`、`[DATABASE]`、`[LANG]`。
5. **安装向导**：首次部署访问后台安装路由（`/install` 系列）完成安装检测。
6. **常用命令**：
   ```bash
   php think <command>          # 命令行任务
   php think service:discover   # 服务发现（composer 脚本自动触发）
   ```

---

## 8. 二次开发说明（本项目定制点）

根据近期 Git 提交记录，本项目相对 HuoCMS 原版的改动集中在**站点1 前台主题定制**（`public/themes/website/1/`，zh/en 两套模板）：

- 首页跳转逻辑调整、导航栏「展会与活动」跳转
- 底部导航调整、底部 logo 更换为深色版本
- 可展开遮罩导航（mask navigation）支持子项
- 产品页移动端样式（图片大小限制、内边距）、分类导航移动端不固定
- 联系页面表单结构（添加锚点 ID）、标题显示、圆角调整
- 新闻详情分页 hover 样式、关于页段落样式
- 路由复用优化、搜索返回值修复

开发建议：

- 前台页面改动优先在主题目录 `public/themes/website/{站点ID}/{语言}/` 内进行，避免直接修改框架文件，便于后续 HuoCMS 版本升级合并。
- 栏目路由由后台「栏目管理」的栏目拼音自动生成，新增栏目后需确认对应站点语言路由文件已更新。
- 多语言内容通过 `WebsiteLang` / `TranslateService` 管理，简繁转换依赖 `extend/php-opencc`。

---

## 9. 目录速查

| 需要改什么 | 去哪里 |
|---|---|
| 后台接口/业务 | `app/controller/backend/` + `app/service/` |
| 前台页面逻辑 | `app/controller/frontend/` |
| 前台页面模板/样式 | `public/themes/website/{站点ID}/{语言}/` |
| 路由 | `route/`（后台 `admin.php`，前台公共 `index.php`，站点 `1_zh_frontend.php` 等） |
| 数据模型 | `app/model/` |
| 配置 | `config/` + `.env` |
| 插件 | `plugins/` |
| 静态资源/上传 | `public/static/`、`public/storage/` |
| 日志/缓存 | `runtime/` |