init

_docs/sql/001_biz_schema.sql

@@ -0,0 +1,101 @@
+-- WechatAdminWeb 订阅模块业务表（MySQL 8+）
+-- 执行前请确认库名；与 api/model/biz_*.js 字段一致
+
+SET NAMES utf8mb4;
+
+-- 业务用户（与 sys_user 后台账号区分）
+CREATE TABLE IF NOT EXISTS `biz_users` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+  `name` VARCHAR(100) NOT NULL DEFAULT '',
+  `mobile` VARCHAR(20) NULL DEFAULT NULL,
+  `email` VARCHAR(120) NULL DEFAULT NULL,
+  `company_name` VARCHAR(200) NULL DEFAULT NULL,
+  `status` ENUM('active', 'disabled') NOT NULL DEFAULT 'active',
+  `created_at` DATETIME NOT NULL,
+  `updated_at` DATETIME NOT NULL,
+  PRIMARY KEY (`id`),
+  KEY `idx_biz_users_mobile` (`mobile`),
+  KEY `idx_biz_users_status` (`status`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='业务用户';
+
+-- 套餐
+CREATE TABLE IF NOT EXISTS `biz_plans` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+  `plan_code` VARCHAR(64) NOT NULL DEFAULT '',
+  `plan_name` VARCHAR(128) NOT NULL DEFAULT '',
+  `monthly_price` DECIMAL(12, 2) NOT NULL DEFAULT 0,
+  `auth_fee` DECIMAL(12, 2) NOT NULL DEFAULT 0,
+  `account_limit` INT NOT NULL DEFAULT 0,
+  `active_user_limit` INT NOT NULL DEFAULT 0,
+  `msg_quota` INT NOT NULL DEFAULT 0,
+  `mass_quota` INT NOT NULL DEFAULT 0,
+  `friend_quota` INT NOT NULL DEFAULT 0,
+  `sns_quota` INT NOT NULL DEFAULT 0,
+  `enabled_features` JSON NULL,
+  `status` ENUM('active', 'inactive') NOT NULL DEFAULT 'active',
+  `created_at` DATETIME NOT NULL,
+  `updated_at` DATETIME NOT NULL,
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_biz_plans_code` (`plan_code`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='套餐';
+
+-- 订阅实例
+CREATE TABLE IF NOT EXISTS `biz_subscriptions` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+  `user_id` BIGINT UNSIGNED NOT NULL,
+  `plan_id` BIGINT UNSIGNED NOT NULL,
+  `status` ENUM('pending', 'active', 'expired', 'cancelled') NOT NULL DEFAULT 'pending',
+  `start_time` DATETIME NOT NULL,
+  `end_time` DATETIME NOT NULL,
+  `renew_mode` ENUM('manual', 'auto') NOT NULL DEFAULT 'manual',
+  `payment_channel` ENUM('offline', 'pay_link') NULL DEFAULT NULL,
+  `payment_ref` VARCHAR(200) NULL DEFAULT NULL,
+  `created_at` DATETIME NOT NULL,
+  `updated_at` DATETIME NOT NULL,
+  PRIMARY KEY (`id`),
+  KEY `idx_biz_sub_user` (`user_id`),
+  KEY `idx_biz_sub_plan` (`plan_id`),
+  KEY `idx_biz_sub_status_end` (`status`, `end_time`),
+  CONSTRAINT `fk_biz_sub_user` FOREIGN KEY (`user_id`) REFERENCES `biz_users` (`id`) ON DELETE CASCADE ON UPDATE CASCADE,
+  CONSTRAINT `fk_biz_sub_plan` FOREIGN KEY (`plan_id`) REFERENCES `biz_plans` (`id`) ON DELETE RESTRICT ON UPDATE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='订阅';
+
+-- API Token（库内仅存 hash；plan_id 冗余便于鉴权少联表）
+CREATE TABLE IF NOT EXISTS `biz_api_tokens` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+  `user_id` BIGINT UNSIGNED NOT NULL,
+  `plan_id` BIGINT UNSIGNED NULL DEFAULT NULL,
+  `token_name` VARCHAR(100) NOT NULL DEFAULT '',
+  `token_hash` VARCHAR(64) NOT NULL,
+  `status` ENUM('active', 'revoked', 'expired') NOT NULL DEFAULT 'active',
+  `expire_at` DATETIME NOT NULL,
+  `last_used_at` DATETIME NULL DEFAULT NULL,
+  `created_at` DATETIME NOT NULL,
+  `updated_at` DATETIME NOT NULL,
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_biz_token_hash` (`token_hash`),
+  KEY `idx_biz_token_user` (`user_id`),
+  KEY `idx_biz_token_plan` (`plan_id`),
+  CONSTRAINT `fk_biz_token_user` FOREIGN KEY (`user_id`) REFERENCES `biz_users` (`id`) ON DELETE CASCADE ON UPDATE CASCADE,
+  CONSTRAINT `fk_biz_token_plan` FOREIGN KEY (`plan_id`) REFERENCES `biz_plans` (`id`) ON DELETE SET NULL ON UPDATE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='API Token';
+
+-- 月用量
+CREATE TABLE IF NOT EXISTS `biz_usage_monthly` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+  `user_id` BIGINT UNSIGNED NOT NULL,
+  `plan_id` BIGINT UNSIGNED NOT NULL,
+  `stat_month` CHAR(7) NOT NULL COMMENT 'YYYY-MM',
+  `msg_count` INT NOT NULL DEFAULT 0,
+  `mass_count` INT NOT NULL DEFAULT 0,
+  `friend_count` INT NOT NULL DEFAULT 0,
+  `sns_count` INT NOT NULL DEFAULT 0,
+  `active_user_count` INT NOT NULL DEFAULT 0,
+  `created_at` DATETIME NOT NULL,
+  `updated_at` DATETIME NOT NULL,
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_biz_usage_user_month` (`user_id`, `stat_month`),
+  KEY `idx_biz_usage_plan` (`plan_id`),
+  CONSTRAINT `fk_biz_usage_user` FOREIGN KEY (`user_id`) REFERENCES `biz_users` (`id`) ON DELETE CASCADE ON UPDATE CASCADE,
+  CONSTRAINT `fk_biz_usage_plan` FOREIGN KEY (`plan_id`) REFERENCES `biz_plans` (`id`) ON DELETE RESTRICT ON UPDATE CASCADE
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='月用量';

_docs/sql/003_biz_audit.sql

@@ -0,0 +1,16 @@
+-- 审计日志（关键操作留痕）
+SET NAMES utf8mb4;
+
+CREATE TABLE IF NOT EXISTS `biz_audit_log` (
+  `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+  `admin_user_id` BIGINT UNSIGNED NULL DEFAULT NULL COMMENT '后台操作者 sys_user.id，可空',
+  `biz_user_id` BIGINT UNSIGNED NULL DEFAULT NULL COMMENT '相关业务用户',
+  `action` VARCHAR(64) NOT NULL COMMENT '动作标识',
+  `resource_type` VARCHAR(64) NOT NULL DEFAULT '',
+  `resource_id` BIGINT UNSIGNED NULL DEFAULT NULL,
+  `detail` JSON NULL,
+  `created_at` DATETIME NOT NULL,
+  PRIMARY KEY (`id`),
+  KEY `idx_biz_audit_action` (`action`),
+  KEY `idx_biz_audit_created` (`created_at`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='订阅模块审计';

_docs/后端管理平台需求说明.md

@@ -0,0 +1,840 @@
+# 后端管理平台需求说明（仅订阅模块）
+
+## 1. 范围
+
+本期只做订阅模块，不考虑白标/OEM，不做合同/财务系统。
+
+包含：
+
+- 用户管理（后台）
+- 套餐管理
+- 订阅开通、升级、续费、到期失效
+- Token发放与吊销
+- 额度校验与月用量统计
+- 线下收款或第三方支付链接确认
+
+不包含：
+
+- 白标/OEM
+- 分成系统
+- 合同审批流
+- 发票与财务对账系统
+
+---
+
+## 2. 角色
+
+- 超级管理员：配置套餐、处理升级、强制开通/停用
+- 运营：创建用户、确认支付、开通订阅、发放Token
+
+---
+
+## 3. 数据模型（最小集）
+
+## 3.1 用户表 `users`
+
+- `id`
+- `name`
+- `mobile`
+- `email`
+- `company_name`
+- `status`（active/disabled）
+
+
+## 3.2 套餐表 `plans`
+
+- `id`
+- `plan_code`（starter/pro/enterprise）
+- `plan_name`
+- `monthly_price`
+- `auth_fee`
+- `account_limit`
+- `active_user_limit`
+- `msg_quota`
+- `mass_quota`
+- `friend_quota`
+- `sns_quota`
+- `enabled_features`（json，具体功能点）
+- `status`（active/inactive）
+
+
+## 3.3 订阅表 `subscriptions`
+
+- `id`
+- `user_id`
+- `plan_id`
+- `status`（pending/active/expired/cancelled）
+- `start_time`
+- `end_time`
+- `renew_mode`（manual/auto）
+- `payment_channel`（offline/pay_link）
+- `payment_ref`（线下流水号或第三方订单号）
+
+
+## 3.4 Token表 `api_tokens`
+
+- `id`
+- `user_id`
+- `token_name`
+- `token_hash`（仅存哈希）
+- `status`（active/revoked/expired）
+- `expire_at`
+- `last_used_at`
+
+
+## 3.5 月用量表 `usage_monthly`
+
+- `id`
+- `user_id`
+- `plan_id`
+- `stat_month`（YYYY-MM）
+- `msg_count`
+- `mass_count`
+- `friend_count`
+- `sns_count`
+- `active_user_count`
+
+---
+
+## 4. 核心流程
+
+## 4.1 开通流程
+
+1. 运营创建用户  
+2. 选择套餐  
+3. 记录支付方式（线下/支付链接）  
+4. 支付确认后创建订阅（`active`）  
+5. 生成Token并展示一次明文  
+
+## 4.2 升级流程
+
+1. 选择新套餐  
+2. 确认补差支付  
+3. 更新订阅的 `plan_id` 与生效时间  
+4. 新套餐额度立即生效或次月生效（可配置）  
+
+## 4.3 续费流程
+
+1. 到期前提醒（D-7/D-3/D-1）  
+2. 支付确认后延长 `end_time`  
+3. 超期未续费则置为 `expired`  
+4. `expired` 状态禁止业务调用  
+
+## 4.4 Token鉴权流程（每次请求）
+
+1. 校验Token是否存在、是否过期、是否吊销  
+2. 查询用户是否有 `active` 订阅  
+3. 校验功能是否在 `enabled_features` 中  
+4. 校验本月用量是否超套餐额度  
+5. 通过则放行，失败返回明确错误码  
+
+---
+
+## 5. 功能需求
+
+## 5.1 用户管理
+
+- 新增/编辑/禁用用户
+- 查询用户当前订阅状态
+- 查询用户Token列表
+
+## 5.2 套餐管理
+
+- 新增/编辑套餐
+- 配置套餐价格、额度、功能点
+- 套餐上下线
+
+## 5.3 订阅管理
+
+- 开通订阅
+- 升级订阅
+- 续费订阅
+- 手动取消订阅
+- 到期自动失效任务
+
+## 5.4 Token管理
+
+- 创建Token（只显示一次明文）
+- 吊销Token
+- 设置Token有效期
+- 查询最后使用时间
+
+## 5.5 支付确认（轻量）
+
+- 线下收款：运营手动确认并录入 `payment_ref`
+- 支付链接：接收第三方回调后确认支付并开通
+
+---
+
+## 6. 错误码（建议）
+
+- `TOKEN_INVALID`：Token不存在
+- `TOKEN_EXPIRED`：Token已过期
+- `TOKEN_REVOKED`：Token已吊销
+- `SUBSCRIPTION_INACTIVE`：无有效订阅
+- `FEATURE_NOT_ALLOWED`：功能不在套餐内
+- `QUOTA_EXCEEDED`：本月额度已用尽
+
+---
+
+## 7. 管理端API（MVP）
+
+## 7.1 用户
+
+- `POST /admin/users`
+- `GET /admin/users`
+- `GET /admin/users/{id}`
+- `PUT /admin/users/{id}`
+- `POST /admin/users/{id}/disable`
+
+## 7.2 套餐
+
+- `POST /admin/plans`
+- `GET /admin/plans`
+- `PUT /admin/plans/{id}`
+- `POST /admin/plans/{id}/toggle`
+
+## 7.3 订阅
+
+- `POST /admin/subscriptions/open`
+- `POST /admin/subscriptions/upgrade`
+- `POST /admin/subscriptions/renew`
+- `POST /admin/subscriptions/cancel`
+- `GET /admin/subscriptions/{user_id}`
+
+## 7.4 Token
+
+- `POST /admin/tokens`
+- `GET /admin/tokens?user_id=`
+- `POST /admin/tokens/{id}/revoke`
+
+## 7.5 支付确认
+
+- `POST /admin/payments/confirm-offline`
+- `POST /admin/payments/confirm-link`
+
+---
+
+## 8. 定时任务
+
+- 订阅到期扫描：每天00:10执行，更新 `expired` 状态
+- 用量月结归档：每月1日00:30执行
+- 续费提醒任务：每天09:00执行
+
+---
+
+## 9. 验收标准
+
+- 可完成用户创建 -> 支付确认 -> 订阅开通 -> Token发放闭环
+- 可完成升级与续费并正确生效
+- 到期后能自动失效并阻断调用
+- 功能与额度限制生效，错误码准确
+- 支付链接回调或线下确认都可触发开通
+
+---
+
+## 10. 开发优先级
+
+P0：
+
+- 用户管理
+- 套餐管理
+- 订阅开通/升级/续费/失效
+- Token管理与鉴权
+
+P1：
+
+- 支付回调确认
+- 用量统计与额度限制
+- 到期提醒
+
+---
+# 后端管理平台需求说明（轻量核心版）
+
+## 1. 目标
+
+搭建最小可用后台，只做四件事：
+
+- 用户管理
+- Token管理
+- 套餐管理
+- 开通/升级流程管理
+
+不做（V1不开发）：
+
+- 合同管理
+- 财务系统集成
+- 分成系统
+- 复杂风控引擎
+
+收费方式：
+
+- 线下打款或在线支付链接（第三方支付页面）
+- 支付成功后由后台手动或回调触发开通
+
+---
+
+## 2. 核心角色
+
+- 超管：全局配置、套餐配置、手动开通
+- 运营：用户资料维护、Token发放、套餐变更
+- 客户（可选后续）：仅查看自己的Token和套餐状态
+
+---
+
+## 3. 核心数据模型
+
+## 3.1 用户
+
+`users`
+
+- id
+- name
+- mobile
+- email
+- company_name
+- status（active / disabled）
+- created_at
+- updated_at
+
+## 3.2 套餐
+
+`plans`
+
+- id
+- plan_code（starter/pro/enterprise）
+- plan_name
+- monthly_price
+- auth_fee
+- account_limit
+- active_user_limit
+- msg_quota
+- mass_quota
+- friend_quota
+- sns_quota
+- enabled_features（json数组，存具体功能点）
+- status（active / inactive）
+- created_at
+- updated_at
+
+## 3.3 用户套餐实例
+
+`user_subscriptions`
+
+- id
+- user_id
+- plan_id
+- start_time
+- end_time
+- status（pending/active/expired/cancelled）
+- payment_channel（offline / pay_link）
+- payment_ref（线下流水号或第三方订单号）
+- created_at
+- updated_at
+
+## 3.4 Token
+
+`api_tokens`
+
+- id
+- user_id
+- token_name
+- token_hash（仅存哈希）
+- status（active/revoked/expired）
+- plan_id（冗余，便于鉴权）
+- expire_at
+- last_used_at
+- created_at
+- updated_at
+
+## 3.5 用量（按月聚合）
+
+`usage_monthly`
+
+- id
+- user_id
+- plan_id
+- stat_month（YYYY-MM）
+- msg_count
+- mass_count
+- friend_count
+- sns_count
+- active_user_count
+- updated_at
+
+---
+
+## 4. 功能需求（MVP）
+
+## 4.1 用户管理
+
+- 新增/编辑/禁用用户
+- 查看用户当前套餐、到期时间、Token数量
+- 用户搜索（手机号、公司名、状态）
+
+## 4.2 套餐管理
+
+- 新增/编辑套餐
+- 配置套餐额度和功能点
+- 套餐上下线（active/inactive）
+- 查看套餐被多少用户使用
+
+## 4.3 Token管理
+
+- 为用户创建Token（仅展示一次明文）
+- Token吊销（revoke）
+- Token过期时间设置
+- Token使用记录查看（最后使用时间）
+
+鉴权规则（核心）：
+
+- 请求带Token
+- 校验Token状态与是否过期
+- 读取用户当前有效套餐
+- 判断功能是否在套餐内
+- 判断当月额度是否超限
+
+## 4.4 开通与升级流程
+
+### 开通流程
+
+1. 创建用户  
+2. 选择套餐  
+3. 记录支付方式（线下/支付链接）  
+4. 支付成功后开通订阅  
+5. 生成Token并交付客户
+
+### 升级流程
+
+1. 选择新套餐  
+2. 记录补差支付  
+3. 生效新套餐（立即或次月）  
+4. Token权限自动按新套餐生效
+
+### 续费流程
+
+1. 到期前提醒（D-7、D-3、D-1）  
+2. 支付成功后延长套餐周期  
+3. 未支付则到期失效（Token权限受限）
+
+---
+
+## 5. 支付与开通方式（轻量）
+
+支持两种方式：
+
+- `offline`：线下收款，后台手动录入流水号后开通
+- `pay_link`：调用第三方支付链接，回调成功后自动开通（或运营手动确认）
+
+V1要求：
+
+- 只保存支付结果与订单号
+- 不做复杂账单系统
+
+---
+
+## 6. 最小风控与安全
+
+- Token只存哈希，不存明文
+- 超管/运营所有关键操作写审计日志
+- 单用户默认Token数量上限（如5个）
+- 支持一键吊销全部Token
+- 超额度后返回明确错误码（不做复杂策略引擎）
+
+---
+
+## 7. 接口清单（管理端）
+
+## 7.1 用户
+
+- `POST /admin/users` 创建用户
+- `GET /admin/users` 用户列表
+- `GET /admin/users/{id}` 用户详情
+- `PUT /admin/users/{id}` 更新用户
+- `POST /admin/users/{id}/disable` 禁用用户
+
+## 7.2 套餐
+
+- `POST /admin/plans` 创建套餐
+- `GET /admin/plans` 套餐列表
+- `PUT /admin/plans/{id}` 更新套餐
+- `POST /admin/plans/{id}/toggle` 上下线套餐
+
+## 7.3 订阅
+
+- `POST /admin/subscriptions/open` 开通套餐
+- `POST /admin/subscriptions/upgrade` 升级套餐
+- `POST /admin/subscriptions/renew` 续费套餐
+- `GET /admin/subscriptions/{user_id}` 查询用户订阅
+
+## 7.4 Token
+
+- `POST /admin/tokens` 创建Token
+- `GET /admin/tokens?user_id=` Token列表
+- `POST /admin/tokens/{id}/revoke` 吊销Token
+
+## 7.5 支付记录
+
+- `POST /admin/payments/confirm-offline` 线下收款确认
+- `POST /admin/payments/confirm-link` 支付链接回调确认
+
+---
+
+## 8. 验收标准（上线即用）
+
+- 可创建用户并成功开通任一套餐
+- 可生成Token并用Token通过鉴权
+- 套餐功能和额度能正确限制请求
+- 可完成升级、续费、到期失效流程
+- 支付成功后可触发开通（手动或回调）
+
+---
+
+## 9. 开发优先级与周期建议
+
+P0（第1周）：
+
+- 用户管理
+- 套餐管理
+- 订阅开通
+- Token创建与鉴权
+
+P1（第2周）：
+
+- 升级/续费流程
+- 线下支付确认与支付链接回调
+- 月用量聚合与额度限制
+
+P2（第3周）：
+
+- 到期提醒
+- 审计日志页面
+- 基础运营看板
+
+---
+# 微信自动化平台后端管理需求说明（V1）
+
+## 1. 目标与范围
+
+建设一套后端管理平台，支撑 `方案.md` 与 `功能执行文档-报价方案配套.md` 的落地执行，覆盖：
+
+- 客户开通与版本管理
+- 功能开关与白名单控制
+- 额度管理与超量计费
+- 授权码生命周期管理
+- 账单、对账、分成结算
+- 风险控制与违规处置
+
+不在V1范围：
+
+- 客户前台门户（仅后台运营端）
+- 财务开票系统深度集成（先导出报表）
+
+---
+
+## 2. 角色与权限
+
+## 2.1 角色
+
+- 超级管理员：全局配置、价格策略、风控策略
+- 商务运营：客户开通、版本变更、合同与授权
+- 交付运营：功能开关、额度配置、验收记录
+- 财务：账单确认、对账、分成结算
+- 风控：告警处理、停用/解封、违规记录
+
+## 2.2 权限原则
+
+- 最小权限原则
+- 核心动作（停服、改价、授权升级）需二次确认与审计日志
+- 所有配置变更可追溯（操作者、时间、变更前后）
+
+---
+
+## 3. 核心业务对象（数据模型）
+
+## 3.1 客户与合同
+
+- `customer`：客户主体信息（公司/个人、联系人、状态）
+- `contract`：合同编号、版本、期限、签约类型、分成比例、补充条款
+- `service_instance`：客户服务实例（当前版本、生效时间、到期时间）
+
+## 3.2 版本与功能
+
+- `plan`：初级/高级/定制/白标
+- `feature_catalog`：功能目录（按具体功能点，不按抽象模块）
+- `plan_feature_map`：版本与功能映射（是否默认开通）
+- `feature_switch`：客户级功能开关（开/关、原因、操作者）
+
+## 3.3 额度与计费
+
+- `quota_policy`：版本默认额度（消息、群发、加好友、朋友圈、企业微信）
+- `customer_quota`：客户当前额度（可覆盖默认值）
+- `usage_daily` / `usage_monthly`：按客户、按计费项聚合用量
+- `price_policy`：单价策略（默认价、阶梯价、生效时间）
+- `billing_statement`：月账单（固定费、超量费、人头费、分成）
+
+## 3.4 授权与风控
+
+- `license_key`：授权码及状态（生成、激活、禁用、延期、删除）
+- `risk_rule`：风控规则（阈值、频率、异常模式）
+- `risk_event`：风险事件记录（级别、动作、处理结果）
+- `penalty_action`：处罚动作（限流、降级、停服、解封）
+
+---
+
+## 4. 功能模块需求
+
+## 4.1 客户开通中心
+
+功能点：
+
+- 创建客户档案
+- 绑定合同与版本
+- 设置账号上限、活跃终端用户上限
+- 初始化功能开关与额度
+- 生成开通确认单
+
+校验规则：
+
+- 无合同不得开通付费版本
+- 开通版本必须匹配授权级别
+- 对外收费客户必须配置分成策略
+
+---
+
+## 4.2 版本与功能管理
+
+功能点：
+
+- 维护版本基础配置（初级/高级/定制/白标）
+- 维护“具体功能点”目录与分组
+- 一键应用版本默认功能到客户
+- 客户级功能差异化调整（例外开关）
+
+关键要求：
+
+- 必须支持“包含/禁开”双清单导出（用于交付验收）
+- 功能变更需记录变更单号与审批人
+
+---
+
+## 4.3 额度与限流管理
+
+功能点：
+
+- 配置套餐默认额度
+- 按客户调整额度
+- 配置阈值告警（80%、100%、120%）
+- 配置超额后策略（仅计费 / 限流 / 禁止高风险动作）
+
+关键要求：
+
+- 日级、月级双维度统计
+- 支持手动补偿额度（需审计）
+
+---
+
+## 4.4 计费与账单中心
+
+功能点：
+
+- 固定费用：月费 + 授权费
+- 用量费用：按计费项单价计算
+- 用户规模费用：超过100后按1元/人/月（可配置）
+- 分成费用：按合同分成比例计算
+- 生成月账单、账单确认、导出对账单
+
+计算规则（V1）：
+
+- 月账单金额 = 固定费 + 超量费 + 人头费 + 分成费
+- 人头费基数 = max(活跃终端用户-100, 0)
+- 活跃终端用户按唯一ID月去重
+
+---
+
+## 4.5 授权码管理
+
+功能点：
+
+- 生成授权码（不同有效期）
+- 激活状态查询
+- 禁用、删除、延期
+- 授权状态同步任务
+
+关键要求：
+
+- 授权码与客户主体绑定
+- 禁用后相关能力按策略自动降级/停用
+
+---
+
+## 4.6 分成与结算管理
+
+功能点：
+
+- 设置客户分成比例（10%/15%/20%或合同自定义）
+- 录入/同步客户营收数据
+- 自动计算应结分成
+- 月度结算单导出
+
+关键要求：
+
+- 分成口径可配置（净营收/归因营收）
+- 允许人工复核后确认入账
+
+---
+
+## 4.7 风控与违规处置
+
+功能点：
+
+- 风控规则配置（频率阈值、异常行为模式）
+- 告警中心（低/中/高风险）
+- 自动处罚策略（限流、冻结高风险功能、停服）
+- 违规记录与解封流程
+
+关键要求：
+
+- 处罚动作必须可回溯
+- 高风险停服需双人审批（可配置）
+
+---
+
+## 4.8 审计与操作日志
+
+必须记录：
+
+- 谁在何时改了什么
+- 改前值/改后值
+- 操作来源（后台/任务/接口）
+- 关联客户、合同、账单编号
+
+---
+
+## 5. 核心流程（状态机）
+
+## 5.1 客户生命周期
+
+- `待签约 -> 已签约 -> 待开通 -> 已开通 -> 运行中 -> 欠费限制 -> 暂停服务 -> 终止`
+
+## 5.2 版本变更流程
+
+- 提交升级/降级申请 -> 商务审批 -> 配置预览 -> 生效执行 -> 通知客户 -> 留档
+
+## 5.3 月结流程
+
+- 月末汇总用量 -> 生成预账单 -> 财务复核 -> 账单确认 -> 推送客户 -> 回款核销
+
+---
+
+## 6. 配置字典（建议）
+
+## 6.1 计费项编码
+
+- `MSG_CALL`：消息调用
+- `MASS_TASK`：群发任务
+- `ADD_FRIEND`：加好友动作
+- `SNS_ACTION`：朋友圈动作
+- `QY_ACTION`：企业微信动作
+- `ACTIVE_USER`：活跃终端用户
+
+## 6.2 风险等级
+
+- `LOW`：告警
+- `MEDIUM`：限流或冻结部分能力
+- `HIGH`：停服并人工复核
+
+---
+
+## 7. 报表与看板需求
+
+## 7.1 运营看板
+
+- 在服客户数（按版本）
+- 当月升级/降级数量
+- 功能开关变更次数
+- 告警事件数量
+
+## 7.2 财务看板
+
+- MRR、ARR
+- 超量收入占比
+- 人头费收入占比
+- 分成收入占比
+- 回款率与逾期率
+
+## 7.3 客户视图
+
+- 客户当前版本与到期时间
+- 功能已开通清单
+- 本月额度、已用量、超量预估
+- 本月预估账单
+
+---
+
+## 8. 非功能性要求
+
+- 可用性：后台可用性 >= 99.9%
+- 审计性：关键操作100%留痕
+- 安全性：权限隔离、敏感操作二次确认
+- 性能：日汇总任务在60分钟内完成
+
+---
+
+## 9. MVP开发优先级
+
+P0（必须）：
+
+- 客户开通中心
+- 版本/功能开关管理
+- 额度管理
+- 用量统计
+- 账单生成
+- 授权码管理
+- 审计日志
+
+P1（次优先）：
+
+- 分成结算
+- 风控自动处置
+- 看板与报表
+
+P2（后续）：
+
+- 工作流审批引擎
+- 财务系统对接
+- 客户自助门户
+
+---
+
+## 10. 验收标准
+
+## 10.1 功能验收
+
+- 能按客户版本一键开通并生效
+- 能对单客户进行功能级开关控制
+- 能正确统计月用量并生成账单
+- 能处理授权码生成、禁用、延期、查询
+
+## 10.2 计费验收
+
+- 对同一客户可复算账单结果（误差为0）
+- 活跃终端用户去重规则正确
+- 超量计费与阶梯价计算正确
+
+## 10.3 风控验收
+
+- 触发阈值后自动生成告警
+- 可执行限流/停服动作并记录日志
+
+---
+
+## 11. 建议交付物
+
+- 后台原型图（客户、版本、计费、风控四大页面）
+- 数据库DDL初稿
+- 后台API清单（管理端）
+- 月账单计算任务说明
+- 上线回滚预案
+
+---

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

@@ -0,0 +1,162 @@
+# 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_tokens`（`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（示例） | 功能 |
+|------|------------------------------|------|
+| 用户列表/编辑 | `biz/user` | 表格 + 搜索 + 抽屉表单 |
+| 套餐列表/编辑 | `biz/plan` | JSON 功能点编辑器（简易 textarea 或 key-value） |
+| 订阅操作 | `biz/subscription` | 开通/升级/续费/取消向导或表单 |
+| Token | `biz/token` | 列表、创建（展示一次明文）、吊销 |
+| 支付确认 | `biz/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 在线文档对照开发。*