docs: add PRD and BEST_PRACTICE_PLAN documents for wp seller plugin

diff --git a/wp_seller_plugin/BEST_PRACTICE_PLAN.md b/wp_seller_plugin/BEST_PRACTICE_PLAN.md
new file mode 100644
index 0000000..cd41838
--- /dev/null
+++ b/wp_seller_plugin/BEST_PRACTICE_PLAN.md
@@ -0,0 +1,161 @@
+# 最佳实践计划 — WordPress 虚拟主机销售插件（wp_seller_plugin）
+
+> 目标：以工程最佳实践交付一个安全、可靠、可维护、可扩展的 WordPress 主机销售插件，复用 MNBT 现有 API 与用户控制台，向 cPanel 式体验靠拢。
+
+---
+
+## 1. 总体原则
+
+1. **复用优先**：销售用 WordPress/WooCommerce，深度管理复用 MNBT 用户控制台，插件只做「编排 + 网关 + 用户中心」。
+2. **适配器隔离**：MNBT 对接封装在独立适配器层，未来切换/增加面板（如直接接宝塔、接其他财务系统）不改业务层。
+3. **幂等与补偿**：开通、续费等有外部副作用的操作必须幂等，失败可重试/回滚。
+4. **安全默认**：密钥加密存储、输出转义、权限校验、最小暴露。
+
+---
+
+## 2. WordPress 插件开发最佳实践
+
+### 2.1 代码规范
+
+- **命名空间**：统一 `MnbtWp\`，类文件 `class-*.php`，文件名小写连字符。
+- **表/选项前缀**：数据库表 `wp_mnbt_*`（`$wpdb->prefix . 'mnbt_'`）；选项 `mnbt_*`。
+- **唯一前缀**：所有函数/常量/钩子用 `mnbt_` 前缀，避免与主题/其他插件冲突。
+- **直接文件访问拦截**：每个 PHP 文件头部 `if (!defined('ABSPATH')) exit;`。
+- **i18n**：文案统一 `__('...', 'wp-seller-plugin')`，文本域 `wp-seller-plugin`。
+- **PHP 版本**：目标 PHP ≥ 7.4，使用类型声明与强类型。
+
+### 2.2 Hooks 使用规范
+
+- 初始化、加载类统一走 `plugins_loaded`；菜单走 `admin_menu`。
+- 前台输出统一走 Shortcode/Block（`[mnbt_my_hosts]` 等），避免硬编码 HTML。
+- 定时任务用 WP-Cron 注册（`wp_schedule_event`），**用 `transient` 加锁**防止并发重叠执行。
+- WooCommerce 集成用其官方钩子：`woocommerce_payment_complete`、`woocommerce_order_status_*`，不监听私有事件。
+
+### 2.3 数据层
+
+- 全部用 `$wpdb->prepare()` 预处理，禁止拼接 SQL。
+- 建表在激活钩子执行，带 `dbDelta()`；卸载删除自定义表需用户确认（`uninstall.php`）。
+- 密钥（`mn_key`/`mn_keye`）用 WordPress 密钥加密（`$wpdb->prepare` + `wp_salt()` 派生加密），前台/日志绝不输出明文。
+- 定时任务、列表页数据优先读本地表（通过 `ztcx` 同步），避免实时远程调用拖慢页面。
+
+### 2.4 安全清单
+
+| 项 | 要求 |
+|----|------|
+| 权限 | 后台所有 AJAX/页面校验 `current_user_can('manage_options')` |
+| 转义 | 输出用 `esc_html/esc_attr/esc_url`；属性与 JS 上下文正确转义 |
+| CSRF | 后台表单加 `nonce`；AJAX 校验 `check_ajax_referer` |
+| SSRF | MNBT API 地址允许配置但请求目标限定 `https?://`，禁止内网地址（复用 MNBT 插件引擎同策略） |
+| 错误信息 | 对用户隐藏密钥/内部堆栈，写入日志 |
+| 上传 | 插件不接收文件上传（V1），避免文件处理面 |
+
+---
+
+## 3. MNBT 对接最佳实践
+
+### 3.1 适配器接口（便于扩展）
+
+```php
+interface MnbtWp\Mnbt\HostProviderInterface {
+    public function testConnection(): bool;
+    public function createHost(array $params): array;   // 返回 ['ok'=>bool,'msg'=>string,'data'=>[...]]
+    public function suspendHost(string $username): bool;
+    public function resumeHost(string $username): bool;
+    public function deleteHost(string $username): bool;
+    public function renewHost(string $username, string $expireDate): bool;
+    public function changePassword(string $username, string $password): bool;
+    public function changePackage(string $username, array $quota): bool;
+    public function startSite(string $username): bool;
+    public function stopSite(string $username): bool;
+    public function getHostStatus(string $username): array;  // 状态+配额
+}
+```
+
+- `MnbtWp\Mnbt\Client`（实现类）封装 MNBT `api/api.php`。
+- 业务层（`Provision`/`Billing`）只依赖接口，不依赖具体实现。
+
+### 3.2 Client 网关要点
+
+- **请求**：`wp_remote_post($url, ['timeout'=>15, 'body'=>$params])`，校验 `is_wp_error`。
+- **鉴权**：每次请求拼装 `mn_bh/mn_key/mn_keye/mn_vs/username`。
+- **超时与重试**：网络层失败（超时/连接失败）自动重试 2 次（间隔 1s/3s）；业务失败（`code!=200`）不重试。
+- **错误归一化**：统一抛出 `MnbtWp\Mnbt\Exception`，`message` 用 MNBT `msg`，`context` 记录 request_id/params（脱敏）。
+- **日志**：每次调用写 `mnbt_api_log` 表（时间、动作、参数摘要、响应 code/msg、耗时）。
+
+### 3.3 开通流程（幂等 + 补偿）
+
+```
+状态机：pending → provisioning → active / failed
+1. 前置校验：本地表该用户无 active 主机；参数完整
+2. 生成用户名：wp_{userId}_{rand4}（≥6位）；生成初始密码
+3. 调 kt：成功→写本地表 active，记录账号/密码/站点名/到期时间
+4. 失败：若 kt 部分成功（宝塔已建站但本地写库失败）→ 调 tz 回滚
+5. 通知：成功通知客户（含账号密码与控制台地址）；失败通知站长
+```
+
+### 3.4 到期与续费
+
+- **每日 cron**：扫描 `datae` 到期的 active 主机：
+  - 过期且在宽限期（可配，默认 0）内 → 发提醒；
+  - 过期超宽限期 → 调 `zt` 暂停 + 本地状态 `expired`；
+  - 续费订单支付成功 → 调 `xf` 更新到期时间 → 若已暂停调 `jc` 恢复。
+- **续费商品**：生成按月的 WooCommerce 订阅/一次性续费商品，订单成功后走同一 `renewHost`。
+
+### 3.5 状态与用量同步
+
+- cron 每 10 分钟调 `ztcx` 更新本地 `mnbt_hosts`（状态、空间/数据库/流量用量），前台从本地表读。
+- 用量单位为 MB（与 MNBT 一致），进度条按 `used/max` 计算。
+
+---
+
+## 4. 开发阶段计划
+
+| 阶段 | 目标 | 交付物 | 完成标志 |
+|------|------|--------|----------|
+| **P0 脚手架** | 插件骨架可安装 | 主文件、激活建表、后台设置页、i18n 框架 | 后台可配置 MNBT 连接并保存 |
+| **P1 网关打通** | MNBT 通信可用 | Client/Adapter/Logger、连接测试、错误归一化 | `cfif` 测试通过，日志可查 |
+| **P2 购买闭环** | 能卖并能开通 | WooCommerce 商品扩展、支付回调开通、我的主机页、开通通知 | 支付后自动开通，前台可见 |
+| **P3 管理闭环** | 全生命周期 | 启停/改密/续费/删除/升降级、到期定时任务、续费流程 | 管理操作可用，到期自动暂停/续费恢复 |
+| **P4 体验增强** | 接近 cPanel | 用量进度条、控制台跳转、到期提醒邮件、管理端主机总览、审计日志 | 自助体验完善 |
+
+> 每个阶段结束做一次**安全自审 + 回归测试**（WordPress 5.x/6.x、PHP 7.4/8.x、WooCommerce 8/9）。
+
+---
+
+## 5. 测试与发布
+
+### 5.1 测试策略
+
+- **单元测试**：PHPUnit + WP_Mock（针对 Client 签名、配额计算、错误归一化）。
+- **集成测试**：本地 WordPress + 测试 MNBT 节点（可用 docker 起宝塔或 mock api/api.php）。
+- **关键场景用例**：
+  1. 支付成功→开通→前台可见；
+  2. 重复支付回调不重复开通（幂等）；
+  3. kt 失败可重试，无脏数据；
+  4. 到期自动暂停、续费恢复；
+  5. 密钥错误时测试连接给出明确错误；
+  6. 禁用插件数据保留、卸载删除按确认执行。
+
+### 5.2 发布
+
+- 版本管理：SemVer；主文件版本 + `readme.txt` 同步。
+- 分发：Git 仓库（git tag）+ 可选提交 WordPress.org（遵守其插件指南：无隐藏外链、GPL）。
+- 升级：`upgrader_process_complete` 钩子做数据迁移（表结构变更用 `dbDelta`）。
+
+---
+
+## 6. 运维与监控
+
+- **日志**：`mnbt_api_log` 保留 N 天，后台可查；关键操作（开通/删除/改密）记审计。
+- **监控**：每日检查 `failed` 状态主机数量；API 连续失败计数超阈值发邮件提醒站长。
+- **备份**：依赖 WordPress 数据库备份；插件自身不处理站点文件备份（V1）。
+
+---
+
+## 7. 未来演进（Backlog）
+
+- SSO 单点登录跳转 MNBT 用户控制台（自动登录）。
+- 流量超额限速/通知；空间/数据库用量实时刷新。
+- 一键部署应用（对接 MNBT 部署能力）。
+- 多面板适配器（直接对接宝塔 / 对接其他财务系统）。
+- 多币种、优惠码、自动续费（WooCommerce Subscriptions 深度集成）。
diff --git a/wp_seller_plugin/PRD.md b/wp_seller_plugin/PRD.md
new file mode 100644
index 0000000..84276b5
--- /dev/null
+++ b/wp_seller_plugin/PRD.md
@@ -0,0 +1,246 @@
+# 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） |