update

openspec/changes/add-asset-package-hierarchy/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-31

openspec/changes/add-asset-package-hierarchy/design.md

@@ -0,0 +1,20 @@
+## Context
+
+套餐使用记录已有 `master_usage_id`，不能为展示重复存储关系。
+
+## Decisions
+
+- 查询批量读取资产全部套餐使用，按 `master_usage_id` 内存分组并稳定排序。
+- 不改变套餐状态、金额或生命周期；缺失主记录只形成读模型异常项。
+
+## 查询与响应契约
+
+- 后台资产详情及 H5 `GET /api/c/v1/asset/package-history` 保持既有资产权限、分页和套餐字段；不新增写接口、迁移、关联表或状态变更。查询需在资产范围内一次读取该资产全部相关 `PackageUsage`，不能按每个主套餐逐条查询加油包。
+- 响应主项包含原套餐使用字段、`children` 加油包数组和 `expand_by_default`；主项 `master_usage_id` 必须为 `null`。子项保留自身 `package_usage_id`、`master_usage_id`、状态、购买创建时间、生效时间和原历史字段。
+- 以 `master_usage_id IS NULL` 的记录为主套餐；关联存在的加油包嵌入对应主项。已生效加油包先按生效时间正序，待生效加油包后按购买创建时间正序；排序字段相同再按 `package_usage_id` 正序，保证后台和 H5 一致。
+- 主套餐只要有一个关联子项即 `expand_by_default=true`；无子项为 `false`。主套餐、子项失效、过期、用尽、退款或历史状态均不得删除或改写层级。
+- 加油包的 `master_usage_id` 指向物理不存在记录时，返回顶层异常项：保留原字段、`relationship_status=master_missing`、`relationship_status_name=关联主套餐缺失`、`children=[]`、`expand_by_default=false`；不得猜测替代主套餐或丢弃该项。
+
+## Verification
+
+验证多主套餐、待生效/失效加油包、缺失主记录、后台/H5 数据范围和分页。

openspec/changes/add-asset-package-hierarchy/proposal.md

@@ -0,0 +1,24 @@
+## Scope
+
+- 迭代编号：`AUG26-013`。
+
+## Why
+
+资产套餐历史平铺展示，无法识别主套餐与其加油包的真实关联。
+
+## What Changes
+
+- 在后台和 H5 按既有套餐使用关联投影主套餐—加油包层级。
+- 保留失效历史；主套餐物理缺失作为可观察异常。
+
+## Capabilities
+
+### New Capabilities
+- 无。
+
+### Modified Capabilities
+- `package-lifecycle`: 套餐历史层级展示。
+
+## Impact
+
+影响套餐使用查询、后台资产详情、H5 和 OpenAPI。

openspec/changes/add-asset-package-hierarchy/specs/package-lifecycle/spec.md

@@ -0,0 +1,16 @@
+## ADDED Requirements
+
+### Requirement: 资产套餐层级投影
+系统 SHALL 在后台资产详情和 H5 资产套餐历史中，直接以既有 `PackageUsage.master_usage_id` 将主套餐和关联加油包投影为层级结构，不新增关联表。响应中每个主套餐必须返回 `expand_by_default`：存在至少一个关联加油包时为 `true`，否则为 `false`；后台与 H5 使用同一规则。加油包按生效时间正序；待生效加油包按购买创建时间正序并排在已生效包之后。主套餐或加油包失效、过期、用尽时仍保留层级；仅关联主套餐物理缺失时作为“关联主套餐缺失”异常独立项返回。
+
+#### Scenario: 已失效加油包
+- **WHEN** 某加油包及其主套餐已失效但主套餐记录仍存在
+- **THEN** 系统仍将加油包嵌入该主套餐层级，不因状态失效拆散关系
+
+#### Scenario: 主套餐含加油包
+- **WHEN** 主套餐关联至少一条加油包使用记录
+- **THEN** 后台和 H5 返回该主套餐时均将 `expand_by_default` 设为 `true`
+
+#### Scenario: 主套餐物理缺失
+- **WHEN** 加油包关联的主套餐使用记录不存在
+- **THEN** 系统返回带“关联主套餐缺失”标识的异常独立项

openspec/changes/add-asset-package-hierarchy/tasks.md

@@ -0,0 +1,7 @@
+## 1. 查询契约
+- [ ] 1.1 追踪后台资产详情、H5 套餐历史、`PackageUsage` 和 `master_usage_id` 查询链路。
+- [ ] 1.2 实现批量层级投影、稳定排序和缺失主套餐异常项；更新 DTO、路由说明和 OpenAPI。
+
+## 2. 验证
+- [ ] 2.1 验证多层级、失效保留、待生效排序、缺失主记录及后台/H5 数据范围。
+- [ ] 2.2 运行 `gofmt -w`、`go build ./cmd/api ./cmd/worker`、`go run cmd/gendocs/main.go`、`openspec validate add-asset-package-hierarchy --strict` 和 `openspec doctor --json`；自动化测试按项目决策为 N/A。