BlackFruit-UI

BlackFruit-UI（品牌名称“主题云”）是一套面向云服务商官网场景的静态前端模板。项目围绕“首页 + 产品 + 解决方案 + 文档 + 资讯 + 合作伙伴 + 客户支持”全链路体验打造，所有页面可直接由任意 Web Server 托管，同时又兼容服务端模板引擎（Smarty/ThinkPHP 风格）以便与现有业务系统整合。

目录

1. 项目概述
2. 技术栈与依赖
3. 目录结构
4. 核心页面与脚本职责
5. 公共模板与数据注入机制
6. 接口与数据契约
7. 本地预览、联调与部署
8. 自定义与二次开发指引
9. 常见问题与调试建议
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. 目录结构

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、产品跳转链接等。
  • 响应示例：

{
  "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. 使用任意静态服务器（示例）：

   # 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，便于同步官方更新。