# PAYMENT_DOMAIN_DESIGN

最后更新: 2026-06-14

## 1. 设计目标

把 T12 中的支付、退款、回调、对账从“页面动作”提升为一等领域对象，避免把订单状态与支付状态混为一体。

## 2. 领域对象

### payment_order

- `payment_id`
- `order_id`
- `provider`
- `amount_cents`
- `status` (`pending/paying/paid/failed/refund_pending/refunded`)
- `checkout_token`
- `provider_trade_no`
- `created_at`
- `updated_at`

### payment_attempt

- 用于保留多次发起支付/重试尝试
- MVP 可先不单独建表，但设计必须保留扩展位

### refund

- `refund_id`
- `payment_id`
- `order_id`
- `amount_cents`
- `status`
- `reason`
- `created_at`

### reconciliation_job

- 用于后续对账任务
- MVP 允许只停留在设计层

## 3. 状态机拆分

### 订单状态

- `pending`
- `paid`
- `serving`
- `delivered`
- `completed`
- `refunded`

### 支付状态

- `pending`
- `paying`
- `paid`
- `failed`
- `refund_pending`
- `refunded`

原则：

- 订单状态不直接替代支付状态
- portal 展示阶段由订单 + 支付 + 交付物共同推导

## 4. 回调处理要求

回调验收至少要覆盖：

1. provider 签名校验
2. `payment_id / order_id` 对应关系校验
3. `amount_cents` 金额校验
4. 幂等处理（重复通知不能重复记账）
5. provider trade no 持久化
6. 异常记录与人工补偿入口

## 5. 当前实现状态

已存在：

- `data/payments/models.py`
- `data/payments/dao.py`
- `data/payments/service.py`
- `mock` / `alipay_sim` provider
- webhook 归一化处理

未完成：

- 真实 `alipay` provider
- refund 一等对象
- reconciliation job
- provider 级签名/证书联调

## 6. 决策

- MVP 只允许一个真实 provider 先闭环
- `alipay_sim` 只用于上线前模拟，不可冒充真实支付验收
- 真实支付上线前，必须先完成 provider doctor 与环境前置校验