# PRD — WordPress 虚拟主机销售插件（wp_seller_plugin）

> 产品版本：v1.0
> 文档状态：草案
> 关联系统：MNBT（梦奈宝塔主机管理系统）

---

## 1. 产品概述

### 1.1 背景

MNBT 是一套基于宝塔面板的虚拟主机管理系统，已具备完整的**主机生命周期管理 API** 与 **cPanel 式的用户自助控制台**（文件管理、数据库、FTP、域名、SSL、日志等）。但 MNBT 本身不承载「对外销售」环节（商品、下单、支付、账单）。

魔方财务通过 `mf_modules/servers/mnbthost` 已证明第三方系统可无缝对接 MNBT API 售卖主机。本插件将把这一模式复刻到 **WordPress**，让站长在 WordPress 站点上直接售卖 MNBT 虚拟主机，体验向 cPanel 的「销售 + 自助管理」形态靠拢。

### 1.2 产品定位

- **销售层（WordPress）**：商品展示、购买下单、支付结算、订单管理。
- **管理层（WordPress + MNBT）**：主机开通/暂停/恢复/删除/续费/改密/启停/升降级。
- **自助层（MNBT 用户控制台）**：文件/数据库/域名/FTP/SSL 等深度管理，插件通过控制台入口复用，不重复开发。

### 1.3 目标

| 目标 | 衡量标准 |
|------|----------|
| 站长能用 WordPress 独立卖主机 | 从创建商品到客户自助开通全流程可跑通 |
| 用户购买后自动开通 | 支付成功后无需人工干预，自动调用 `kt` 开通 |
| 主机管理接近 cPanel 体验 | 前台提供状态、配额用量、启停/改密/续费；深度管理跳转 MNBT 控制台 |
| 到期不续费自动停站 | WordPress 定时任务调用 `zt`/`jc` 实现到期控制 |

### 1.4 非目标（V1 范围外）

- 不重写 MNBT 控制台功能（文件/数据库/域名管理复用 MNBT）。
- 不做多支付网关适配（V1 对接 WooCommerce 支付体系）。
- 不做 WordPress 多站点（Multisite）专属适配（保证兼容但不做增强）。

---

## 2. 用户与场景

### 2.1 角色

| 角色 | 说明 |
|------|------|
| 站长（WordPress 管理员） | 配置 MNBT 连接、上架主机商品、查看订单与主机、处理退款/工单 |
| 客户（WordPress 注册用户） | 浏览商品、购买支付、管理自己的主机 |

### 2.2 核心场景

1. **S1 购买开通**：客户选套餐 → 下单 → 支付成功 → 插件自动在 MNBT 开通主机（建站+FTP+数据库）→ 客户在"我的主机"看到账号/密码/控制台入口。
2. **S2 自助管理**：客户查看主机状态（运行中/暂停）、空间/数据库/流量用量条、执行启停、改密、续费。
3. **S3 到期控制**：每日定时任务扫描到期主机，到期未续费自动暂停，续费后恢复。
4. **S4 管理端运维**：站长查看所有主机、手动暂停/恢复/删除、调整配额、查看 MNBT 节点状态。

---

## 3. 功能需求

优先级：P0（V1 必须）/ P1（V1 建议）/ P2（后续迭代）。

### 3.1 管理端（WordPress 后台）

| 编号 | 功能 | 优先级 | 说明 |
|------|------|--------|------|
| A1 | MNBT 连接配置 | P0 | 节点代号(btdh)、系统 API 密钥、调用密钥、API 地址、版本号；支持多节点 |
| A2 | 连接测试 | P0 | 调用 `cfif` 验证配置 |
| A3 | 商品管理 | P0 | 基于 WooCommerce 产品扩展：套餐类型、配额（空间/数据库/流量/域名绑定数）、节点映射、控制台地址 |
| A4 | 订单/主机列表 | P0 | 关联订单与主机，展示状态、到期时间、配额用量 |
| A5 | 手动管理 | P0 | 暂停/恢复/删除/改密/续费/启停/升降级 |
| A6 | 到期策略配置 | P0 | 到期自动暂停开关、宽限期、续费恢复 |
| A7 | 日志 | P1 | API 调用日志、开通/删除/续费审计 |
| A8 | 通知 | P1 | 到期提醒邮件（提前 N 天）、开通成功通知 |

### 3.2 前台（WordPress 前端）

| 编号 | 功能 | 优先级 | 说明 |
|------|------|--------|------|
| B1 | 商品展示 | P0 | 套餐卡片：空间/数据库/流量/价格/控制台地址 |
| B2 | 下单支付 | P0 | 走 WooCommerce 结账流程，支付成功回调触发开通 |
| B3 | 我的主机 | P0 | 列出当前用户主机：状态、到期、配额用量、控制台入口 |
| B4 | 主机操作 | P1 | 启停、改密、续费（生成续费订单） |
| B5 | 控制台跳转 | P0 | "打开控制台"按钮跳转 MNBT 用户控制台 |
| B6 | 用量展示 | P1 | 空间/数据库/流量用量进度条（`ztcx` 数据） |

### 3.3 MNBT 集成（插件核心服务）

| 编号 | 功能 | 优先级 | 说明 |
|------|------|--------|------|
| C1 | API 网关封装 | P0 | 统一鉴权（三密钥）、签名、超时、重试、错误归一化 |
| C2 | 开通流程 | P0 | `kt` + 幂等保护（防重复开通）+ 失败回滚 |
| C3 | 生命周期映射 | P0 | `zt`/`jc`/`tz`/`xf`/`czmm`/`start`/`stop`/`zjmode` |
| C4 | 状态同步 | P0 | `ztcx` 定时同步状态与配额到本地表 |
| C5 | 到期定时任务 | P0 | WP-Cron 每日扫描，到期暂停/续费恢复 |

---

## 4. 非功能需求

| 类别 | 要求 |
|------|------|
| 安全 | 密钥存储加密；所有输出转义；后台操作权限校验；API 调用失败不泄露密钥 |
| 性能 | API 调用设超时（≤15s）；列表页用本地缓存数据，不实时调 MNBT |
| 兼容 | WordPress ≥ 6.0；PHP ≥ 7.4；WooCommerce ≥ 8.0；MNBT API mn_vs ≥ 15 |
| 可维护 | 命名空间 `MnbtWp\`、表前缀 `mnbt_`、适配器模式隔离 MNBT 对接 |
| 可靠性 | 开通幂等、定时任务加锁防并发、失败可重试、操作留日志 |

---

## 5. 技术架构

### 5.1 组件

```
┌─────────────────────────────────────────────┐
│ WordPress（本插件 wp_seller_plugin）          │
│  ┌───────────┐ ┌───────────┐ ┌────────────┐ │
│  │ 商品/结账   │ │ 我的主机    │ │ 后台管理     │ │
│  │ (Woo)     │ │ 前端 Shortcode/Block │ │ (Settings) │ │
│  └─────┬─────┘ └─────┬─────┘ └─────┬──────┘ │
│        └──────────────┼─────────────┘        │
│              ┌────────▼────────┐              │
│              │ MNBT Client      │ 适配器/网关   │
│              │ 鉴权+签名+重试    │              │
│              └────────┬────────┘              │
│        ┌──────────────┼──────────────┐        │
│        │ 开通/暂停/恢复/删除/续费/改密/启停/状态 │        │
│        └──────────────┼──────────────┘        │
└───────────────────────┼───────────────────────┘
                        │ HTTPS + 三密钥鉴权
               ┌────────▼────────┐
               │ MNBT api/api.php │
               │  + 用户控制台     │ (cPanel 式自助管理)
               └────────┬────────┘
                        │ 宝塔面板 API
                 ┌──────▼──────┐
                 │ 宝塔节点(多台) │
                 └─────────────┘
```

### 5.2 数据流（购买开通）

```
客户下单支付 → WooCommerce 钩子 woocommerce_payment_complete
    → 创建本地主机记录(pending) → MNBT Client.kt()
    → 成功：写入账号/密码/站点名，状态 active，通知客户
    → 失败：标记 failed，可重试，通知站长
```

### 5.3 目录结构

```
wp_seller_plugin/
├── wp-seller-plugin.php          # 主文件（插件头、常量、加载）
├── includes/
│   ├── class-plugin.php          # 插件生命周期（激活/卸载/初始化）
│   ├── class-activator.php       # 建表、默认配置
│   ├── mnbt/
│   │   ├── class-client.php      # MNBT API 网关（鉴权/签名/请求）
│   │   ├── class-adapter.php     # 适配器接口（便于未来扩展其他面板）
│   │   └── class-exception.php   # 异常与错误归一化
│   ├── admin/
│   │   ├── class-admin.php       # 后台菜单/设置页
│   │   └── views/                # 后台模板
│   ├── front/
│   │   ├── class-front.php       # Shortcode/Block 注册
│   │   └── views/                # 前台模板
│   ├── services/
│   │   ├── class-provision.php   # 开通/生命周期编排
│   │   ├── class-billing.php     # 续费/到期策略
│   │   └── class-cron.php        # 定时任务
│   └── class-logger.php          # 日志
├── assets/                       # js/css
├── languages/                    # i18n
├── uninstall.php
└── README.md
```

---

## 6. API 对接规范（MNBT）

### 6.1 鉴权参数（每次请求必带）

| 参数 | 来源 |
|------|------|
| `mn_bh` | MNBT 后台宝塔节点开通代号（`MN_bt.btdh`） |
| `mn_key` | MNBT 系统 API 密钥（`$conf['api']`，系统设置→API 密钥） |
| `mn_keye` | 节点调用密钥 `md5(ktmy . qmk)`（宝塔列表 ktmy 列点击可见） |
| `mn_vs` | 插件版本号，≥ 15 |
| `username` | 主机用户名（= 客户在 MNBT 的主机账号） |

### 6.2 接口映射

| 场景 | gn | 关键参数 | 备注 |
|------|----|---------|------|
| 连接测试 | `cfif` | - | 验证三密钥 |
| 开通 | `kt` | `password`,`sizemax`,`dqtime`,`webdx`,`sqldx`,`ymbds` | 建站+FTP+数据库；需幂等 |
| 暂停 | `zt` | - | 停站点+FTP |
| 恢复 | `jc` | - | 解除暂停 |
| 删除 | `tz` | - | 删站点+删本地行 |
| 续费 | `xf` | `setdate`(YYYY-MM-DD) | 更新到期时间 |
| 改密 | `czmm` | `password` | FTP+控制面板密码 |
| 升降级 | `zjmode` | `websize`,`sqlsize`,`ll` | 更新配额（MB） |
| 启停 | `start`/`stop` | - | 站点启停 |
| 状态查询 | `ztcx` | - | 返回状态+配额用量 |

### 6.3 响应格式

```json
{ "success": true|false, "code": 200|100, "msg": "提示", "data": {...} }
```

插件需统一归一化：`code==200` 视为成功，其余取 `msg` 作为错误。

### 6.4 集成最佳实践

- **幂等**：开通前检查本地表是否已有该用户主机，防重复 `kt`；`kt` 失败且宝塔已建站时调用 `tz` 回滚。
- **超时/重试**：网络异常（超时、连接失败）可重试 2 次；业务错误（100）不重试，直接记录。
- **用户名策略**：避免与 MNBT 现有用户冲突，可用订单/用户 ID 生成（如 `wp_` + 用户ID + 随机），≥6 位。
- **密码策略**：初始密码由插件生成（≥6 位），开通后以明文存本地并提示站长在"我的主机"查看/修改。
- **时间字段**：`dqtime`/`setdate` 传 `Y-m-d`。

---

## 7. 里程碑与验收

| 里程碑 | 内容 | 验收标准 |
|--------|------|----------|
| M0 脚手架 | 插件骨架、激活建表、后台设置页 | 可安装启用，配置页可保存 |
| M1 连接打通 | MNBT Client + 连接测试 + 日志 | 配置正确密钥后 `cfif` 通过 |
| M2 购买开通 | WooCommerce 商品扩展 + 支付回调开通 + 我的主机 | 支付后自动开通，前台可见账号/密码 |
| M3 管理闭环 | 启停/改密/续费/删除 + 到期定时任务 | 全生命周期操作可用，到期自动暂停 |
| M4 体验增强 | 用量进度条、控制台跳转、到期提醒、审计日志 | cPanel 式自助体验 |

---

## 8. 风险与对策

| 风险 | 影响 | 对策 |
|------|------|------|
| MNBT API 无统一错误码 | 插件错误识别困难 | 网关层错误归一化 + 完整日志 |
| 支付回调与开通时序 | 支付成功但开通失败 | 订单状态机 + 后台手动重试开通 |
| 定时任务漂移（WP-Cron 依赖访问） | 到期暂停不及时 | 支持第三方 cron 触发（wp-cron.php 可外部调用） |
| 用户名冲突/重复开通 | 数据错乱 | 用户名生成策略 + 开通前幂等检查 |
| MNBT 升级 API 变更 | 对接失效 | 适配器模式 + 版本号校验（mn_vs） |