# 计费与用量设计（Stripe + 硬配额）- ImageForge

目标：形成“套餐/订阅/用量/发票/支付/风控”可落地的闭环，为后续实现提供清晰边界与数据模型依据。

---

## 1. 计费模型（已确认）

已确认口径：
- 支付渠道：**Stripe**
- 超额策略：**硬配额**（超过当期额度返回 `QUOTA_EXCEEDED` / HTTP `402`）
- 配额周期：**按订阅周期**（Stripe `current_period_start` ~ `current_period_end`），不是自然月

### 1.0 周期定义（统一口径）
为避免前后端与账本口径不一致，本项目将“周期”分为三类：
- **Pro/Business（付费）**：按 Stripe 订阅周期（`current_period_start` ~ `current_period_end`）。
- **Free（未订阅）**：按自然月（UTC+8）重置，用于展示“本月已用/剩余/重置时间”。
- **匿名试用**：按自然日（UTC+8）重置，仅用于网站试用（默认每日 10 次）。

### 1.1 计量单位
**compression_unit**：每成功压缩 1 个输出文件计 1 单位。

规则：
- 同一任务中失败的文件不计费。
- 同一请求重试若携带相同 `Idempotency-Key`，不重复计费（返回相同结果）。
- 输出格式转换（png->webp 等）不额外加价（首期），后续可按“高级功能”计价。

### 1.2 套餐（Plan）
套餐是“功能 + 配额 + 限制”的集合，建议存为可配置（DB 或配置中心）。

最小字段：
- `included_units_per_period`：周期含量（对付费为订阅周期；对 Free 为自然月）。
- `max_file_size_mb` / `max_files_per_batch` / `concurrency_limit`
- `retention_days`：结果保留期。
- `features`：例如 webhook、团队、IP 白名单等开关。

### 1.3 订阅（Subscription）
采用“月度订阅 + 含量（硬配额）”：
- 用户在每个订阅周期获得固定含量（`included_units_per_period`）。
- 超出含量：直接拒绝（`QUOTA_EXCEEDED` / HTTP `402`）。

---

## 2. 用量计算与配额扣减（Metering）

### 2.1 何时扣减
- **成功生成输出**时扣减（以文件粒度）。
- 对于异步任务：Worker 完成文件压缩后写入用量事件；API/前端通过任务查询看到实时用量。

### 2.2 幂等与去重
需要两层保护：
1) **请求幂等**：`Idempotency-Key` 防止重复创建任务/重复扣减。
2) **用量幂等**：每个输出文件生成唯一 `usage_event_id`（或以 `task_file_id` 唯一）确保不会重复入账。

### 2.3 用量数据结构（建议）
- `usage_events`：明细账本（append-only），用于可追溯与对账。
  - `user_id` / `api_key_id` / `source`（web/api）
  - `task_id` / `task_file_id`
  - `units`（通常为 1）
  - `bytes_in` / `bytes_out` / `format_in` / `format_out`
  - `occurred_at`
- `usage_periods`：按订阅周期聚合（加速配额判断）。
  - `user_id` + `period_start` + `period_end` 唯一
  - `used_units`、`bytes_in`、`bytes_out` 等

配额判断：
- 写入 `usage_events` 前先检查本周期 `used_units` 是否已达 `included_units_per_period`（并发场景需原子性：事务/锁/原子计数）。
- 失败时返回 `QUOTA_EXCEEDED`，并在响应中附带“已用/上限/重置时间”。

### 2.4 并发安全的扣减算法（推荐）
目标：在高并发下也不能“超扣”。

推荐做法（Worker 侧每成功文件 1 次扣减）：
- 先拿到当期 `included_units`（来自 plan）。
- 用单条 SQL 做“条件更新”，只有未超额时才 +1：

```sql
UPDATE usage_periods
SET used_units = used_units + 1,
    bytes_in   = bytes_in + $1,
    bytes_out  = bytes_out + $2,
    updated_at = NOW()
WHERE user_id = $3
  AND period_start = $4
  AND period_end = $5
  AND used_units + 1 <= $6
RETURNING used_units;
```

如果 `RETURNING` 无行（0 行更新），表示额度已耗尽：该文件应标记为 `QUOTA_EXCEEDED`，并丢弃输出（不返回/不落盘/不入账）。

> 说明：为保持“成功才扣减”的口径，2.4 默认按“成功后尝试扣减”实现；在配额临界点可能出现“先压缩、后发现额度不足”的少量无效计算。若要完全避免，可升级为“预留额度 + 失败回滚”的方案（复杂度更高，后续可做 V1+ 优化）。

### 2.5 批量任务与配额（硬配额）
为尽量减少“上传后才发现额度不足”的体验问题，建议双层策略：
- **创建任务前预检**：`remaining_units < files_count` 时直接返回 `402 QUOTA_EXCEEDED`（不创建任务）。
- **扣减时最终校验**：写入账本/聚合时仍按 2.4 做原子扣减，防止并发竞态导致超额。

说明：
- 批量任务的计量仍以“成功文件数”为准；失败文件（含 `QUOTA_EXCEEDED`）不计费。
- 前端建议在上传前调用 `GET /billing/usage`（登录）或读取配额头（API）做本地提示/拦截。

---

## 3. 订阅生命周期（状态机）

### 3.1 状态
建议：
- `trialing`：试用中（可选）
- `active`：正常
- `past_due`：欠费（支付失败）
- `paused`：暂停（可选）
- `canceled`：已取消
- `incomplete`：创建未完成（例如支付页未完成）

### 3.2 关键动作
- 升级/降级套餐：下周期生效（首期建议），避免按天结算复杂度。
- 取消订阅：`cancel_at_period_end=true`，到期生效；到期后自动降级到 Free（不续费）。

---

## 4. 支付集成（Stripe）

### 4.1 核心对象映射（建议）
- `users.billing_customer_id` ↔ Stripe `customer.id`
- `plans` ↔ Stripe `product/price`（建议每个 plan 对应一个 Stripe `price`）
- `subscriptions.provider_subscription_id` ↔ Stripe `subscription.id`
- `invoices.provider_invoice_id` ↔ Stripe `invoice.id`
- `payments.provider_payment_id` ↔ Stripe `payment_intent.id`（或 charge id，按实现选）

### 4.2 Checkout / Portal
- Checkout：后端创建 Stripe Checkout Session，前端跳转 `checkout_url`。
- Portal：后端创建 Stripe Billing Portal Session，前端跳转管理支付方式/取消订阅。

### 4.3 Stripe Webhook（商用必须）
要求：
- **验签**：使用 `STRIPE_WEBHOOK_SECRET` 校验 `Stripe-Signature`。
- **事件幂等**：按 `provider_event_id` 去重（落库 `webhook_events`）。
- **乱序容忍**：以 Stripe 事件时间 + 当前 DB 状态做“只前进不回退”更新。
- **可重放**：保存原始 payload（脱敏）用于排查。

建议首期处理的事件（示例）：
- `checkout.session.completed`
- `customer.subscription.created`
- `customer.subscription.updated`
- `customer.subscription.deleted`
- `invoice.paid`
- `invoice.payment_failed`

---

## 5. 发票与对账

### 5.1 发票（Invoice）
发票用于：
- 向用户展示本期费用、税务信息（后续）、支付状态。
- 与支付记录/订阅周期关联。

最小字段：
- `invoice_number`（展示用）
- `currency`、`total_amount`
- `status`：draft/open/paid/void/uncollectible（可简化）
- `period_start` / `period_end`
- `paid_at`

### 5.2 对账原则
- 以 `usage_events` 为最终真相（source of truth）。
- 以 `invoice` 为结算结果（面向用户）。
- 管理后台可以按用户/周期拉取用量明细，支持导出 CSV。

---

## 6. 风控策略（与计费强相关）

### 6.1 防盗刷
- API Key 支持：权限范围、速率限制、（可选）IP 白名单、（可选）域名白名单（仅对 Web 场景有效）。
- 异常检测：短时间内用量突增、来自异常国家/ASN、重复失败率高。

### 6.2 欠费与滥用处理
- 欠费（past_due）：建议限制创建新任务，并在 UI 引导用户去 Portal 完成支付。
- 严重滥用：冻结用户/API Key，并记录审计日志。

---

## 7. 需要在文档中保持一致的“最终口径”

上线前必须定稿并在 `docs/api.md`、`docs/database.md`、`docs/ui.md` 同步：
- 套餐表（默认配额值）。
- 配额刷新周期（按订阅周期）。
- 超额策略（硬配额 / HTTP 402）。
- 匿名试用是否开放、开放到什么程度。