# 后端管理平台需求说明（仅订阅模块）

## 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清单（管理端）
- 月账单计算任务说明
- 上线回滚预案

---
