163 lines
7.9 KiB
Markdown
163 lines
7.9 KiB
Markdown
# 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_users`（或 `users`，注意与 `sys_user` 后台账号区分 — **建议业务客户表用前缀 `biz_`**，避免与系统用户混淆）
|
||
- `biz_plans`
|
||
- `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/users` 或 `/admin_api/biz_users` |
|
||
| `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 在线文档对照开发。*
|