From e34b86d6bc38524ecbbf0b189c0719f5a7ac08ac Mon Sep 17 00:00:00 2001 From: peijunlei Date: Sat, 5 Sep 2026 10:18:08 +0800 Subject: [PATCH] =?UTF-8?q?feat(documentation):=20=E6=9B=B4=E6=96=B0?= =?UTF-8?q?=E4=B8=8B=E8=BD=BD=E7=9A=84=E6=96=87=E4=BB=B6=E5=90=8D=E7=A7=B0?= =?UTF-8?q?=E4=B8=8D=E4=B8=80=E8=87=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- public/themes/website/1/zh/demo/product.html | 4 +- 项目文档.md | 238 +++++++++++++++++++++++++++ 2 files changed, 241 insertions(+), 1 deletion(-) create mode 100644 项目文档.md diff --git a/public/themes/website/1/zh/demo/product.html b/public/themes/website/1/zh/demo/product.html index b25e546..cd1c55f 100644 --- a/public/themes/website/1/zh/demo/product.html +++ b/public/themes/website/1/zh/demo/product.html @@ -297,6 +297,8 @@ $resource_download = $main_content['resource_download'] ?? []; $dateTmp = $download_names[$key-1][2] ?? ('日期-'.$key); $ext = strtolower(pathinfo($one_resource['url'], PATHINFO_EXTENSION)); $file_type_name = $map[$ext] ?? '未知文件'; + // 下载文件名与页面展示名一致（展示名未带扩展名时补充） + $download_name = ($ext !== '' && strtolower(pathinfo($nameTmp, PATHINFO_EXTENSION)) === $ext) ? $nameTmp : rtrim($nameTmp, '.') . '.' . $ext; {/php}
  • @@ -310,7 +312,7 @@ $resource_download = $main_content['resource_download'] ?? []; 文档生成时间：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 ` 执行： + +- `BaiduTongji` — 百度统计数据采集 +- `WebDiagnosis` / `WebDiagnosis2` / `WebDiagnosis3` — 网站诊断 +- `CreateModel` / `CreateController` / `CreateLink` — 脚手架/代码生成 + +--- + +## 5. 路由设计 + +- **后台**：统一挂在 `route/admin.php`，格式为 `/<模块>/` 映射到 `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 # 命令行任务 + 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/` |