ylrz_saas_his_scrm/docs/SaaS计费模块产品文档.md

SaaS计费模块产品文档

1. 文档信息

• 模块名称：SaaS 多租户计费模块
• 适用系统：ylrz_saas_his_scrm
• 当前状态：已完成核心计费闭环改造（方案、绑定、钱包、事件计费、明细、账单）
• 文档用途：产品、研发、测试、运营统一对齐

---

2. 产品目标

2.1 目标

构建一套可在 SaaS 场景下稳定运行的统一计费能力，支持：

1. 平台统一维护计费方案；
2. 租户按绑定方案自动计费；
3. 支持预付费/后付费；
4. 全链路可追溯（事件 -> 明细 -> 钱包流水 -> 账单）。

2.2 业务价值

• 支撑商业化收费与多租户精细化运营；
• 平台可审计全部租户费用情况；
• 租户可自助查看自身费用明细，降低客服压力。

---

3. 角色与权限模型

3.1 平台总账号（Admin）

• 配置并发布计费方案；
• 绑定租户计费方案；
• 查看全部租户明细（可按租户筛选）；
• 生成账单。

权限点：

• fee:billing:admin:list

3.2 租户账号（Tenant）

• 查看“我的费用明细”；
• 查询钱包、发起充值（按产品授权控制）。

权限点：

• fee:billing:tenant:list

---

4. 收费项设计

当前实现的收费项如下：

1. FLOW：流量计费
   
   • 预付费：按阶梯价格（基于累计预存金额）；
   • 后付费：按 FLOW_POSTPAID 单价。
2. CALL：通话计费
   
   • 子类型：CALL_OUT、CALL_IN；
   • 不满一分钟按一分钟；
   • AI 外呼在通话费基础上叠加 AI_CALL。
3. TOKEN_SOP：SOP Token 计费。
4. TOKEN_AI_REPLY：AI 回复 Token 计费。
5. ADD_WECHAT：按加微次数计费。
6. OPEN_ACCOUNT：开户费
   
   • AI 租户：OPEN_ACCOUNT_AI；
   • 非 AI 租户：OPEN_ACCOUNT_NON_AI。

---

5. 核心业务规则

5.1 方案规则

1. 方案唯一键：planCode + version；
2. 仅 PUBLISHED 状态方案可用于计费；
3. 支持多版本并行，租户绑定到具体版本。

5.2 租户绑定规则

租户绑定项：

• tenantType（AI / NON_AI）
• billingMode（PREPAID / POSTPAID）
• planCode
• planVersion

未绑定方案时禁止执行计费。

5.3 幂等规则

usage_event.event_id 作为幂等键：
重复事件上报不重复计费。

5.4 钱包规则

• 预付费：实时扣减余额并写流水；
• 后付费：仅记录明细，后续账单结算。

5.5 账单规则

1. 仅聚合未入账明细（statement_id is null）；
2. 账单项按 event_type 聚合；
3. 生成后回填明细 statement_id，避免重复出账。

---

6. 端到端流程

6.1 方案配置流程（平台）

1. 创建方案草稿；
2. 配置收费项；
3. 配置流量阶梯；
4. 发布方案；
5. 绑定租户。

6.2 事件计费流程（系统）

1. 业务侧上报 usage_event；
2. 幂等校验（eventId）；
3. 加载租户绑定与方案配置；
4. 计算金额并写 billing_detail；
5. 若预付费则扣钱包并写 tenant_wallet_txn；
6. 返回计费结果。

6.3 对账出账流程（平台）

1. 查询明细；
2. 指定时间区间生成账单；
3. 账单聚合 + 明细挂账；
4. 进入后续财务流程（支付/核销可扩展）。

---

7. 页面设计（前端）

已按“两页面模型”实现：

1. 总账号页：saas/billingAdmin/index
   
   • 查看所有租户费用明细；
   • 支持按租户筛选。
2. 租户页：saas/billingTenant/index
   
   • 仅查看当前登录租户的费用明细；
   • 不允许手工传 tenantId。

---

8. 接口清单与示例

以下示例统一返回结构基于项目常见 R：

{
  "code": 200,
  "msg": "操作成功",
  "data": {},
  "rows": []
}

8.1 方案管理

8.1.1 创建方案

• POST /api/fee/plan/create

请求示例：

{
  "planCode": "STANDARD",
  "planName": "标准方案",
  "version": 1,
  "remark": "默认标准方案"
}

响应示例：

{
  "code": 200,
  "msg": "创建成功"
}

8.1.2 保存收费项

• POST /api/fee/plan/item/save

请求示例：

{
  "planCode": "STANDARD",
  "version": 1,
  "items": [
    {
      "itemCode": "FLOW_POSTPAID",
      "unit": "KB",
      "unitPrice": 0.2,
      "tokenUnit": 100000,
      "minChargeUnit": 1,
      "enabled": 1
    },
    {
      "itemCode": "CALL_OUT",
      "unit": "MIN",
      "unitPrice": 0.3,
      "enabled": 1
    }
  ]
}

8.1.3 保存流量阶梯

• POST /api/fee/plan/flow-tier/save

请求示例：

{
  "planCode": "STANDARD",
  "version": 1,
  "tiers": [
    {
      "minPrepayAmount": 0,
      "maxPrepayAmount": 100000,
      "unitPrice": 0.1,
      "sortNo": 1
    },
    {
      "minPrepayAmount": 100000,
      "maxPrepayAmount": 200000,
      "unitPrice": 0.08,
      "sortNo": 2
    }
  ]
}

8.1.4 发布方案

• POST /api/fee/plan/publish?planCode=STANDARD&version=1

---

8.2 租户绑定

8.2.1 绑定方案

• POST /api/fee/tenant/bind-plan

请求示例：

{
  "tenantId": 1001,
  "tenantType": "NON_AI",
  "billingMode": "PREPAID",
  "planCode": "STANDARD",
  "planVersion": 1
}

8.2.2 切换计费模式

• POST /api/fee/tenant/change-billing-mode

请求示例：

{
  "tenantId": 1001,
  "billingMode": "POSTPAID"
}

8.2.3 切换租户类型

• POST /api/fee/tenant/change-type

请求示例：

{
  "tenantId": 1001,
  "tenantType": "AI"
}

---

8.3 钱包

8.3.1 查询钱包

• GET /api/fee/wallet/{tenantId}

响应示例：

{
  "code": 200,
  "data": {
    "tenantId": 1001,
    "balanceAmount": 12345.67,
    "totalRecharge": 50000,
    "totalCost": 37654.33
  }
}

8.3.2 充值

• POST /api/fee/wallet/recharge

请求示例：

{
  "tenantId": 1001,
  "amount": 10000,
  "bizNo": "RC202604210001",
  "remark": "线下转账充值"
}

---

8.4 用量上报

8.4.1 上报并计费

• POST /api/fee/usage/report

请求示例：

{
  "eventId": "EVT_20260421_0001",
  "tenantId": 1001,
  "eventType": "CALL",
  "subType": "CALL_OUT",
  "bizId": "ORDER_001",
  "usageValue": 125,
  "usageUnit": "SECOND",
  "occurredAt": "2026-04-21 15:30:00",
  "extJson": {
    "isAiCall": true
  }
}

响应示例：

{
  "code": 200,
  "data": {
    "eventId": "EVT_20260421_0001",
    "charged": true,
    "amount": 2.4,
    "message": "计费成功"
  }
}

---

8.5 明细与账单

8.5.1 平台查询明细（可看全租户）

• GET /api/fee/billing/detail/list
• 参数：tenantId（可选）

示例：

• GET /api/fee/billing/detail/list（全部）
• GET /api/fee/billing/detail/list?tenantId=1001（指定租户）

8.5.2 租户查询我的明细

• GET /api/fee/billing/detail/my
• 不接收 tenantId，由后端从登录态获取

8.5.3 生成账单

• POST /api/fee/statement/generate
• 参数：tenantId、periodType、periodStart、periodEnd

示例：

POST /api/fee/statement/generate?tenantId=1001&periodType=MONTH&periodStart=2026-04-01%2000:00:00&periodEnd=2026-04-30%2023:59:59

响应示例：

{
  "code": 200,
  "data": {
    "statementId": 88,
    "statementNo": "ST1713693258123",
    "periodType": "MONTH",
    "periodStart": "2026-04-01 00:00:00",
    "periodEnd": "2026-04-30 23:59:59",
    "totalAmount": 1299.35
  }
}

---

9. 数据模型

9.1 方案

• fee_plan
• fee_plan_item
• fee_plan_flow_tier

9.2 租户绑定

• tenant_info（新增计费相关字段）
  • tenant_type
  • billing_mode
  • fee_plan_code
  • fee_plan_version

9.3 钱包

• tenant_wallet
• tenant_wallet_txn

9.4 计费主链路

• usage_event
• billing_detail
• billing_statement
• billing_statement_item

---

10. 安全与数据隔离

1. 明细查询按权限点分流；
2. 租户端明细接口不接受 tenantId；
3. 统一通过登录态解析租户 ID；
4. 防止前端参数篡改导致跨租户越权查询。

---

11. 监控与审计建议

1. 监控 usage_event 入库量与重复率；
2. 监控钱包扣费失败告警；
3. 监控账单生成耗时和失败率；
4. 保留事件、明细、流水的关联查询能力，支持财务审计。

---

12. 验收标准（UAT）

1. 方案创建/配置/发布可用；
2. 租户绑定后可正常计费；
3. 重复事件不会重复扣费；
4. 预付费会扣钱包并生成流水；
5. 总账号可看全租户明细；
6. 租户仅能看本人租户明细；
7. 账单生成后明细正确挂账。

---

13. 版本演进建议

1. 增加账单支付、核销、坏账流程；
2. 增加账单列表与账单详情 API；
3. 增加按天/月统计报表与导出；
4. 用量上报支持 MQ 异步削峰；
5. 引入欠费阈值与停服策略。