Files
wechatWeb/_docs/后端管理平台需求说明.md
张成 aa8eaa6ccd init
2026-03-24 16:07:02 +08:00

841 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 后端管理平台需求说明(仅订阅模块)
## 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. 管理端APIMVP
## 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
- statusactive / disabled
- created_at
- updated_at
## 3.2 套餐
`plans`
- id
- plan_codestarter/pro/enterprise
- plan_name
- monthly_price
- auth_fee
- account_limit
- active_user_limit
- msg_quota
- mass_quota
- friend_quota
- sns_quota
- enabled_featuresjson数组存具体功能点
- statusactive / inactive
- created_at
- updated_at
## 3.3 用户套餐实例
`user_subscriptions`
- id
- user_id
- plan_id
- start_time
- end_time
- statuspending/active/expired/cancelled
- payment_channeloffline / pay_link
- payment_ref线下流水号或第三方订单号
- created_at
- updated_at
## 3.4 Token
`api_tokens`
- id
- user_id
- token_name
- token_hash仅存哈希
- statusactive/revoked/expired
- plan_id冗余便于鉴权
- expire_at
- last_used_at
- created_at
- updated_at
## 3.5 用量(按月聚合)
`usage_monthly`
- id
- user_id
- plan_id
- stat_monthYYYY-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清单管理端
- 月账单计算任务说明
- 上线回滚预案
---