# package-usage-paid-amount-snapshot Specification

## Purpose

在套餐使用记录（`tb_package_usage`）创建时，快照购买该套餐对应订单的实付金额，使资产套餐接口能直接返回购买价格，无需 JOIN 订单表。

## Requirements

### Requirement: 套餐使用记录快照实付金额

系统 SHALL 在创建 `PackageUsage` 记录时，将购买该套餐对应订单的实付金额（`tb_order.actual_paid_amount`）快照至 `tb_package_usage.paid_amount` 字段，单位为分（人民币）。

**字段规范**：
- 数据库字段：`paid_amount BIGINT NULLABLE`
- Go 字段：`PaidAmount *int64`（单位：分）
- 赋值来源：`order.ActualPaidAmount`，直接赋值，不转换
- 为 null 的情况：线下支付（无实际收款）或无订单关联的企业分配套餐

**覆盖范围（所有 PackageUsage 写入点）**：
- `internal/service/order/service.go` `activateMainPackage()`
- `internal/service/order/service.go` `activateAddonPackage()`
- `internal/task/auto_purchase.go` `activateMainPackage()`
- `internal/task/auto_purchase.go` `activateAddonPackage()`

**存量数据**：通过迁移 SQL `UPDATE tb_package_usage SET paid_amount = o.actual_paid_amount FROM tb_order o WHERE pu.order_id = o.id AND pu.order_id != 0` 回填，`order_id = 0` 的记录保持 null。

#### Scenario: 钱包支付套餐激活时快照实付金额

- **WHEN** 用户以钱包支付购买套餐，订单 `actual_paid_amount = 9900`（分）
- **THEN** 激活生成的 `PackageUsage.paid_amount = 9900`

#### Scenario: 微信支付回调后激活套餐时快照实付金额

- **WHEN** 微信支付回调触发 `HandlePaymentCallback`，`actual_paid_amount = 19900`，随后调用 `activatePackage`
- **THEN** 生成的 `PackageUsage.paid_amount = 19900`

#### Scenario: 线下支付套餐激活时 paid_amount 为 null

- **WHEN** 管理员以线下支付方式为客户激活套餐，`order.actual_paid_amount = nil`
- **THEN** `PackageUsage.paid_amount = nil`，接口响应中 `paid_amount` 字段缺省（omitempty）

#### Scenario: 自动购包任务激活套餐时快照实付金额

- **WHEN** C 端钱包充值触发 `auto_purchase` 任务，自动购买套餐，扣款 `paidAmount = 5900`
- **THEN** 激活生成的 `PackageUsage.paid_amount = 5900`

#### Scenario: 加油包激活时独立快照实付金额

- **WHEN** 用户购买加油包，对应订单 `actual_paid_amount = 2900`
- **THEN** 加油包 `PackageUsage.paid_amount = 2900`，与主套餐的 `paid_amount` 相互独立