新增文档说明

README.md

@@ -0,0 +1,210 @@
+# BlackFruit-UI
+
+BlackFruit-UI（品牌名称“主题云”）是一套面向云服务商官网场景的静态前端模板。项目围绕“首页 + 产品 + 解决方案 + 文档 + 资讯 + 合作伙伴 + 客户支持”全链路体验打造，所有页面可直接由任意 Web Server 托管，同时又兼容服务端模板引擎（Smarty/ThinkPHP 风格）以便与现有业务系统整合。
+
+## 目录
+1. [项目概述](#1-项目概述)
+2. [技术栈与依赖](#2-技术栈与依赖)
+3. [目录结构](#3-目录结构)
+4. [核心页面与脚本职责](#4-核心页面与脚本职责)
+5. [公共模板与数据注入机制](#5-公共模板与数据注入机制)
+6. [接口与数据契约](#6-接口与数据契约)
+7. [本地预览、联调与部署](#7-本地预览联调与部署)
+8. [自定义与二次开发指引](#8-自定义与二次开发指引)
+9. [常见问题与调试建议](#9-常见问题与调试建议)
+10. [维护清单](#10-维护清单)
+
+## 1. 项目概述
+
+BlackFruit-UI 提供 40+ 个静态 HTML 页面，覆盖品牌展示、产品售卖、行业方案、内容资讯、客服支持、合作推广及活动营销等业务场景。通过极少量的 JavaScript 调用 `/console/v1/*` 系列接口即可完成动态数据渲染，适合作为现成模板嵌入到任意云产品后台或 IDC 运营系统中。
+
+### 1.1 功能亮点
+- **纯前端实现**：无需打包/编译，部署即用；文件结构可直接复制到 Nginx/Apache/OSS 等静态资源服务。
+- **模板可复用**：广泛使用 `{include file=""}`、`{if}`、`{foreach}` 等服务端模板语法，方便与现有 PHP/Smarty/ThinkPHP 项目拼装。
+- **统一脚本与样式**：`common/common.js`、`common/*.css` 封装了登录态、导航、常见交互；`css/*.less` 与编译后的 `.css` 同时提供，便于定制主题。
+- **丰富页面库**：覆盖云服务器、物理裸机、域名、ICP、短信、SSL、托管等产品页，以及 8+ 行业解决方案、新闻公告、文档中心、合作伙伴与营销活动。
+- **可插拔扩展**：内置域名插件、AI 知识库插件占位；通过 `addons_js` 和后端配置即可按需启用。
+- **多端适配**：默认宽度 1400px，提供缩放逻辑应对 1000–1440px 视口；图片资源集中在 `assets/` 便于统一管理。
+
+### 1.2 页面覆盖
+
+| 模块 | 入口文件 | 功能概要 |
+| --- | --- | --- |
+| 首页与品牌 | `index.html`、`about.html` | 首页 banner、产品入口、荣誉/合作伙伴展示、新闻公告、AI 插件；关于页提供里程碑、核心指标、价值观等板块。 |
+| 产品与服务 | `cloud.html`、`dedicated.html`、`rent.html`、`trusteeship.html`、`sms.html`、`ssl.html`、`trademark.html`、`icp.html`、`domain*.html` | 横幅、配置卡片、套餐列表、优势场景、CTA 按钮；域名模块支持插件与静态模式。 |
+| 行业解决方案 | `solution.html`、`solution/*.html` | 展示多行业痛点、解决方案、推荐产品、应用场景与价值收益。 |
+| 资讯公告 | `news.html`、`news-classify.html`、`news-details.html`、`announce.html`、`announce-details.html` | 新闻/公告分类、分页、详情页及推荐阅读。 |
+| 文档中心 | `document.html`、`document-result.html`、`document-view.html`、`document-details.html` | 支持搜索、分类展示、树形导航示例与详情模板。 |
+| 合作伙伴与推广 | `partner/agent.html`、`partner/cps.html`、`partner-agent.html`、`partner-reward.html` | 代理合作、CPS 推广新版/旧版页面，含流程、权益与 FAQ。 |
+| 客户支持 | `contact.html`、`feedback.html`、`service-guarantee.html`、`recruit.html` | 联系我们、意见反馈、服务保障、招聘等互动场景。 |
+| 营销活动 | `activities.html` | 限量秒杀、爆款特惠、优惠礼包等活动模块，含倒计时和弹窗示例。 |
+
+## 2. 技术栈与依赖
+
+- **模板引擎**：使用 `{include file=""}`、`{if}`、`{foreach}` 等语法，建议在 ThinkPHP、Smarty 或任意支持同类语法的模板引擎下使用。
+- **JavaScript 生态**  
+  - 核心库：`vender/jQuery/jquery-3.5.1.min.js`、`vender/bootstrap/`、`vender/swiper/`、`js/viewer.min.js`。  
+  - 插件：`jquery.SuperSlide2.1.2.js`（里程碑滑块）、`swiper.animate.min.js`（动画）、`viewer.min.js`（荣誉图片预览）。
+- **样式资源**  
+  - `common/reset.css`、`common/style.css`、`common/theme.css`、`common/common.css` 负责全局重置、布局和导航等模块。  
+  - `css/*.less` 与 `css/*.css` 成对出现，可根据 `.less` 二次编译自定义色彩和字体。  
+  - `assets/font/` 存放 IconFont，`assets/img/` 按模块拆分背景与插画。
+- **运行要求**：静态文件即可运行；若需远程数据，需提供 `/console/v1/*` REST 接口并开通跨域或反向代理。
+
+## 3. 目录结构
+
+```text
+BlackFruit-UI/
+├─ index.html / about.html / cloud.html / ...   # 各业务页面（共 40+）
+├─ header.html & footer.html                    # 顶部/底部模板入口
+├─ public/                                      # header、footer 片段与悬浮工具条
+├─ common/
+│  ├─ reset.css / style.css / theme.css         # 全局样式
+│  ├─ common.css                                # header、footer、浮窗等通用块
+│  └─ common.js                                 # 登录态、导航、表单、全局配置
+├─ css/                                         # 页面级样式与 less 源文件
+├─ js/                                          # 页面级脚本、数据交互与插件初始化
+├─ assets/
+│  ├─ font/                                     # iconfont.ttf/.woff/.css
+│  └─ img/                                      # 图片资源（index/cloud/solution/...）
+├─ vender/                                      # 第三方库（Bootstrap/jQuery/Swiper/animate）
+├─ solution/                                    # 行业解决方案详情页
+├─ partner/                                     # 新版代理与 CPS 页面
+└─ theme.jpg / favicon.ico                      # 预览封面、站点图标
+```
+
+## 4. 核心页面与脚本职责
+
+| JS / 模块 | 关联页面 | 主要职责 | 相关接口 |
+| --- | --- | --- | --- |
+| `common/common.js` | 全站 | 登录态渲染、顶部/底部数据填充、消息弹窗、导航 hover、招聘 Tab/FAQ 切换、窗口缩放适配、公共按钮跳转。 | `GET /console/v1/account`、`GET /console/v1/certification/info`、`GET /console/v1/common` |
+| `js/index.js` | `index.html` | 读取站点荣誉/案例、初始化 Swiper、使用 Viewer 弹窗预览、请求公告/新闻列表并跳转到详情。 | `GET /console/v1/common`、`GET /console/v1/announcement`、`GET /console/v1/news` |
+| `js/about.js` | `about.html` | 展示荣誉、合作伙伴、发展历程、SuperSlide 横向滑动。 | `GET /console/v1/common` |
+| `js/activities.js` | `activities.html` | 活动倒计时、弹窗开关与 CTA 按钮占位。 | 静态/业务自定义 |
+| `js/product.js` | 产品页（云服务器/物理机等） | 切换地域/配置 Tab、高亮已选套餐、滚动动画。 | 静态/可接入业务 API |
+| `js/domain.js` & `js/buy_domain.js` | `domain.html`、`domain_buy.html` | 读取 `addons_js` 判定是否启用域名插件，加载后缀与跳转链接，提供弹窗示例。 | `GET /console/v1/idcsmart_domain/config`、`GET /console/v1/idcsmart_domain/domain_suffix` |
+| `js/document_index.js` / `js/document_result.js` / `js/document.js` | 文档中心 | 分类列表、搜索结果聚合、树形导航展开/收起、空状态提示。 | `GET /console/v1/help` |
+| `js/news.js` / `js/news-classify.js` / `js/news-details.js` | 新闻中心 | 分类 Tab、分页、详情页上一条/下一条推荐、相关资讯列表。 | `GET /console/v1/news/type`、`GET /console/v1/news`、`GET /console/v1/news/{id}` |
+| `js/announce.js` / `js/announce-details.js` | 公告中心 | 分类过滤、分页器、详情页跳转。 | `GET /console/v1/announcement/type`、`GET /console/v1/announcement`、`GET /console/v1/announcement/{id}` |
+| `js/consult.js` | `contact.html` | 联系我们表单校验与提交、自定义 Toast、售前售后入口跳转。 | `POST /console/v1/consult` |
+| `js/feedback.js` | `feedback.html` | 动态渲染反馈类型、表单验证、提交后清空表单。 | `GET /console/v1/common`、`POST /console/v1/feedback` |
+| `js/ai.js` | 所有页面（按需） | 解析 `<html id="addons_js" addons_js='[]'>`，若包含 `AiKnowledge` 则加载 `/plugins/addon/ai_knowledge/template/clientarea/ai-dialog.js` 并初始化浮窗。 | 插件脚本（同域） |
+
+> 其余脚本（如 `js/tools.js`、`js/extend.js` 等）为 Swiper/动画辅助工具，可根据实际页面引用。
+
+## 5. 公共模板与数据注入机制
+
+- **头部结构**：`header.html` 引入 meta、CSS、JS；`public/header.html` 定义导航结构。若后端传入 `$data.header_nav`，即可覆盖默认导航、二级菜单、图标与跳转方式。无配置时展示静态备选项。
+- **底部结构**：`public/footer.html` 通过 `$data.config`、`$data.friendly_link` 渲染承诺、导航分组、企业信息、友情链接与备案。`common/common.js` 会读取 `/console/v1/common` 的数据替换 logo、电话、二维码等占位。
+- **登录态展示**：当 `localStorage.jwt` 存在时，全局脚本会以 `Authorization: Bearer <jwt>` 请求 `GET /console/v1/account` 和 `GET /console/v1/certification/info`，展示用户名、首字母头像、实名认证标识以及“账户信息/未付款订单/我的工单/退出”菜单。
+- **Session 缓存**：接口结果会被写入 `sessionStorage.commentData`、`sessionStorage.accountInfo`、`sessionStorage.is_certification`，避免重复请求。开发调试若需刷新数据，请手动清除浏览器缓存或在控制台执行 `sessionStorage.clear()`。
+- **浏览器跳转**：`common/common.js` 统一绑定了登录/注册/控制台/购物车/文档等按钮的跳转逻辑，可根据业务修改路径。
+- **插件注入**：在 `<html>` 标签上添加 `id="addons_js"` 并设置 `addons_js='[{"name":"AiKnowledge"}]'` 即可启用 AI 知识库弹窗；其他插件可以扩展 `js/ai.js` 做懒加载。
+
+## 6. 接口与数据契约
+
+所有接口默认以 `JSON` 格式返回 `{ status: 200, data: { ... } }`，`Authorization` 头部采用 `Bearer <jwt>`。常用接口如下（可根据后端实现调整路径/字段）：
+
+- **账号与认证**
+  - `GET /console/v1/account`：返回 `account.username/avatar/...`；用于顶部登录态。
+  - `GET /console/v1/certification/info`：返回 `is_certification` 布尔值。
+- **站点公共配置**
+  - `GET /console/v1/common`：企业名称、电话、邮箱、二维码、logo、备案、友情链接、荣誉 `honor`、合作伙伴 `partner`、反馈类型 `feedback_type`、产品跳转链接等。
+  - 响应示例：
+
+```json
+{
+  "status": 200,
+  "data": {
+    "enterprise_name": "主题云",
+    "enterprise_telephone": "400-000-0000",
+    "enterprise_mailbox": "support@example.com",
+    "enterprise_qrcode": "/upload/qrcode.png",
+    "official_website_logo": "/upload/logo.png",
+    "friendly_link": [
+      { "name": "合作伙伴A", "url": "https://example.com" }
+    ],
+    "honor": [{ "name": "高新技术企业", "img": "/upload/honor.png" }],
+    "partner": [{ "name": "案例客户", "img": "/upload/case.png", "description": "典型案例" }],
+    "feedback_type": [{ "id": 1, "name": "产品建议" }],
+    "cloud_product_link": "/cart/goods.htm?id=1",
+    "dcim_product_link": "/cart/goods.htm?id=2",
+    "terms_service_url": "/agreement/service.html",
+    "terms_privacy_url": "/agreement/privacy.html",
+    "icp_info": "京ICP备XXXX号",
+    "icp_info_link": "https://beian.miit.gov.cn/#/Integrated/index"
+  }
+}
+```
+
+- **公告/新闻**
+  - `GET /console/v1/announcement/type`、`GET /console/v1/announcement`、`GET /console/v1/announcement/{id}`。
+  - `GET /console/v1/news/type`、`GET /console/v1/news`、`GET /console/v1/news/{id}`。
+  - 列表接口默认接受 `page`、`limit` 参数；详情页根据 URL 参数 `id` 调用。
+- **文档中心**
+  - `GET /console/v1/help`（支持 `keywords` 查询）返回 `category_list` 与 `article_list`。跳转链接可指向 `/plugin/26/helpTotal.htm?id=` 等后端页面。
+- **域名插件**
+  - `GET /console/v1/idcsmart_domain/config`：返回默认后缀、跳转地址。
+  - `GET /console/v1/idcsmart_domain/domain_suffix`：返回后缀数组并指明价格/语言等信息。
+  - 没有插件时会 fallback 到静态 `.com/.cn` 后缀并弹出“功能暂未开放”提示。
+- **互动表单**
+  - `POST /console/v1/consult`：`contact.html` 提交公司/联系人/手机/邮箱/问题描述，成功后通过 `showMessage("success", "提交成功", 3000)` 提示。
+  - `POST /console/v1/feedback`：`feedback.html` 提交类型、标题、内容、邮箱/电话，字段由 `feedback.js` 校验。
+
+> 建议后端统一返回 `status`、`msg`、`data` 三段式结构，并在需要登录的接口开启 JWT 校验。
+
+## 7. 本地预览、联调与部署
+
+### 7.1 本地预览
+1. 克隆或下载项目后进入目录：`cd BlackFruit-UI`。
+2. 使用任意静态服务器（示例）：
+   ```bash
+   # Python3
+   python -m http.server 8080
+   # or Node
+   npx http-server -p 8080
+   ```
+3. 浏览器访问 `http://localhost:8080` 预览。注意：若直接使用 `file://` 打开 HTML，`$.ajax` 请求会因同源策略失败。
+
+### 7.2 接口联调
+- 将 `/console/v1/*` 代理至后端（Nginx `proxy_pass` 或本地 mock 服务）。
+- 确保接口支持跨域、携带 `Authorization` header，并返回上文约定的字段。
+- 调试登录态时在控制台执行 `localStorage.jwt = "<测试 token>"` 以模拟已登录状态。
+
+### 7.3 部署建议
+- 将整个目录同步到 Web Server（Nginx `root`, Apache `DocumentRoot`, CDN/OSS 等），保持相对路径不变。
+- 为 `assets/`、`css/`、`js/`、`vender/` 设置长期缓存，HTML 设置较短缓存或协商缓存，方便热更新。
+- 若需 HTTPS，保证接口与静态资源均在同一协议下，避免混合内容警告。
+- 可按需要在 Nginx 中配置 `try_files $uri /index.html;` 以支持根路径访问首页。
+
+## 8. 自定义与二次开发指引
+
+- **导航与页脚**：后台传入 `$data.header_nav`、`$data.config`、`$data.friendly_link` 即可动态渲染导航结构、二级菜单图标、友情链接与备案信息。若要新增菜单，可在 `public/header.html` 中复制现有 `nav-item`/`nav-cont-menu` 结构。
+- **产品与解决方案扩展**：
+  1. 复制现有页面（如 `cloud.html`）并更名；
+  2. 引入对应 CSS（`css/product.css` 或 `css/solution.css`）和 JS（`js/product.js`）；
+  3. 替换图文内容或通过后端模板传入动态数据；
+  4. 保持 CTA 链接指向 `/cart/goods.htm?id=` 或自定义购买页。
+- **域名与插件**：通过 `<html id="addons_js" addons_js='[{"name":"IdcsmartDomain"}]'>` 让 `js/domain.js` 触发 API 模式；若缺省则自动进入静态说明模式。
+- **AI 知识库**：在 `addons_js` 中添加 `{"name": "AiKnowledge"}` 即可加载 `/plugins/addon/ai_knowledge/template/clientarea/ai-dialog.js`。如需新增插件，可在 `js/ai.js` 中扩展判断逻辑。
+- **交互表单**：`common/common.js` 已提供 `showMessage`、表单校验示例；如需新增表单，建议复用该组件及 `btn btn-normal` 样式，保持一致的体验。
+- **样式主题**：优先修改 `common/theme.css` 或对应 `.less` 文件，然后重新编译为 `.css`（可使用 `lessc css/product.less css/product.css` 等命令）。
+- **资源替换**：所有图片集中在 `assets/img/{module}`，替换时保持文件名或同步更新 HTML 引用；IconFont 可在 `assets/font/iconfont.css` 中更新 `@font-face`。
+
+## 9. 常见问题与调试建议
+
+- **接口请求 404/跨域**：检查预览方式是否为 `file://` 或接口域名不一致；推荐通过本地静态服务器 + 反向代理保证同域。
+- **导航或页脚未渲染**：确认 `common/common.js` 已加载且 `/console/v1/common` 请求成功；可在控制台查看 `sessionStorage.commentData`。
+- **登录信息不显示**：需要在浏览器注入有效的 `localStorage.jwt`，并确保接口返回 `status: 200`；否则会回退到“登录/立即注册”按钮。
+- **域名插件按钮点击无反应**：检查 `<html>` 上的 `addons_js` 是否包含 `IdcsmartDomain`；没有插件时页面会提示“功能暂未开放”。
+- **AI 对话框未加载**：确认插件脚本 URL 可访问，并且 `addons_js` 中包含 `AiKnowledge`。此外需确保 `AIDialog` 构造函数在加载脚本后可用。
+- **Viewer 预览空白**：`js/index.js` 会将 `#viewer` 图片地址替换为所点图片，若 `assets/img` 路径调整，请同步更新图片引用。
+
+## 10. 维护清单
+
+- **静态资源版本化**：当更新 CSS/JS 时建议在 `header.html` 中追加查询参数（如 `?v=202404`）以便缓存刷新。
+- **第三方依赖更新**：`vender/` 中的库仍是 3.x 版本，请在升级 jQuery/Bootstrap/Swiper 时同步验证与 `common/common.js` 的兼容性。
+- **LESS/CSS 同步**：若修改 `.less`，请记得重新编译生成 `.css`，避免线上引用旧样式。
+- **可访问性与 SEO**：合理设置 `<title>`、`<meta name="keywords/description">` 以及图片 `alt` 属性，保证页面友好度。
+- **多语言/多站点**：如需多语言版本，可复制整个目录并调整文案，或在模板层根据语言变量输出不同片段。
+- **版本控制**：建议将本项目作为子模块或模板仓库，二次开发时维护 Changelog，便于同步官方更新。