better-staridc-MNBT
1# PRD — WordPress 虚拟主机销售插件（wp_seller_plugin）
2
3> 产品版本：v1.0
4> 文档状态：草案
5> 关联系统：MNBT（梦奈宝塔主机管理系统）
6
7---
8
9## 1. 产品概述
10
11### 1.1 背景
12
13MNBT 是一套基于宝塔面板的虚拟主机管理系统，已具备完整的**主机生命周期管理 API** 与 **cPanel 式的用户自助控制台**（文件管理、数据库、FTP、域名、SSL、日志等）。但 MNBT 本身不承载「对外销售」环节（商品、下单、支付、账单）。
14
15魔方财务通过 `mf_modules/servers/mnbthost` 已证明第三方系统可无缝对接 MNBT API 售卖主机。本插件将把这一模式复刻到 **WordPress**，让站长在 WordPress 站点上直接售卖 MNBT 虚拟主机，体验向 cPanel 的「销售 + 自助管理」形态靠拢。
16
17### 1.2 产品定位
18
19- **销售层（WordPress）**：商品展示、购买下单、支付结算、订单管理。
20- **管理层（WordPress + MNBT）**：主机开通/暂停/恢复/删除/续费/改密/启停/升降级。
21- **自助层（MNBT 用户控制台）**：文件/数据库/域名/FTP/SSL 等深度管理，插件通过控制台入口复用，不重复开发。
22
23### 1.3 目标
24
25| 目标 | 衡量标准 |
26|------|----------|
27| 站长能用 WordPress 独立卖主机 | 从创建商品到客户自助开通全流程可跑通 |
28| 用户购买后自动开通 | 支付成功后无需人工干预，自动调用 `kt` 开通 |
29| 主机管理接近 cPanel 体验 | 前台提供状态、配额用量、启停/改密/续费；深度管理跳转 MNBT 控制台 |
30| 到期不续费自动停站 | WordPress 定时任务调用 `zt`/`jc` 实现到期控制 |
31
32### 1.4 非目标（V1 范围外）
33
34- 不重写 MNBT 控制台功能（文件/数据库/域名管理复用 MNBT）。
35- 不做多支付网关适配（V1 对接 WooCommerce 支付体系）。
36- 不做 WordPress 多站点（Multisite）专属适配（保证兼容但不做增强）。
37
38---
39
40## 2. 用户与场景
41
42### 2.1 角色
43
44| 角色 | 说明 |
45|------|------|
46| 站长（WordPress 管理员） | 配置 MNBT 连接、上架主机商品、查看订单与主机、处理退款/工单 |
47| 客户（WordPress 注册用户） | 浏览商品、购买支付、管理自己的主机 |
48
49### 2.2 核心场景
50
511. **S1 购买开通**：客户选套餐 → 下单 → 支付成功 → 插件自动在 MNBT 开通主机（建站+FTP+数据库）→ 客户在"我的主机"看到账号/密码/控制台入口。
522. **S2 自助管理**：客户查看主机状态（运行中/暂停）、空间/数据库/流量用量条、执行启停、改密、续费。
533. **S3 到期控制**：每日定时任务扫描到期主机，到期未续费自动暂停，续费后恢复。
544. **S4 管理端运维**：站长查看所有主机、手动暂停/恢复/删除、调整配额、查看 MNBT 节点状态。
55
56---
57
58## 3. 功能需求
59
60优先级：P0（V1 必须）/ P1（V1 建议）/ P2（后续迭代）。
61
62### 3.1 管理端（WordPress 后台）
63
64| 编号 | 功能 | 优先级 | 说明 |
65|------|------|--------|------|
66| A1 | MNBT 连接配置 | P0 | 节点代号(btdh)、系统 API 密钥、调用密钥、API 地址、版本号；支持多节点 |
67| A2 | 连接测试 | P0 | 调用 `cfif` 验证配置 |
68| A3 | 商品管理 | P0 | 基于 WooCommerce 产品扩展：套餐类型、配额（空间/数据库/流量/域名绑定数）、节点映射、控制台地址 |
69| A4 | 订单/主机列表 | P0 | 关联订单与主机，展示状态、到期时间、配额用量 |
70| A5 | 手动管理 | P0 | 暂停/恢复/删除/改密/续费/启停/升降级 |
71| A6 | 到期策略配置 | P0 | 到期自动暂停开关、宽限期、续费恢复 |
72| A7 | 日志 | P1 | API 调用日志、开通/删除/续费审计 |
73| A8 | 通知 | P1 | 到期提醒邮件（提前 N 天）、开通成功通知 |
74
75### 3.2 前台（WordPress 前端）
76
77| 编号 | 功能 | 优先级 | 说明 |
78|------|------|--------|------|
79| B1 | 商品展示 | P0 | 套餐卡片：空间/数据库/流量/价格/控制台地址 |
80| B2 | 下单支付 | P0 | 走 WooCommerce 结账流程，支付成功回调触发开通 |
81| B3 | 我的主机 | P0 | 列出当前用户主机：状态、到期、配额用量、控制台入口 |
82| B4 | 主机操作 | P1 | 启停、改密、续费（生成续费订单） |
83| B5 | 控制台跳转 | P0 | "打开控制台"按钮跳转 MNBT 用户控制台 |
84| B6 | 用量展示 | P1 | 空间/数据库/流量用量进度条（`ztcx` 数据） |
85
86### 3.3 MNBT 集成（插件核心服务）
87
88| 编号 | 功能 | 优先级 | 说明 |
89|------|------|--------|------|
90| C1 | API 网关封装 | P0 | 统一鉴权（三密钥）、签名、超时、重试、错误归一化 |
91| C2 | 开通流程 | P0 | `kt` + 幂等保护（防重复开通）+ 失败回滚 |
92| C3 | 生命周期映射 | P0 | `zt`/`jc`/`tz`/`xf`/`czmm`/`start`/`stop`/`zjmode` |
93| C4 | 状态同步 | P0 | `ztcx` 定时同步状态与配额到本地表 |
94| C5 | 到期定时任务 | P0 | WP-Cron 每日扫描，到期暂停/续费恢复 |
95
96---
97
98## 4. 非功能需求
99
100| 类别 | 要求 |
101|------|------|
102| 安全 | 密钥存储加密；所有输出转义；后台操作权限校验；API 调用失败不泄露密钥 |
103| 性能 | API 调用设超时（≤15s）；列表页用本地缓存数据，不实时调 MNBT |
104| 兼容 | WordPress ≥ 6.0；PHP ≥ 7.4；WooCommerce ≥ 8.0；MNBT API mn_vs ≥ 15 |
105| 可维护 | 命名空间 `MnbtWp\`、表前缀 `mnbt_`、适配器模式隔离 MNBT 对接 |
106| 可靠性 | 开通幂等、定时任务加锁防并发、失败可重试、操作留日志 |
107
108---
109
110## 5. 技术架构
111
112### 5.1 组件
113
114```
115┌─────────────────────────────────────────────┐
116│ WordPress（本插件 wp_seller_plugin） │
117│ ┌───────────┐ ┌───────────┐ ┌────────────┐ │
118│ │ 商品/结账 │ │ 我的主机 │ │ 后台管理 │ │
119│ │ (Woo) │ │ 前端 Shortcode/Block │ │ (Settings) │ │
120│ └─────┬─────┘ └─────┬─────┘ └─────┬──────┘ │
121│ └──────────────┼─────────────┘ │
122│ ┌────────▼────────┐ │
123│ │ MNBT Client │ 适配器/网关 │
124│ │ 鉴权+签名+重试 │ │
125│ └────────┬────────┘ │
126│ ┌──────────────┼──────────────┐ │
127│ │ 开通/暂停/恢复/删除/续费/改密/启停/状态 │ │
128│ └──────────────┼──────────────┘ │
129└───────────────────────┼───────────────────────┘
130 │ HTTPS + 三密钥鉴权
131 ┌────────▼────────┐
132 │ MNBT api/api.php │
133 │ + 用户控制台 │ (cPanel 式自助管理)
134 └────────┬────────┘
135 │ 宝塔面板 API
136 ┌──────▼──────┐
137 │ 宝塔节点(多台) │
138 └─────────────┘
139```
140
141### 5.2 数据流（购买开通）
142
143```
144客户下单支付 → WooCommerce 钩子 woocommerce_payment_complete
145 → 创建本地主机记录(pending) → MNBT Client.kt()
146 → 成功：写入账号/密码/站点名，状态 active，通知客户
147 → 失败：标记 failed，可重试，通知站长
148```
149
150### 5.3 目录结构
151
152```
153wp_seller_plugin/
154├── wp-seller-plugin.php # 主文件（插件头、常量、加载）
155├── includes/
156│ ├── class-plugin.php # 插件生命周期（激活/卸载/初始化）
157│ ├── class-activator.php # 建表、默认配置
158│ ├── mnbt/
159│ │ ├── class-client.php # MNBT API 网关（鉴权/签名/请求）
160│ │ ├── class-adapter.php # 适配器接口（便于未来扩展其他面板）
161│ │ └── class-exception.php # 异常与错误归一化
162│ ├── admin/
163│ │ ├── class-admin.php # 后台菜单/设置页
164│ │ └── views/ # 后台模板
165│ ├── front/
166│ │ ├── class-front.php # Shortcode/Block 注册
167│ │ └── views/ # 前台模板
168│ ├── services/
169│ │ ├── class-provision.php # 开通/生命周期编排
170│ │ ├── class-billing.php # 续费/到期策略
171│ │ └── class-cron.php # 定时任务
172│ └── class-logger.php # 日志
173├── assets/ # js/css
174├── languages/ # i18n
175├── uninstall.php
176└── README.md
177```
178
179---
180
181## 6. API 对接规范（MNBT）
182
183### 6.1 鉴权参数（每次请求必带）
184
185| 参数 | 来源 |
186|------|------|
187| `mn_bh` | MNBT 后台宝塔节点开通代号（`MN_bt.btdh`） |
188| `mn_key` | MNBT 系统 API 密钥（`$conf['api']`，系统设置→API 密钥） |
189| `mn_keye` | 节点调用密钥 `md5(ktmy . qmk)`（宝塔列表 ktmy 列点击可见） |
190| `mn_vs` | 插件版本号，≥ 15 |
191| `username` | 主机用户名（= 客户在 MNBT 的主机账号） |
192
193### 6.2 接口映射
194
195| 场景 | gn | 关键参数 | 备注 |
196|------|----|---------|------|
197| 连接测试 | `cfif` | - | 验证三密钥 |
198| 开通 | `kt` | `password`,`sizemax`,`dqtime`,`webdx`,`sqldx`,`ymbds` | 建站+FTP+数据库；需幂等 |
199| 暂停 | `zt` | - | 停站点+FTP |
200| 恢复 | `jc` | - | 解除暂停 |
201| 删除 | `tz` | - | 删站点+删本地行 |
202| 续费 | `xf` | `setdate`(YYYY-MM-DD) | 更新到期时间 |
203| 改密 | `czmm` | `password` | FTP+控制面板密码 |
204| 升降级 | `zjmode` | `websize`,`sqlsize`,`ll` | 更新配额（MB） |
205| 启停 | `start`/`stop` | - | 站点启停 |
206| 状态查询 | `ztcx` | - | 返回状态+配额用量 |
207
208### 6.3 响应格式
209
210```json
211{ "success": true|false, "code": 200|100, "msg": "提示", "data": {...} }
212```
213
214插件需统一归一化：`code==200` 视为成功，其余取 `msg` 作为错误。
215
216### 6.4 集成最佳实践
217
218- **幂等**：开通前检查本地表是否已有该用户主机，防重复 `kt`；`kt` 失败且宝塔已建站时调用 `tz` 回滚。
219- **超时/重试**：网络异常（超时、连接失败）可重试 2 次；业务错误（100）不重试，直接记录。
220- **用户名策略**：避免与 MNBT 现有用户冲突，可用订单/用户 ID 生成（如 `wp_` + 用户ID + 随机），≥6 位。
221- **密码策略**：初始密码由插件生成（≥6 位），开通后以明文存本地并提示站长在"我的主机"查看/修改。
222- **时间字段**：`dqtime`/`setdate` 传 `Y-m-d`。
223
224---
225
226## 7. 里程碑与验收
227
228| 里程碑 | 内容 | 验收标准 |
229|--------|------|----------|
230| M0 脚手架 | 插件骨架、激活建表、后台设置页 | 可安装启用，配置页可保存 |
231| M1 连接打通 | MNBT Client + 连接测试 + 日志 | 配置正确密钥后 `cfif` 通过 |
232| M2 购买开通 | WooCommerce 商品扩展 + 支付回调开通 + 我的主机 | 支付后自动开通，前台可见账号/密码 |
233| M3 管理闭环 | 启停/改密/续费/删除 + 到期定时任务 | 全生命周期操作可用，到期自动暂停 |
234| M4 体验增强 | 用量进度条、控制台跳转、到期提醒、审计日志 | cPanel 式自助体验 |
235
236---
237
238## 8. 风险与对策
239
240| 风险 | 影响 | 对策 |
241|------|------|------|
242| MNBT API 无统一错误码 | 插件错误识别困难 | 网关层错误归一化 + 完整日志 |
243| 支付回调与开通时序 | 支付成功但开通失败 | 订单状态机 + 后台手动重试开通 |
244| 定时任务漂移（WP-Cron 依赖访问） | 到期暂停不及时 | 支持第三方 cron 触发（wp-cron.php 可外部调用） |
245| 用户名冲突/重复开通 | 数据错乱 | 用户名生成策略 + 开通前幂等检查 |
246| MNBT 升级 API 变更 | 对接失效 | 适配器模式 + 版本号校验（mn_vs） |