junhong_cmp_fiber/openspec/changes/archive/2026-09-07-add-asset-package-hierarchy/tasks.md

## 1. 查询契约与共享投影

- [x] 1.1 依据 design 的开工检查证据核对后台套餐列表、H5 套餐历史、`PackageUsage` 及 DTO 引用范围，确认实施时调用链仍符合既有授权、后台全部世代、H5 当前世代及入口字段差异。
- [x] 1.2 在 `internal/query/asset/package_history.go` 实现既有资产／世代范围内一次读取全部未软删除使用记录；按 `master_usage_id` 建立完整关系，去重后一次最小存在性核对未解析主 ID，区分物理缺失异常项与存在但不可展示时的整体读取错误，禁止逐主项查询子项。
- [x] 1.3 实现同一成员联合匹配状态／类型条件并选择整组，保持 H5 类型匹配排除软删除商品的既有口径；按规格实现三桶子项排序、顶层稳定排序、顶层 `total` 和整组分页。

## 2. 历史响应与两端接入

- [x] 2.1 在现有 DTO 文件增加历史专用层级节点及列表响应，落实普通主项显式 `master_usage_id=null`、`children` 空数组、默认展开及既定缺失标识；不改变当前套餐和修改套餐接口的公共响应契约。
- [x] 2.2 将后台 `Service.GetPackages` 接入共享 Query，保留 Handler 资产解析、状态入参校验、全部世代、50／100 页大小、`page_size` 响应字段、平台成本字段及后台商品查询失败快照策略。
- [x] 2.3 将 H5 `GetPackageHistory` 接入同一 Query，保留客户有效绑定、资产实体当前世代、20／100 页大小、`size` 响应字段、原历史字段及商品查询失败响应；不得因复用补出订单、退款或金额字段。
- [x] 2.4 更新两条历史路由的响应类型、整组分页／筛选和错误说明，批量复用商品加载；仅在构造依赖变化时同步 bootstrap、`cmd/api/docs.go`、`cmd/gendocs/main.go` 装配，删除被本次接入替代的旧明细分页与重复关系逻辑。

## 3. 隔离环境验收

- [x] 3.1 在隔离环境对两条历史入口执行多主项、无子项、多子项及子项数超过页大小的只读 smoke，核对不跨页、不重复、顶层 `total`、异常项独立计数、空结果及超出末页行为。
- [x] 3.2 验证仅子项命中、主项命中、联合条件不能由不同成员分摊、无匹配及软删除商品类型资格场景，确认选中整组并保留完整可展示父子，不因筛选误报主项缺失。
- [x] 3.3 验证主子失效、过期、用尽及退款关系保留；核对三桶顺序、非待生效但生效时间为空、待生效排序及顶层／子项相同时间的确定顺序，不修改原状态。
- [x] 3.4 验证主使用记录物理缺失、软删除、跨资产、H5 跨世代、商品缺失及存在性查询失败分别遵守异常／整体错误／历史回退契约；范围内不可展示关系不因分页或筛选被掩盖，不返回范围外内容及具体不可见原因。
- [x] 3.5 验证卡／设备载体边界、后台全部世代与 H5 当前世代差异、代理店铺范围和 H5 绑定拒绝、主子项金额字段隔离；核对当前套餐及修改接口的既有响应不变，不把存量企业授权问题算作本期已修复。
- [x] 3.6 核对两端相同输入集合的层级顺序一致、两种分页响应壳不变、商品加载失败策略保留；通过隔离环境查询记录确认 usage 一次读取、未解析主 ID 至多一次存在性核对、商品／类型资格批量加载，查询次数不随主项数线性增长。
- [x] 3.7 核对后台和 H5 消费者同步适配层级、默认展开、顶层总数、整组筛选及整体读取错误，完成消费者联调并确认 API 与消费者可同步发布／回滚；未取得联调结果不得宣称展示验收完成。

## 4. 工程验证

- [x] 4.1 对变更 Go 文件运行 `gofmt -w`，运行 `go build ./cmd/api ./cmd/worker` 和 `go run cmd/gendocs/main.go`；核对生成 OpenAPI 与两条历史接口实际 JSON 一致，当前套餐和修改接口未被连带改变。
- [x] 4.2 运行 `openspec validate add-asset-package-hierarchy --strict` 和 `openspec doctor --json`，汇总上述 smoke 与兼容验收结果；自动化测试按项目决策为 N/A，不恢复旧测试，不运行迁移或真实外部业务调用。