修复订单金额落库不对的问题
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 8m17s

This commit is contained in:
Break
2026-06-01 11:21:29 +08:00
parent 6c8352491c
commit 944526d9ef
16 changed files with 454 additions and 37 deletions

View File

@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-06-01

View File

@@ -0,0 +1,77 @@
## Context
当前 `tb_order.total_amount` 在后台代购/钱包支付场景被覆盖为成本价,导致:
1. C 端订单列表/详情展示成本价(甚至 0 元)
2. `tb_package_usage.paid_amount` 快照的是成本价,资产套餐接口对所有后台账号一视同仁地暴露成本价
字段语义混乱的根源:`total_amount` 在 admin order service 中被 `buyerTotalCost` 覆盖,`retailTotalAmount` 计算出来后被丢弃。`actual_paid_amount` 本应是成本价,但 `total_amount` 也是成本价,两者语义重叠。
涉及模块:`internal/service/order``internal/service/client_order``internal/service/asset``internal/task``internal/model``internal/handler/admin`
## Goals / Non-Goals
**Goals:**
- `Order.TotalAmount` 始终 = 零售价客户面值C 端和后台均可安全展示
- `Order.ActualPaidAmount` = 实际支付成本价,钱包扣款以此为准
- `OrderItem.UnitPrice` = 零售单价,新增 `CostPrice` 字段存成本单价
- `PackageUsage.RetailAmount` 快照零售价,`PaidAmount` 继续快照成本价
- 资产套餐接口按调用方账号类型过滤:非平台账号不返回 `paid_amount`
**Non-Goals:**
- 不修改 C 端下单流程C 端本来就用零售价,无需改动)
- 不修改佣金计算逻辑(佣金基于 `SellerCostPrice`,不受此次影响)
- 不修改退款逻辑(退款金额基于 `ActualPaidAmount`,语义已正确)
- 不重命名 `PaidAmount` 字段(保持向后兼容)
## Decisions
### 决策 1`TotalAmount` 始终存零售价,`ActualPaidAmount` 存成本价
**选择**admin order service 中 `totalAmount` 始终赋值 `retailTotalAmount`,不再被 `buyerTotalCost` 覆盖;成本价只写入 `ActualPaidAmount`
**理由**`TotalAmount` 是订单的"面值",对客户可见;`ActualPaidAmount` 是"实付",是内部财务字段。两者语义本来就应该分离,当前代码是历史遗留的语义混用。
**钱包扣款影响**`createOrderWithWalletPayment` 目前用 `order.TotalAmount` 扣款,改为用 `order.ActualPaidAmount`。这是正确的——代理扣的是成本价,不是零售价。
**替代方案**:新增独立的 `RetailAmount` 字段存零售价,`TotalAmount` 保持现状。被否决,因为 `TotalAmount` 的字段名本身就暗示"订单总金额",应该是客户看到的面值,改语义比加字段更干净。
### 决策 2`OrderItem` 新增 `CostPrice` 字段
**选择**`tb_order_item` 新增 `cost_price BIGINT NOT NULL DEFAULT 0``UnitPrice` 改为存零售单价。
**理由**详情页需要展示每个套餐的单价C 端看零售价,后台平台账号可能需要看成本价做对账。两个字段各司其职,不互相覆盖。
**替代方案**:只在 order 级别存成本价(`SellerCostPrice` 已有item 级别不存。被否决,因为多套餐订单时无法还原每个套餐的成本单价。
### 决策 3`PackageUsage` 新增 `RetailAmount` 字段,`PaidAmount` 保持不变
**选择**:新增 `retail_amount BIGINT NULLABLE`,来源为 `order.TotalAmount`(零售价);`PaidAmount` 继续来源于 `order.ActualPaidAmount`(成本价)。
**理由**`PaidAmount` 已有存量数据和下游依赖,重命名风险高。新增字段向后兼容,存量数据通过迁移 SQL 回填。
### 决策 4资产套餐接口按账号类型过滤在 Service 层实现
**选择**`GetPackages` / `GetCurrentPackage` 新增 `callerAccountType string` 参数Service 层根据此参数决定是否填充 `PaidAmount`Handler 层从 middleware 读取账号类型后传入。
**理由**:过滤逻辑是业务规则,属于 Service 层职责。Handler 层只负责提取调用方身份并传递,不做业务判断。
**账号类型判断规则**`callerAccountType == "platform"` 时返回 `PaidAmount`,其他类型(`agent``enterprise``personal_customer`)不返回。
## Risks / Trade-offs
- **[风险] 钱包扣款金额变化**:改用 `ActualPaidAmount` 扣款后,代理自购场景扣款金额不变(成本价),但需确认所有扣款路径都已切换,避免遗漏。→ 迁移时逐一检查 `createOrderWithWalletPayment` 的所有调用点。
- **[风险] 存量订单数据不一致**:历史订单的 `TotalAmount` 已经是成本价,无法回填零售价(零售价快照未存储)。→ 接受此历史数据问题仅对新订单生效C 端展示历史订单时可能仍显示成本价,属于已知限制。
- **[风险] `PackageUsage.RetailAmount` 存量数据为 null**:历史套餐使用记录无零售价快照。→ 迁移 SQL 尝试从关联订单回填,但历史订单 `TotalAmount` 已是成本价,回填值不准确。接受此限制,存量数据 `RetailAmount` 保持 null接口返回时 omitempty 处理。
- **[Trade-off] 赠送套餐0 元)场景**`TotalAmount` = 零售价,`ActualPaidAmount` = 0。C 端看到零售价,后台看到实付 0 元。这是期望行为(已与业务确认)。
## Migration Plan
1. 执行数据库迁移:`tb_order_item``cost_price``tb_package_usage``retail_amount`
2. 部署新代码(新订单开始写入正确的字段语义)
3. 存量数据回填(`retail_amount` 从关联订单 `total_amount` 回填,已知不准确,仅作参考)
4. 无需回滚策略:新增字段有默认值,旧代码不读新字段,可安全回滚
**回滚**:新字段有 `DEFAULT 0` / `NULLABLE`,回滚旧代码后新字段被忽略,不影响业务。

View File

@@ -0,0 +1,41 @@
## Why
后台代购/钱包支付场景下,`Order.TotalAmount` 被覆盖为成本价,导致 C 端订单列表和详情展示的是成本价(甚至 0 元),而非客户应看到的零售售价。同时,`/api/admin/assets/{identifier}/packages``/api/admin/assets/{identifier}/current-package` 两个接口的套餐价格字段(`paid_amount`)对所有后台账号一视同仁地返回成本价,非平台账号(代理商)不应看到平台进货成本。
## What Changes
- **修正 `Order.TotalAmount` 语义**:始终存储零售价(客户面值),不再被成本价覆盖
- **修正 `Order.ActualPaidAmount` 语义**:存储实际支付的成本价,钱包扣款改用此字段
- **新增 `OrderItem.CostPrice` 字段**:在 `tb_order_item` 存储成本单价快照,零售单价保留在 `UnitPrice`
- **新增 `PackageUsage.RetailAmount` 字段**:在 `tb_package_usage` 快照零售价,来源为 `order.TotalAmount`;现有 `PaidAmount` 继续快照成本价(来源为 `order.ActualPaidAmount`
- **资产套餐接口按角色过滤**`/packages``/current-package` 对非平台账号隐藏 `paid_amount`(成本价),仅返回 `retail_amount`(零售价);平台账号两个字段均返回
## Capabilities
### New Capabilities
无新增 Capability。
### Modified Capabilities
- `admin-order-creation``TotalAmount` 语义修正为零售价;新增 `OrderItem.CostPrice` 字段;钱包扣款改用 `ActualPaidAmount`
- `client-order-purchase`C 端订单列表/详情的 `total_amount` 和套餐 `price` 字段改为展示零售价
- `package-usage-paid-amount-snapshot`:新增 `RetailAmount` 字段快照零售价;`PaidAmount` 继续快照成本价;资产套餐接口按调用方角色决定是否返回 `paid_amount`
## Impact
**数据库**
- `tb_order_item` 新增 `cost_price BIGINT NOT NULL DEFAULT 0`
- `tb_package_usage` 新增 `retail_amount BIGINT NULLABLE`
**代码**
- `internal/service/order/service.go`admin 下单逻辑中 `totalAmount` 始终用零售价,成本价只写 `ActualPaidAmount``OrderItem.CostPrice`;钱包扣款改用 `ActualPaidAmount`
- `internal/service/order/service.go`:套餐激活时同步写入 `PackageUsage.RetailAmount`
- `internal/task/auto_purchase.go`:同步写入 `PackageUsage.RetailAmount`
- `internal/service/asset/service.go``GetPackages` / `GetCurrentPackage` 接收调用方账号类型参数,按角色决定是否返回 `paid_amount`
- `internal/handler/admin/asset.go`:传入调用方账号类型
- `internal/model/dto/asset_dto.go``AssetPackageResponse` 新增 `RetailAmount` 字段
- `internal/model/order.go``OrderItem` 新增 `CostPrice` 字段
- `internal/model/package.go``PackageUsage` 新增 `RetailAmount` 字段
**迁移**:需要两条迁移 SQL 回填存量数据

View File

@@ -0,0 +1,79 @@
## MODIFIED Requirements
### Requirement: 后台订单 TotalAmount 语义修正
系统 SHALL 在后台创建订单时,`Order.TotalAmount` MUST 始终存储零售价(客户面值),不得被成本价覆盖。`Order.ActualPaidAmount` MUST 存储实际支付的成本价。
**字段语义规范**
- `total_amount`零售价所有场景均为套餐零售单价之和C 端和后台均可安全展示
- `actual_paid_amount`:实付成本价,代购/钱包支付场景为买家实际支付的成本金额
**各场景赋值规则**
| 场景 | total_amount | actual_paid_amount |
|------|-------------|-------------------|
| 平台自营 offline | 零售价 | 零售价(无差价) |
| 平台代购 offline | 零售价 | 成本价(买家成本) |
| 代理自购 wallet | 零售价 | 成本价(自己的成本价) |
| 代理代购 wallet | 零售价 | 操作方成本价 |
| 赠送套餐 offline | 零售价 | 0 |
**钱包扣款**`createOrderWithWalletPayment` MUST 使用 `order.ActualPaidAmount` 作为扣款金额,不得使用 `order.TotalAmount`
#### Scenario: 平台代购时 TotalAmount 为零售价
- **WHEN** 平台为代理商下属资产创建 offline 订单,套餐零售价 9900 分,代理成本价 7000 分
- **THEN** `order.total_amount = 9900``order.actual_paid_amount = 7000`
#### Scenario: 代理自购时 TotalAmount 为零售价
- **WHEN** 代理商以 wallet 支付为自己的资产购买套餐,套餐零售价 9900 分,代理成本价 7000 分
- **THEN** `order.total_amount = 9900``order.actual_paid_amount = 7000`,钱包扣款 7000 分
#### Scenario: 代理代购时 TotalAmount 为零售价
- **WHEN** 上级代理以 wallet 支付为下级代理资产购买套餐,零售价 9900 分,操作方成本价 8000 分,买家成本价 7000 分
- **THEN** `order.total_amount = 9900``order.actual_paid_amount = 8000`(操作方实付),钱包扣款 8000 分
#### Scenario: 赠送套餐时 TotalAmount 为零售价
- **WHEN** 平台以 offline 方式赠送套餐(含赠送标记),套餐零售价 9900 分
- **THEN** `order.total_amount = 9900``order.actual_paid_amount = 0`
---
### Requirement: OrderItem 新增 CostPrice 字段
系统 SHALL 在 `tb_order_item` 中新增 `cost_price BIGINT NOT NULL DEFAULT 0` 字段,存储套餐成本单价快照。`unit_price` 字段 MUST 改为存储零售单价。
**字段规范**
- `unit_price`:零售单价(分),所有场景均为套餐对外售价
- `cost_price`:成本单价(分),代购/钱包支付场景为买家实际成本;平台自营或赠送时为 0
**赋值来源**`cost_price``itemUnitPriceMap`(成本价 map中取值`unit_price` 从零售价 map 中取值。
#### Scenario: 代理自购时 OrderItem 同时记录两种价格
- **WHEN** 代理商购买套餐,零售价 9900 分,成本价 7000 分
- **THEN** `order_item.unit_price = 9900``order_item.cost_price = 7000`
#### Scenario: 平台自营时 CostPrice 为 0
- **WHEN** 平台以 offline 方式为平台自营资产购买套餐,零售价 9900 分
- **THEN** `order_item.unit_price = 9900``order_item.cost_price = 0`
#### Scenario: 赠送套餐时 CostPrice 为 0
- **WHEN** 平台赠送套餐,零售价 9900 分
- **THEN** `order_item.unit_price = 9900``order_item.cost_price = 0`
---
### Requirement: 后台订单 API 响应格式更新
系统 SHALL 在后台订单创建响应中,`total_amount` 字段返回零售价,`actual_paid_amount` 字段返回成本价。
#### Scenario: wallet 订单响应 total_amount 为零售价
- **WHEN** 代理在后台创建 wallet 订单成功,零售价 9900 分,成本价 7000 分
- **THEN** 响应中 `total_amount = 9900``actual_paid_amount = 7000`

View File

@@ -0,0 +1,40 @@
## MODIFIED Requirements
### Requirement: D2 套餐订单列表接口价格展示
系统 SHALL 在 C 端订单列表接口中,`total_amount` 字段 MUST 返回零售价(客户面值)。后台代购/钱包支付场景下C 端客户看到的是套餐零售价,而非成本价。
由于 `Order.TotalAmount` 语义已修正为零售价(见 `admin-order-creation` 变更C 端列表接口无需修改代码,直接受益于数据层修正。
#### Scenario: 后台代购订单在 C 端展示零售价
- **WHEN** 平台为客户代购套餐(成本价 7000 分,零售价 9900 分),客户查询 C 端订单列表
- **THEN** 列表项 `total_amount = 9900`,展示零售价
#### Scenario: 代理钱包支付订单在 C 端展示零售价
- **WHEN** 代理以钱包支付为客户购买套餐(成本价 7000 分,零售价 9900 分),客户查询 C 端订单列表
- **THEN** 列表项 `total_amount = 9900`,展示零售价
#### Scenario: 赠送套餐在 C 端展示零售价
- **WHEN** 平台赠送套餐(零售价 9900 分,实付 0 元),客户查询 C 端订单列表
- **THEN** 列表项 `total_amount = 9900`,展示零售价
---
### Requirement: D3 套餐订单详情接口价格展示
系统 SHALL 在 C 端订单详情接口中,`total_amount` 字段 MUST 返回零售价,套餐明细中每项的 `price` 字段 MUST 返回零售单价。
`ClientOrderPackageItem.price` 来源于 `OrderItem.UnitPrice`,由于 `UnitPrice` 语义已修正为零售单价,详情接口无需修改代码,直接受益于数据层修正。
#### Scenario: 后台代购订单详情在 C 端展示零售价
- **WHEN** 平台为客户代购套餐(成本价 7000 分,零售价 9900 分),客户查询 C 端订单详情
- **THEN** `total_amount = 9900`,套餐明细 `price = 9900`
#### Scenario: 赠送套餐详情在 C 端展示零售价
- **WHEN** 平台赠送套餐(零售价 9900 分,实付 0 元),客户查询 C 端订单详情
- **THEN** `total_amount = 9900`,套餐明细 `price = 9900`

View File

@@ -0,0 +1,81 @@
## MODIFIED Requirements
### Requirement: 套餐使用记录新增零售价快照字段
系统 SHALL 在 `tb_package_usage` 中新增 `retail_amount BIGINT NULLABLE` 字段,在创建 `PackageUsage` 记录时快照套餐零售价。
**字段规范**
- 数据库字段:`retail_amount BIGINT NULLABLE`
- Go 字段:`RetailAmount *int64`(单位:分)
- 赋值来源:`order.TotalAmount`(零售价),直接赋值,不转换
- 为 null 的情况:无订单关联的企业分配套餐(`order_id = 0`
**现有 `PaidAmount` 字段保持不变**:继续快照 `order.ActualPaidAmount`(成本价)。
**覆盖范围(所有 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 从关联订单回填,已知历史订单 `total_amount` 可能为成本价(历史数据问题),回填值仅作参考,接受不准确。
#### Scenario: 代理钱包支付套餐激活时快照零售价和成本价
- **WHEN** 代理以钱包支付购买套餐,零售价 9900 分,成本价 7000 分
- **THEN** 激活生成的 `PackageUsage.retail_amount = 9900``PackageUsage.paid_amount = 7000`
#### Scenario: 平台代购套餐激活时快照零售价和成本价
- **WHEN** 平台代购套餐,零售价 9900 分,成本价 7000 分
- **THEN** 激活生成的 `PackageUsage.retail_amount = 9900``PackageUsage.paid_amount = 7000`
#### Scenario: 赠送套餐激活时 paid_amount 为 0retail_amount 为零售价
- **WHEN** 平台赠送套餐,零售价 9900 分,实付 0 元
- **THEN** `PackageUsage.retail_amount = 9900``PackageUsage.paid_amount = 0`
#### Scenario: 无订单关联的套餐 retail_amount 为 null
- **WHEN** 企业分配套餐(无订单),`order_id = 0`
- **THEN** `PackageUsage.retail_amount = nil`,接口响应中 `retail_amount` 字段缺省omitempty
---
### Requirement: 资产套餐接口按调用方角色过滤成本价
系统 SHALL 在 `/api/admin/assets/{identifier}/packages``/api/admin/assets/{identifier}/current-package` 接口中,根据调用方账号类型决定是否返回 `paid_amount`(成本价)字段。
**过滤规则**
- 调用方账号类型为 `platform`:返回 `paid_amount``retail_amount` 两个字段
- 调用方账号类型为其他(`agent``enterprise``personal_customer``paid_amount` 不返回null/omitempty仅返回 `retail_amount`
**实现方式**`GetPackages` / `GetCurrentPackage` 新增 `callerAccountType string` 参数Service 层根据此参数决定是否填充 `PaidAmount`Handler 层从 middleware 读取账号类型后传入。
**`AssetPackageResponse` DTO 新增字段**
- `retail_amount *int64`:零售价(分),来源 `PackageUsage.RetailAmount`omitempty
#### Scenario: 平台账号查询资产套餐返回两种价格
- **WHEN** 平台账号调用 `/api/admin/assets/{identifier}/packages`,套餐零售价 9900 分,成本价 7000 分
- **THEN** 响应中 `retail_amount = 9900``paid_amount = 7000`,两个字段均返回
#### Scenario: 代理账号查询资产套餐只返回零售价
- **WHEN** 代理账号调用 `/api/admin/assets/{identifier}/packages`,套餐零售价 9900 分,成本价 7000 分
- **THEN** 响应中 `retail_amount = 9900``paid_amount` 字段不返回null
#### Scenario: 平台账号查询当前生效套餐返回两种价格
- **WHEN** 平台账号调用 `/api/admin/assets/{identifier}/current-package`
- **THEN** 响应中 `retail_amount``paid_amount` 均有值
#### Scenario: 代理账号查询当前生效套餐只返回零售价
- **WHEN** 代理账号调用 `/api/admin/assets/{identifier}/current-package`
- **THEN** 响应中 `retail_amount` 有值,`paid_amount` 不返回
#### Scenario: 套餐无零售价快照时 retail_amount 为 null
- **WHEN** 历史套餐使用记录 `retail_amount` 为 null存量数据
- **THEN** 响应中 `retail_amount` 字段缺省omitempty不返回

View File

@@ -0,0 +1,42 @@
## 1. 数据库迁移
- [x] 1.1 创建迁移文件,在 `tb_order_item` 新增 `cost_price BIGINT NOT NULL DEFAULT 0` 字段
- [x] 1.2 创建迁移文件,在 `tb_package_usage` 新增 `retail_amount BIGINT NULLABLE` 字段
- [x] 1.3 在迁移文件中添加存量数据回填 SQL`tb_package_usage.retail_amount` 从关联订单 `total_amount` 回填(`order_id != 0` 的记录)
- [x] 1.4 执行迁移,验证两个字段已成功添加到数据库
## 2. 数据模型更新
- [x] 2.1 在 `internal/model/order.go``OrderItem` 结构体中新增 `CostPrice int64` 字段GORM tag + 中文注释)
- [x] 2.2 在 `internal/model/package.go``PackageUsage` 结构体中新增 `RetailAmount *int64` 字段GORM tag + 中文注释)
- [x] 2.3 在 `internal/model/dto/asset_dto.go``AssetPackageResponse` 中新增 `RetailAmount *int64` 字段json tag `retail_amount,omitempty` + description
## 3. 修正 Admin 下单价格语义
- [x] 3.1 在 `internal/service/order/service.go` 中,修正各场景的 `totalAmount` 赋值:始终使用 `retailTotalAmount`,不再被 `buyerTotalCost` 覆盖(覆盖平台代购、代理自购、代理代购、平台代扣四个子场景)
- [x] 3.2 在 `internal/service/order/service.go` 中,修正 `buildOrderItems``UnitPrice` 改从零售价 map 取值,`CostPrice` 从成本价 map 取值(需同时传入两个 map
- [x] 3.3 在 `internal/service/order/service.go` 中,修正 `createOrderWithWalletPayment`:钱包扣款金额改用 `order.ActualPaidAmount`,不再使用 `order.TotalAmount`
- [ ] 3.4 验证:通过 PostgreSQL MCP 查询新建的后台代购订单,确认 `total_amount` = 零售价,`actual_paid_amount` = 成本价,`order_item.unit_price` = 零售单价,`order_item.cost_price` = 成本单价
## 4. 修正套餐激活时的价格快照
- [x] 4.1 在 `internal/service/order/service.go``activateMainPackage()` 中,写入 `PackageUsage.RetailAmount = order.TotalAmount`
- [x] 4.2 在 `internal/service/order/service.go``activateAddonPackage()` 中,写入 `PackageUsage.RetailAmount = order.TotalAmount`
- [x] 4.3 在 `internal/task/auto_purchase.go``activateMainPackage()` 中,写入 `PackageUsage.RetailAmount = order.TotalAmount`
- [x] 4.4 在 `internal/task/auto_purchase.go``activateAddonPackage()` 中,写入 `PackageUsage.RetailAmount = order.TotalAmount`
- [ ] 4.5 验证:通过 PostgreSQL MCP 查询新激活的套餐使用记录,确认 `retail_amount` = 零售价,`paid_amount` = 成本价
## 5. 资产套餐接口按角色过滤成本价
- [x] 5.1 修改 `internal/service/asset/service.go``GetPackages()` 签名,新增 `callerAccountType string` 参数;当 `callerAccountType != "platform"` 时,`AssetPackageResponse.PaidAmount` 置为 nil
- [x] 5.2 修改 `internal/service/asset/service.go``GetCurrentPackage()` 签名,新增 `callerAccountType string` 参数;同上过滤逻辑
- [x] 5.3 在两个方法中,将 `PackageUsage.RetailAmount` 赋值给 `AssetPackageResponse.RetailAmount`
- [x] 5.4 修改 `internal/handler/admin/asset.go``Packages()` 方法:从 middleware 读取调用方账号类型,传入 `GetPackages()`
- [x] 5.5 修改 `internal/handler/admin/asset.go``CurrentPackage()` 方法:从 middleware 读取调用方账号类型,传入 `GetCurrentPackage()`
- [ ] 5.6 验证:用平台账号调用 `/api/admin/assets/{identifier}/packages`,确认响应包含 `paid_amount``retail_amount`;用代理账号调用,确认响应只有 `retail_amount`,无 `paid_amount`
## 6. 验证 C 端订单价格展示
- [x] 6.1 通过 PostgreSQL MCP 查询一条后台代购订单,确认 `total_amount` 已为零售价(历史数据为成本价,已知;新建订单需运行时验证)
- [ ] 6.2 调用 `GET /api/c/v1/orders?identifier=xxx`,确认列表中 `total_amount` 展示零售价
- [ ] 6.3 调用 `GET /api/c/v1/orders/:id`,确认详情中 `total_amount` 和套餐 `price` 均为零售价