better-staridc-MNBT

better-staridc-MNBT/ docs/development/theme/tdesign.md 18.5 KB · 369 行原始文件
Z zfhsh first commit 2 天前
1---
2title: TDesign 三端主题
3description: tdesign 主题说明:特性、目录结构、编译、启用、设计规范、开发约定、已知限制与版本
4---
5
6# TDesign 三端主题(tdesign)v0.3.0
7
8现代化 **三端** 主题:基于 TDesign 品牌蓝,覆盖**用户端 + 管理端 + 主页售卖**全部页面。卡片化布局、侧栏 + 顶栏、echarts 数据可视化、左侧背景图登录页、独立主页售卖前端。
9
10技术栈:**Vue 3 + Vue Router (Hash) + TDesign Vue Next + Vite + ECharts**。
11
12> 历史文档:双端改造计划见 [tdesign 双端改造计划](../plan/tdesign-user-scope.md);与 PHP 的对接细节见 [与 PHP 的对接](./tdesign-php.md)。
13
14---
15
16## 特性
17
18### 用户端(user scope)
19
20| 模块 | 说明 |
21|------|------|
22| 登录页 | 左侧背景图 + 右侧登录区,验证码支持,登录态自动跳转 |
23| 控制台壳 | 侧栏 + 顶栏,折叠/移动端抽屉,退出登录确认 |
24| 首页仪表盘 | 资源使用 echarts gauge 仪表盘 / 月度流量趋势柱状图+折线图 / 快捷操作平铺按钮 / 4 张站点信息卡片 |
25| 站点设置 | PHP 版本 / 密码访问 / 默认文档 / 运行目录 / 伪静态 / SSL / 防盗链 / Gzip / 缓存 / 修改密码 / SQL 权限 |
26| 文件管理 | iframe 嵌入默认主题 ftp.php(复用成熟的文件管理 UI) |
27| SQL 备份 | 备份列表 / 立即备份 / 下载 / 恢复 / 删除 |
28| 监控任务 | 任务列表 / 新增 / 编辑 / 删除 / 监控日志 |
29| 站点统计 | 概览卡片 + 访问路径 / IP 排行 / 错误日志分类标签页 |
30| 一键部署 | 部署程序列表 |
31| 插件页面 | 通过 SPA 路由 + iframe 在 layout 内加载,不再新窗口打开 |
32| 公告弹窗 | NoticeDialog 组件,sessionStorage 记忆已读 |
33| 邮箱绑定 | MailBindDialog 组件,未绑定时强制弹出 |
34
35### 管理端(admin scope)
36
37| 模块 | 说明 |
38|------|------|
39| 登录页 | 左侧背景图 + 右侧登录区,验证码支持,登录态自动跳转 |
40| 控制台壳 | 深色侧栏 + 顶栏,折叠/移动端抽屉,退出登录确认 |
41| 仪表盘 | 公告 / 系统信息 / 检查更新(`sy.php` 注入 `$sy`) |
42| 系统管理 | 网站设置 / 管理设置 / API / 邮箱 / 控制面板 / 监控 / 系统更新 / 操作日志 |
43| 主机管理 | 主机列表(服务端分页) / 添加主机 / 批量删除 |
44| 节点与宝塔 | 宝塔列表(通信检测 / PHP 版本管理) / 添加宝塔 / 节点列表 / 违禁词扫描 |
45| 一键部署 | 订单列表 / 程序列表 / 添加程序 / 导入程序 |
46| 支付设置 | 动态渲染支付插件及子付款方式,启用/显示名/图标/排序 |
47| 插件管理 | 安装 / 启用 / 卸载,设置入口跳转 |
48| 前端模板 | 用户端 / 管理端主题切换 |
49| 教程 / 修复 / 更新 | 教程与监控、系统修复、系统更新 |
50| 插件页面 | 通过 SPA 路由 + iframe 在 layout 内加载 |
51| 路由 | Hash 模式,不改 PHP 控制器 URL |
52
53### 主页(home scope)
54
55完整售卖系统前端,通过**插件 API 路由**(`index.php?_r=/xxx/api/xxx`)驱动,不依赖 iframe。依赖 `user_info`(认证)、`balance`(余额)、`hosting_shop`(商店)插件;`official_site`(官网内容)插件可选,启用后展示官网页面。
56
57| 模块 | 说明 |
58|------|------|
59| 落地页 | Hero + 公告 + 套餐卡 + 特性区块(数据来自 `mnbt_home_data()` 注入的 `$plans` / `$blocks`) + 轮播 hero + 新闻预览 + 客户评价(绿色风格) |
60| 账户 | 登录 / 注册 / 个人信息 / 修改密码(`user_info` 插件 `GET /account/api/*`) |
61| 商店 | 套餐列表 / 下单(选周期 + 支付方式,支付 HTML 用 `document.write` 跳转) / 我的主机 / 我的订单(`hosting_shop` 插件 `GET /shop/api/*`) |
62| 余额 | 余额卡 + 流水表格 / 充值(`balance` 插件 `GET /balance/api/*`) |
63| 官网内容 | 关于我们 / 产品中心(列表+详情) / 新闻资讯(列表+详情) / 联系我们(留言表单)(`official_site` 插件 `GET /site/api/*`、`POST /site/api/contact`,`meta.cap: 'site'` 能力守卫) |
64| 登录态 | `auth.js` store 启动时探测 `/account/api/me`,路由守卫统一拦截,未登录访问受保护页自动跳登录 |
65
66---
67
68## 目录结构
69
70```
71templates/tdesign/
72├── theme.json                 # 主题元信息(scope: ["user", "admin", "home"])
73├── theme.php                  # 注册双端菜单渲染器(插件菜单 → 侧栏 HTML)
74├── README.md                  # 本说明(已迁移至 docs/development/theme/tdesign.md)
75├── PLAN_USER_SCOPE.md         # 双端改造计划文档(已迁移至 ../plan/tdesign-user-scope.md)
76│
77├── admin/                     # 管理端 PHP 主题入口
78│   ├── _spa_boot.php          # 注入 window.__TD_BOOT__ + 加载 dist
79│   ├── login.php              # 登录页入口
80│   ├── index.php / sy.php     # 仪表盘入口(sy.php 注入 $sy)
81│   ├── set.php                # 设置类页面(set.php?gn=xxx → SPA 路由)
82│   ├── list.php               # 列表类页面(list.php?gn=xxx → SPA 路由)
83│   ├── add.php                # 添加类页面(add.php?gn=xxx → SPA 路由)
84│   ├── node.php               # 节点入口(node.php?tab=scan → 违禁词)
85│   ├── plugin_manage.php      # 插件管理
86│   ├── pay_settings.php       # 支付设置
87│   ├── tutorial.php           # 教程与监控
88│   ├── update.php             # 系统更新
89│   └── dist/                  # ★ Vite 构建产物(需提交,勿 gitignore)
90│       ├── admin.html
91│       └── assets/
92│           ├── index.js
93│           ├── index.css
94│           └── login-bg.webp
95│
96├── user/                      # 用户端 PHP 主题入口
97│   ├── _spa_boot.php          # 注入 window.__TD_BOOT__ + 加载 dist + 插件菜单渲染
98│   ├── login.php              # 登录页入口
99│   ├── index.php / sy.php     # 首页入口
100│   ├── set.php                # 设置类页面(set.php?gn=xxx → SPA 路由)
101│   ├── site_stats.php         # 站点统计
102│   ├── sqlgl.php              # SQL 备份
103│   ├── monitor.php            # 监控任务
104│   ├── monitor_log.php        # 监控日志
105│   ├── notice.php             # 公告
106│   ├── webgl.php              # 一键部署
107│   └── dist/                  # ★ Vite 构建产物(需提交,勿 gitignore)
108│       ├── user.html
109│       └── assets/
110│           ├── index.js
111│           ├── index.css
112│           └── login-bg.webp
113│
114├── home/                      # 主页 PHP 主题入口(home scope)
115│   ├── index.php              # 落地页入口,注入 __TD_BOOT__ + 加载 dist(未构建时给出提示)
116│   └── dist/                  # ★ Vite 构建产物(需提交,勿 gitignore)
117│       ├── home.html
118│       └── assets/
119│           ├── index.js
120│           └── index.css
121│
122└── spa/                       # SPA 源码(开发用,按端分层)
123    ├── package.json           # 构建脚本(build:admin / build:user / build:docker / build:home)
124    ├── vite.admin.config.js   # 管理端 Vite 配置
125    ├── vite.user.config.js    # 用户端 Vite 配置
126    ├── vite.docker.config.js  # Docker 控制台 Vite 配置
127    ├── vite.home.config.js    # 主页 Vite 配置
128    ├── admin.html             # 管理端 HTML 模板
129    ├── user.html              # 用户端 HTML 模板
130    ├── docker.html            # Docker 控制台 HTML 模板
131    ├── home.html              # 主页 HTML 模板
132    ├── public/                # 静态资源(验证码图等,构建时复制进 dist)
133    ├── .gitignore             # 仅忽略 node_modules 等,不忽略 dist
134    └── src/
135        ├── App-admin.vue      # 管理端根组件
136        ├── App-user.vue       # 用户端根组件
137        ├── App-docker.vue     # Docker 控制台根组件
138        ├── App-home.vue       # 主页根组件
139        ├── main-admin.js      # 管理端入口
140        ├── main-user.js       # 用户端入口
141        ├── main-docker.js     # Docker 控制台入口
142        ├── main-home.js       # 主页入口
143        │
144        ├── admin/             # 管理端代码(全部集中于此)
145        │   ├── api/           # 13 个 API 文件(auth/baota/dashboard/host/...)
146        │   ├── layouts/AdminLayout.vue
147        │   ├── router/index.js
148        │   └── views/         # 按业务模块分目录
149        │       ├── baota/     # 宝塔(List/Add)
150        │       ├── docker/    # Docker(节点/套餐/用户)
151        │       ├── host/      # 主机(List/Add)
152        │       ├── node/      # 节点(List/Scan)
153        │       ├── program/   # 程序(List/Add/Import)
154        │       ├── order/     # 订单
155        │       ├── log/       # 日志
156        │       ├── plugin/    # 插件
157        │       ├── pay/       # 支付
158        │       ├── settings/  # 设置(Website/Admin/Api/Mail/Panel/Monitor/Theme)
159        │       └── *.vue      # 顶层散落 view(Dashboard/Login/PluginPage/Repair/Tutorial/Update)
160        │
161        ├── user/              # 用户端代码(全部集中于此)
162        │   ├── api/           # 7 个 API 文件(auth/common/database/deploy/monitor/site/stats)
163        │   ├── components/    # MailBindDialog / NoticeDialog
164        │   ├── layouts/UserLayout.vue
165        │   ├── router/index.js
166        │   └── views/         # 按业务模块分目录
167        │       ├── dashboard/ # 首页仪表盘(gauge + 流量趋势 + 快捷操作 + 站点信息)
168        │       ├── settings/  # 站点设置
169        │       ├── ftp/       # 文件管理
170        │       ├── database/  # SQL 备份
171        │       ├── monitor/   # 监控任务 + 监控日志
172        │       ├── stats/     # 站点统计
173        │       ├── deploy/    # 一键部署
174        │       └── *.vue      # 顶层 view(Login/Notice/Plugin)
175        │
176        ├── docker/            # Docker 控制台代码
177        │   ├── api/docker.js  # Docker API 封装(CSRF + 登录态自动跳转)
178        │   ├── components/    # SliderCaptcha 滑块验证码
179        │   ├── layouts/DockerLayout.vue
180        │   ├── router/index.js
181        │   └── views/         # Console/Login/AppStore/Image/Volume/Compose/Proxy
182        │
183        ├── home/              # 主页售卖端代码(home scope)
184        │   ├── api/           # http.js(routeRequest+CSRF) / account / balance / shop
185        │   ├── layouts/HomeLayout.vue
186        │   ├── router/index.js # 路由 + 登录态守卫(initAuth 探测 /account/api/me)
187        │   ├── store/auth.js   # 响应式登录态 store
188        │   ├── styles/home.scss
189        │   ├── utils/format.js # periodLabels/centsToYuan/orderStatusMap/...
190        │   └── views/         # 按业务模块分目录
191        │       ├── auth/      # 登录/注册/个人信息/修改密码
192        │       ├── shop/      # 套餐列表/下单/我的主机/我的订单
193        │       ├── balance/   # 余额/充值
194        │       └── LandingView.vue # 落地页
195        │
196        └── shared/            # 各端共用代码
197            ├── api/http.js    # apiGn/postGn/parseResult 统一请求封装
198            ├── utils/echarts.js # echarts 按需引入(Gauge/Bar/Line + 组件)
199            ├── assets/login-bg.webp  # 登录页背景图
200            └── styles/theme.scss     # 全局样式 + CSS 变量
201```
202
203---
204
205## 编译说明
206
207### 环境
208
209- Node.js **18+**(推荐 20 LTS)
210- npm 9+ 或 pnpm / yarn
211
212### 安装依赖
213
214```bash
215cd templates/tdesign/spa
216npm install
217```
218
219### 开发(可选)
220
221```bash
222# 管理端开发服务器
223npm run dev:admin
224
225# 用户端开发服务器
226npm run dev:user
227
228# Docker 控制台开发服务器
229npm run dev:docker
230
231# 主页开发服务器(端口 5177)
232npm run dev:home
233```
234
235开发配置见各 `vite.*.config.js` 的 `server.proxy`。  
236开发模式 HTML 内置最小 `window.__TD_BOOT__`,可在无 PHP 环境下预览 UI。
237
238### 生产构建
239
240```bash
241cd templates/tdesign/spa
242
243# 单独构建
244npm run build:admin    # 输出到 ../admin/dist/
245npm run build:user     # 输出到 ../user/dist/
246npm run build:docker   # 输出到 ../docker/dist/
247npm run build:home     # 输出到 ../home/dist/
248
249# 四端一起构建
250npm run build
251```
252
253产物输出:
254
255| 端 | 输出目录 | HTML | 入口 JS |
256|----|----------|------|---------|
257| 管理端 | `templates/tdesign/admin/dist/` | `admin.html` | `assets/index.js` |
258| 用户端 | `templates/tdesign/user/dist/` | `user.html` | `assets/index.js` |
259| Docker 控制台 | `templates/tdesign/docker/dist/` | `docker.html` | `assets/index.js` |
260| 主页 | `templates/tdesign/home/dist/` | `home.html` | `assets/index.js` |
261
262PHP 入口通过 `mnbt_theme_url('dist/assets/index.js')` 加载。  
263**请将各端 `dist` 一并提交/部署**,服务器无需安装 Node 即可运行主题。
264
265构建配置要点(各端一致):
266
267- `base: './'` —— 相对路径,适配 PHP 子目录部署
268- `inlineDynamicImports: true` —— 打成单 JS 包,避免动态 chunk 相对路径错位
269- `cssCodeSplit: false` —— 单 CSS 文件
270- `assetsDir: 'assets'`,固定输出 `assets/index.js` 与 `assets/index.css`
271- `@` alias 指向 `src`,import 路径形如 `@/admin/api/xxx`、`@/user/views/xxx`、`@/shared/utils/echarts`
272
273### 未构建时
274
275打开管理后台/用户端/主页会显示「TDesign 主题尚未构建」提示与编译命令。
276
277---
278
279## 启用主题
280
2811. 确保已 `npm run build` 且存在各端 `dist/assets/index.js`(`admin` / `user` / `home`)
2822. 管理后台 → **系统管理** → **前端模板**
2833. **管理端主题** 选择 **TDesign 三端主题** → 保存
2844. **用户端主题** 选择 **TDesign 三端主题** → 保存
2855. **主页主题** 选择 **TDesign 三端主题** → 保存  
286   或写入文件:`templates/active_admin_theme` / `templates/active_user_theme` / `templates/active_home_theme` 内容均为 `tdesign`
287
288---
289
290## 与 PHP 的对接
291
292管理端 / 用户端入口映射、`__TD_BOOT__` 启动数据、AJAX gn 列表、插件菜单对接、主页 API 路由等,见 [与 PHP 的对接(tdesign-php.md)](./tdesign-php.md)。
293
294---
295
296## 设计规范
297
298| 项 | 值 |
299|----|----|
300| 主色 | `#0052D9`(TDesign 品牌蓝) |
301| 主色浅底 | `#E8F3FF` |
302| 成功 / 警告 / 危险 | `#2BA471` / `#E37318` / `#D54941` |
303| 正文 / 次要 / 占位 | `#181818` / `#595959` / `#8C8C8C` |
304| 边框 / 背景 / 表面 | `#E7E7E7` / `#F2F3F5` / `#FFFFFF` |
305| 侧栏深色 | 背景 `#1F2B3A`,文字 `#C5CDD6` |
306| 侧栏宽度 | `220px`(折叠 `64px`) |
307| 顶栏高度 | `56px` |
308| 圆角 | `6px` / 大圆角 `10px` |
309| 字体 | 系统 UI / 苹方 / 微软雅黑 |
310| 阴影 | `0 1px 2px rgba(0,0,0,.04), 0 4px 12px rgba(0,0,0,.04)` |
311
312CSS 变量定义在 `spa/src/shared/styles/theme.scss` 顶部 `:root`,修改后重新 `npm run build`。
313
314### 通用样式类
315
316| 类 | 用途 |
317|----|------|
318| `.td-page` / `.td-page-head` / `.td-page-title` / `.td-page-subtitle` | 页面容器与标题 |
319| `.td-card` / `.td-card-head` / `.td-card-bd` | 卡片 |
320| `.td-form` / `.td-form-row` / `.td-form-actions` / `.td-form-switch` | 表单页 |
321| `.td-toolbar` / `.td-toolbar-spacer` | 表格工具条 |
322| `.td-table-wrap` | 表格容器(自带白底/边框/圆角/阴影) |
323| `.td-set-card` / `.td-set-card-hd` / `.td-set-card-bd` | 设置卡片 |
324| `.td-chip` / `.td-chip-success` / `.td-chip-danger` | 状态徽标 |
325| `.td-empty` / `.td-code` / `.td-mono` / `.td-flex-center` / `.td-gap-8` / `.td-row-actions` | 通用工具 |
326
327### 长表单滚动
328
329`t-dialog` 弹窗内长表单通过 `.t-dialog__body .td-form` 自动启用垂直滚动:  
330`max-height: calc(100vh - 220px)` + `overflow-y: auto` + `padding-right: 6px`。
331
332---
333
334## 开发约定
335
3361. **不要改** `admin/*.php` / `user/*.php` / `home/*.php` 控制器与 `ajax.php` 接口路径
3372. 新增纯前端页面:
338   - 管理端:`src/admin/views/` 添加 `.vue` + `src/admin/router/index.js` 注册路由
339   - 用户端:`src/user/views/` 添加 `.vue` + `src/user/router/index.js` 注册路由
340   - 主页:`src/home/views/` 添加 `.vue` + `src/home/router/index.js` 注册路由(需登录页加 `meta.auth`、访客页加 `meta.guest`)
3413. import 路径统一使用 `@` alias:
342   - 管理端:`@/admin/api/xxx`、`@/admin/views/xxx`
343   - 用户端:`@/user/api/xxx`、`@/user/views/xxx`
344   - 主页:`@/home/api/xxx`、`@/home/views/xxx`、`@/home/store/auth`
345   - 共用:`@/shared/api/http`、`@/shared/utils/echarts`、`@/shared/styles/theme.scss`
3464. 列表页统一服务端分页,前端只做查询条件与渲染
3475. 表单/表格统一使用 `.td-form` / `.td-table-wrap` / `.td-toolbar` 等通用类,避免重复样式
3486. 表格工具条 `.td-toolbar` 使用 `padding: 12px 16px` 确保与边框间距
3497. `t-dialog` 组件必须使用 `v-model:visible` 而非 `v-model`(避免 Vue modelValue 错误)
3508. `spa/.gitignore` 忽略 `node_modules`,**不忽略** 各端 `dist`
3519. 版本号同步:`theme.json` 与 `spa/package.json`
35210. 修改源码后必须重新构建对应端(`npm run build:admin` / `build:user` / `build:docker` / `build:home`),否则线上不会生效
353
354---
355
356## 已知限制
357
358- 文件管理页面(ftp)采用 iframe 嵌入默认主题 ftp.php(复用成熟的文件管理 UI,避免重写复杂组件)
359- 插件自带页面仍由插件自行渲染,主题仅提供菜单入口与 iframe 容器
360- 主页售卖端依赖 `user_info` / `balance` / `hosting_shop` 三个插件;官网页面依赖 `official_site` 插件(`boot.hasSite` 为 false 时导航与页面自动隐藏)
361- 部分旧接口字段因版本差异可能需在 `parseResult` 或视图层做兼容调整
362
363---
364
365## 版本
366
367- **0.3.0** 主页售卖端:新增 home scope(落地页/登录注册/个人信息/商店/下单/我的主机/订单/余额/充值),插件 API 路由(`index.php?_r=`)驱动 + 独立 Vite 入口(`build:home`),登录态由 `auth.js` store 统一探测
368- **0.2.0** 双端主题:用户端全部页面原生化(仪表盘/设置/文件管理/SQL备份/监控/统计/部署/插件) + 按端分层目录重构(admin/user/shared) + 左侧背景图登录页 + echarts gauge 仪表盘 + 快捷操作平铺按钮 + 插件页面 iframe 内嵌
369- **0.1.0** 首版:SPA 壳 + 登录 + 全部后台页面原生化(仪表盘 / 设置 / 主机 / 宝塔 / 节点 / 程序 / 订单 / 日志 / 插件 / 支付 / 主题切换 / 教程 / 更新 / 修复)