wechatWeb/_docs/订阅模块实施计划.md

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 在线文档对照开发。