# 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`：

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

## 8.1 方案管理

### 8.1.1 创建方案

- `POST /api/fee/plan/create`

请求示例：

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

响应示例：

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

### 8.1.2 保存收费项

- `POST /api/fee/plan/item/save`

请求示例：

```json
{
  "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`

请求示例：

```json
{
  "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`

请求示例：

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

### 8.2.2 切换计费模式

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

请求示例：

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

### 8.2.3 切换租户类型

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

请求示例：

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

---

## 8.3 钱包

### 8.3.1 查询钱包

- `GET /api/fee/wallet/{tenantId}`

响应示例：

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

### 8.3.2 充值

- `POST /api/fee/wallet/recharge`

请求示例：

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

---

## 8.4 用量上报

### 8.4.1 上报并计费

- `POST /api/fee/usage/report`

请求示例：

```json
{
  "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
  }
}
```

响应示例：

```json
{
  "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`

响应示例：

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