# WechatAdminWeb — 订阅模块后台实施计划

> 依据：`_docs/后端管理平台需求说明.md` 中 **「订阅模块 / 轻量核心版」** 与 **§7 管理端 API（MVP）**；技术栈以仓库现有 **node-core-framework** + **admin-framework.js** 为准。  
> 说明：需求文档后半部分「微信自动化平台 V1（合同/账单/分成/风控等）」**不在本期范围**，若后续要扩展，可单独立项。

---

## 1. 范围与验收对齐

### 1.1 本期必做（P0）

| 模块 | 内容 |
|------|------|
| 用户管理 | 增删改查、禁用；列表筛选（手机/公司/状态）；详情含当前订阅与 Token 概要 |
| 套餐管理 | CRUD、上下线、额度与 `enabled_features`（JSON） |
| 订阅 | 开通、升级、续费、取消；按 `user_id` 查询；状态机 `pending/active/expired/cancelled` |
| Token | 创建（仅一次明文）、吊销、有效期、`last_used_at`；单用户数量上限（如 5） |
| 对外鉴权 | Token 校验 + 有效订阅 + 功能点 + 月额度；统一错误码 |

### 1.2 本期次优先（P1）

| 模块 | 内容 |
|------|------|
| 支付 | `confirm-offline`、`confirm-link`（录入 `payment_ref` / 模拟回调开通） |
| 用量与额度 | `usage_monthly` 聚合、调用侧上报或管理端录入；超配额返回 `QUOTA_EXCEEDED` |
| 定时任务 | 到期扫描、月结归档、续费提醒（D-7/D-3/D-1） |

### 1.3 可选增强（P2）

- 审计日志表 + 关键操作写入（需求「最小风控与安全」）
- 一键吊销某用户全部 Token
- 简单运营看板（用户数、到期分布）

### 1.4 数据表命名统一

需求中同时出现 `subscriptions` 与 `user_subscriptions`。实施时 **固定一张业务订阅表**（建议表名 `biz_subscriptions` 或 `user_subscriptions`，与现有命名风格一致），在 DDL 与文档中只保留一种，避免混用。

`api_tokens` 轻量版建议含 **`plan_id` 冗余**（便于鉴权时少联表），与需求「3.4 Token」轻量版一致。

---

## 2. 技术约定（与仓库现状对齐）

### 2.1 后端

- **入口**：`app.js` → `Framework.init`（`framework/node-core-framework.js`）。
- **管理端 API 前缀**：`config/framework.config.js` 中 `apiPaths` 已配置为 **`/admin_api`** + `authType: 'admin'`。  
  - 需求文档中的 `/admin/...` 在实现时映射为 **`/admin_api/...`**（或在网关层做重写），**Swagger/前端 axios 基路径需统一**。
- **模型**：`api/model/*.js`，Sequelize `db.define` 风格（参考 `api/model/sys_user.js`）。
- **控制器**：`api/controller_admin/*.js`，导出形如 `"METHOD /path": async (ctx) => {}`（参考 `api/controller_admin/sys_file.js`）。
- **关联**：`config/model.associations.js` 中注册 `users` / `plans` / `subscriptions` / `api_tokens` / `usage_monthly` 的 `belongsTo`/`hasMany`。

### 2.2 需先修复的阻塞项

| 问题 | 处理 |
|------|------|
| `app.js` 引用 `./config/model.associations.wms.js`，仓库中 **不存在** | 改为引用 `./config/model.associations.js`，或在 `config` 下增加兼容 re-export，保证 `npm start` 可启动 |

### 2.3 管理端前端

- **入口**：`admin/src/main.js`，`AdminFramework.createApp` + `componentMap`（`admin/src/router/component-map.js`）。
- **页面**：为「用户 / 套餐 / 订阅 / Token / 支付确认」各增 Vue 页，并在 `componentMap` 注册；列表/表单模式对齐现有 `admin-framework` 与 `test/test.vue` 用法。
- **接口封装**：`admin/src/api/` 下新增模块，**baseURL 指向 `admin_api`**（与 `admin/config` 中 `apiUrl` 一致）。

### 2.4 定时任务

- `middleware/schedule.js` 的 `init()` 内用 `node-schedule` 注册：
  - 每天 **00:10** — 订阅到期扫描 → `expired`
  - 每月 **1 日 00:30** — 用量月结归档（如有需要）
  - 每天 **09:00** — 续费提醒（写通知表或日志，MVP 可先日志）

---

## 3. 数据层实施清单

### 3.1 DDL（MySQL）

新建迁移或 SQL 脚本（建议 `_docs/sql/` 或 `migrations/`，与团队习惯一致）包含：

- `biz_user`（与模型 `api/model/biz_user.js` 的 `tableName` 一致；与 `sys_user` 后台账号区分）
- `biz_plan`
- `biz_subscriptions`（字段含 `renew_mode`、`payment_channel`、`payment_ref` 等）
- `biz_api_token`（`token_hash`、`plan_id` 可选冗余）
- `biz_usage_monthly`（`stat_month` YYYY-MM）

### 3.2 Sequelize 模型文件

每个表一个 `api/model/biz_*.js`，字段类型、注释与需求一致；`enabled_features` 用 `JSON` 或 `TEXT` + 序列化。

### 3.3 安全

- Token 明文仅创建接口返回一次；库内只存 **hash**（如 SHA-256 + salt，与框架内 crypto 工具一致）。
- 管理端接口走 `admin` 鉴权；对外鉴权接口放 `api/controller_front` 或单独 `prefix`，**放入 allowUrls 或 Header 鉴权**，与需求「每次请求」流程一致。

---

## 4. API 实施清单（路径以 `/admin_api` 为准）

需求 §7 映射如下（**实际路由字符串以框架注册为准**）：

| 需求路径 | 实现前缀 |
|----------|----------|
| `POST /admin/users` | `POST /admin_api/biz_user/page` 等（以实际 controller 为准） |
| `GET /admin/users` | `GET /admin_api/users` |
| `GET /admin/users/{id}` | `GET /admin_api/users/:id` |
| `PUT /admin/users/{id}` | `PUT /admin_api/users/:id` |
| `POST /admin/users/{id}/disable` | `POST /admin_api/users/:id/disable` |
| 套餐 / 订阅 / Token / 支付 | 同上模式 |

**对外鉴权（非管理端）**建议单独一组，例如：

- `POST /api/auth/verify` 或 `GET /api/auth/context`：入参 Token + `feature` + 可选用量上报字段，返回用户上下文或错误码。

错误码与需求 §6 一致：`TOKEN_INVALID`、`TOKEN_EXPIRED`、`TOKEN_REVOKED`、`SUBSCRIPTION_INACTIVE`、`FEATURE_NOT_ALLOWED`、`QUOTA_EXCEEDED`。

---

## 5. 前端页面与菜单

| 页面 | 路由 component key（示例） | 功能 |
|------|------------------------------|------|
| 用户列表/编辑 | `subscription/user` | 表格 + 搜索 + 抽屉表单 |
| 套餐列表/编辑 | `subscription/plan` | JSON 功能点编辑器（简易 textarea 或 key-value） |
| 订阅操作 | `subscription/subscription` | 开通/升级/续费/取消向导或表单 |
| Token | `subscription/token` | 列表、创建（展示一次明文）、吊销 |
| 支付确认 | `subscription/payment` | 线下确认、链接确认表单 |

菜单数据若来自后端 `sys_menu`，需在库中插入对应菜单项，`component` 与 `component-map.js` **key 一致**。

---

## 6. 实施顺序（建议迭代）

1. **迭代 A**：修复 `model.associations` 引用；建表 + 模型 + associations；用户 + 套餐 CRUD API 与页面。
2. **迭代 B**：订阅状态机 + 开通/升级/续费/取消 API + 页面；支付确认打通「pending → active」。
3. **迭代 C**：Token 创建/吊销/哈希；对外鉴权接口 + 错误码；用量表与额度校验。
4. **迭代 D**：定时任务（到期扫描、提醒）；Swagger 补全；联调验收用例（需求 §9）。

---

## 7. 交付物

- 可运行的后端 + 管理端前端，完成「创建用户 → 支付确认 → 订阅生效 → Token 发放 → 鉴权与额度」闭环。
- 本文档同目录可补充 **`_docs/sql/001_biz_schema.sql`**（实施时产出）。
- API 文档：框架自带 `/api/docs`，需保证新接口有 Swagger 注解或框架要求的注释格式。

---

## 8. 参考文件（仓库内）

| 说明 | 路径 |
|------|------|
| 框架入口 | `app.js`、`config/framework.config.js` |
| 管理端控制器 | `api/controller_admin/sys_file.js` |
| 模型示例 | `api/model/sys_user.js` |
| 定时任务壳 | `middleware/schedule.js` |
| 前端挂载 | `admin/src/main.js`、`admin/src/router/component-map.js` |
| 需求原文 | `_docs/后端管理平台需求说明.md` |

---

*文档版本：v1 | 与 README 中 admin-framework / node-core-framework 在线文档对照开发。*