# CDR Minimal Billing Runbook

> 任务：S23 - 最小计费与余额扣减  
> 完成时间：2026-06-21 19:55 +08:00

## 1. 目标

S23 在 S22 的 Redis Stream 消费基础上完成最小计费闭环：

- 成功通话 CDR 写入 `raw_cdrs` 和 `rated_cdrs`。
- 按周期秒数和周期费率计算费用。
- 扣减客户余额，并写入不可变客户余额流水。
- 同一 `event_id` 或同一 `raw_cdr_id` 不重复扣费。

当前系统尚未建立客户侧费率表，因此 S23 使用落地网关的 `billingCycleSec` 和 `cycleRate` 同时作为供应商成本和临时客户费用，`grossProfit` 为 `0.000000`。正式客户费率和利润计算留给后续计费版本。

## 2. 计费规则

`apps/worker-cdr/src/billing.ts` 提供周期计费函数：

```text
cycles = ceil(duration_sec / billing_cycle_sec)
bill_sec = cycles * billing_cycle_sec
amount = cycles * cycle_rate
```

约束：

- `duration_sec` 必须为非负整数。
- `billing_cycle_sec` 必须为 1 到 60 的整数。
- 金额统一保留 6 位小数。
- `sip_code` 为 `2xx` 且 `duration_sec > 0` 时才进入计费。

失败 CDR、零时长 CDR、缺少客户或落地网关 ID 的 CDR 只写 `raw_cdrs`，`ratingStatus` 标记为 `SKIPPED`，不扣余额。

## 3. 写库与幂等

`apps/worker-cdr/src/rating.ts` 的 `CdrRatingService` 在单个数据库事务内处理：

1. 按 `raw_cdrs.event_id` 查询是否已处理。
2. 新建 `raw_cdrs`。
3. 锁定客户余额行：`SELECT ... FOR UPDATE`。
4. 读取落地网关周期费率。
5. 新建 `rated_cdrs`。
6. 新建一条负数 `customer_recharges` 作为扣费流水。
7. 更新 `customers.balance`。
8. 将 `raw_cdrs.ratingStatus` 标记为 `RATED`。

扣费流水约定：

| 字段 | 值 |
| --- | --- |
| `amount` | 负数费用 |
| `idempotencyKey` | `cdr:<event_id>` |
| `remark` | `CDR_CHARGE:<raw_cdr_id>` |
| `createdBy` | `worker-cdr` |

数据库唯一约束共同防止重复扣费：

- `raw_cdrs.event_id`
- `rated_cdrs.raw_cdr_id`
- `customer_recharges.idempotencyKey`

## 4. Worker 行为

`apps/worker-cdr/src/main.ts` 现在连接 Redis 和 MySQL：

1. 从 `stream:cdr_payload` 的 `billing-workers` Consumer Group 读取 CDR。
2. 解析成功后调用 `CdrRatingService.rate(event)`。
3. 处理成功或重复消息后 ACK Redis 消息。
4. 处理异常时沿用 S22 死信机制写入 `stream:cdr_deadletter`。

必需环境变量：

```text
REDIS_URL
DATABASE_URL
```

可选环境变量：

```text
CDR_CONSUMER_NAME
CDR_BLOCK_MS
CDR_BATCH_SIZE
CDR_PENDING_IDLE_MS
LISGLOSIPS_LOG_LEVEL
```

## 5. 验证结果

- `corepack pnpm@10.33.0 exec vitest run apps/worker-cdr/src/rating.spec.ts` 通过，3 条测试覆盖周期计费、成功 CDR 扣费幂等、失败 CDR 不扣费。
- `corepack pnpm@10.33.0 --filter @lisglosips/worker-cdr build` 通过。
- `corepack pnpm@10.33.0 typecheck` 通过。
- `corepack pnpm@10.33.0 lint` 通过。
- `corepack pnpm@10.33.0 build` 通过。

本次未连接 B 执行服务部署或真实库写入验证，因为 B sudo 凭据仍未通过校验。S23 仅完成本地代码闭环和构建验收。

## 6. 回滚

代码回滚：

- 恢复 `apps/worker-cdr/src/main.ts` 到 S22 只记录 CDR 的版本。
- 删除或恢复 `apps/worker-cdr/src/billing.ts`、`apps/worker-cdr/src/rating.ts`、`apps/worker-cdr/src/rating.spec.ts`。
- 恢复 `apps/worker-cdr/package.json` 和 `apps/worker-cdr/tsconfig.json`。
- 重新执行 `corepack pnpm@10.33.0 build`。

数据回滚：

- S23 未执行真实数据库写入验证，无需清理远端数据。
- 若后续环境已运行 worker 并产生扣费数据，回滚前必须先停止 worker，记录待回滚的 `event_id`、`raw_cdr_id`、`rated_cdr_id` 和客户流水；不得直接删除余额流水，应通过受控反向流水或备份恢复方案处理。