赠送套餐逻辑

openspec/changes/package-price-fallback-and-platform-gift-policy/实施基线与手工验证清单.md

@@ -0,0 +1,98 @@
+# 实施基线与手工验证清单
+
+## 一、当前受影响接口与链路
+
+### 1. 后台套餐管理
+- `GET /api/admin/packages`
+- `GET /api/admin/packages/:id`
+- `POST /api/admin/packages`
+- `PUT /api/admin/packages/:id`
+- `PUT /api/admin/packages/:id/shelf-status`
+- `PUT /api/admin/packages/:id/retail-price`
+
+### 2. C 端可购套餐与下单
+- `GET /api/c/v1/asset/packages?identifier=xxx`
+- C 端创建订单链路（`internal/service/client_order/service.go`）
+- 充值后自动购包链路（`internal/task/auto_purchase.go`）
+
+### 3. 后台订单与发放链路
+- 后台创建订单（`internal/service/order/service.go`）
+- 套餐激活链路（`internal/service/order/service.go`、`internal/service/package/activation_service.go`）
+
+### 4. 代理授权与分配
+- 系列授权创建/维护（`internal/service/shop_series_grant/service.go`）
+- 批量分配（`internal/service/shop_package_batch_allocation/service.go`）
+
+## 二、当前受影响数据表
+
+- `tb_package`：套餐主数据，当前仅有 `cost_price`、`suggested_retail_price`
+- `tb_shop_package_allocation`：代理分配记录，当前仅有 `cost_price`、`retail_price`
+- `tb_order`：订单主表
+- `tb_order_item`：订单价格快照
+- `tb_package_usage`：套餐使用记录快照
+- `tb_shop_package_allocation_price_history`：当前仅记录成本价变更历史
+
+## 三、回滚点与历史数据来源
+
+### 1. 回滚点
+- 迁移文件回滚：撤销新增字段、清理人工复核清单表
+- Service 层回滚：恢复到直接读取 `suggested_retail_price` / `retail_price` 的旧逻辑
+- 发放策略回滚：撤销后台赠送订单专属分支，恢复统一后台订单逻辑
+
+### 2. 历史数据判定来源
+- `tb_package.suggested_retail_price`
+- `tb_shop_package_allocation.retail_price`
+- `tb_order_item.unit_price`
+- `tb_order.total_amount` / `tb_order.actual_paid_amount`
+- `tb_package_usage.paid_amount`
+- 后台创建订单记录（用于识别“发放=后台创建订单”的赠送语义）
+
+## 四、改动前诊断基线
+
+### 1. 无阻塞诊断错误的核心文件
+- `internal/model/package.go`
+- `internal/service/purchase_validation/service.go`
+- `internal/service/client_order/service.go`
+- `internal/task/auto_purchase.go`
+- `internal/service/shop_package_batch_allocation/service.go`
+- `internal/service/shop_series_grant/service.go`
+
+### 2. 已知基线提示（非本次改动引入）
+- `internal/service/order/service.go` 存在若干 `QF1003` 提示、`unusedparams` 提示和既有 `nilness` warning，作为改动前基线保留
+- `internal/handler/app/client_asset.go` 存在 `unusedfunc` 基线提示
+
+## 五、手工验证清单
+
+### 1. 后台套餐配置
+- 创建普通可售套餐，建议售价留空，保存成功
+- 创建普通可售套餐，建议售价填 `0`，保存失败
+- 创建赠送套餐，建议售价填 `0`，保存成功
+- 编辑普通可售套餐将建议售价改成 `0`，保存失败
+- 详情页/编辑页能区分“未配置价格”和“赠送 0 价”
+
+### 2. C 端可购列表
+- 平台渠道普通套餐未配置建议售价时，列表显示成本价
+- 代理渠道分配记录未配置零售价时，列表显示成本价
+- 赠送套餐不出现在可购列表
+- 无主套餐时，加油包仍然不可见
+
+### 3. 下单与自动购包
+- C 端普通套餐下单按生效价落单
+- H5/后台普通购买接口无法购买赠送套餐
+- 自动购包命中赠送套餐时被拦截
+- 同一订单仍禁止正式套餐和加油包混买
+
+### 4. 后台发放（走创建订单）
+- 平台后台可为目标资产创建赠送订单并激活套餐
+- 赠送订单无需支付凭证，不产生正常购买语义
+- 赠送加油包必须已有主套餐，否则发放失败
+
+### 5. 代理授权与分配
+- 代理授权列表不展示赠送套餐
+- 系列授权新增赠送套餐失败
+- 批量分配不会把赠送套餐分配给代理
+
+### 6. 迁移与历史数据
+- 迁移后能区分未配置价格、赠送 0 价、已配置非 0
+- 历史模糊 0 数据进入人工复核清单
+- 历史快照查询不再把普通未配置价格当成显式 0 售卖价