feat: 新增套餐使用记录实付金额快照字段 paid_amount
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 7m19s

- 新增迁移 000129:tb_package_usage 添加 paid_amount BIGINT 字段,存量数据通过 JOIN tb_order 回填
- PackageUsage Model 新增 PaidAmount *int64 字段
- 4 个写入点(order service 主套餐/加油包、auto_purchase 主套餐/加油包)赋值 order.ActualPaidAmount
- AssetPackageResponse DTO 新增 paid_amount 字段
- GetCurrentPackage / GetPackages 填充 paid_amount,接口直接返回购买价格无需 JOIN 订单表
This commit is contained in:
2026-04-18 10:19:21 +08:00
parent 4b8784d5e7
commit 2b3a9cb33f
15 changed files with 391 additions and 5 deletions

View File

@@ -108,22 +108,28 @@
- `activated_at`: 生效时间
- `expires_at`: 过期时间
- `status`: 套餐状态0-待生效 1-生效中 2-已用完 3-已过期 4-已失效)
- `paid_amount`: 购买时实付金额(分),线下支付或无订单分配时为 null
#### Scenario: 查询卡的套餐历史
- **WHEN** 管理员调用 `GET /api/admin/assets/card/123/packages`,该卡有 3 条套餐记录(含 1 条已失效)
- **THEN** 系统返回全部 3 条记录,按创建时间倒序排列
- **THEN** 系统返回全部 3 条记录,按创建时间倒序排列,每条记录含 `paid_amount` 字段
#### Scenario: 查询设备的套餐历史
- **WHEN** 管理员调用 `GET /api/admin/assets/device/456/packages`
- **THEN** 系统返回该设备 device_id 下的所有套餐记录
- **THEN** 系统返回该设备 device_id 下的所有套餐记录,含 `paid_amount` 字段
#### Scenario: 资产无套餐记录
- **WHEN** 管理员查询一张从未购买过套餐的卡
- **THEN** 系统返回空数组,不报错
#### Scenario: 线下支付套餐的 paid_amount 为 null
- **WHEN** 管理员查询一张通过线下支付购买套餐的卡
- **THEN** 对应套餐记录的 `paid_amount` 字段缺省omitempty不展示
---
### Requirement: 当前主套餐详情查询
@@ -138,12 +144,13 @@
**响应字段**:
- 完整套餐信息(同套餐历史列表中的单条记录字段)
- `paid_amount`: 购买时实付金额(分),线下支付或无订单分配时为 null
- 当无生效主套餐时,返回 HTTP 404
#### Scenario: 返回当前主套餐
#### Scenario: 返回当前主套餐(含实付金额)
- **WHEN** 管理员调用 `GET /api/admin/assets/card/123/current-package`,该卡有 1 个生效主套餐和 1 个加油包
- **THEN** 系统只返回主套餐信息,不包含加油包
- **WHEN** 管理员调用 `GET /api/admin/assets/card/123/current-package`,该卡有 1 个生效主套餐和 1 个加油包,主套餐 `paid_amount = 9900`
- **THEN** 系统只返回主套餐信息,响应中包含 `paid_amount: 9900`不包含加油包
#### Scenario: 无当前生效主套餐

View File

@@ -0,0 +1,50 @@
# 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` 相互独立