init

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