Etusivu Tutki Apua
Kirjaudu sisään
txl
/
ylrz_saas_his_scrm
1
0
Fork 0
Tiedostot Ongelmat 0 Pull-pyynnöt 0 Wiki
Branch: master
Branchit Tagit
ylrz_saas_hi...
/
docs
/
SaaS计费模块产品文档.md

SaaS计费模块产品文档.md 8.7 KB
Pysyvä linkki Historia Raaka

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. 引入欠费阈值与停服策略。