feat: 套餐加油包变子

openspec/changes/update-asset-package-history-hierarchy/proposal.md

@@ -0,0 +1,21 @@
+# Change: Update asset package history hierarchy
+
+## Why
+
+资产套餐历史接口已从平铺使用记录升级为主套餐与关联加油包的关系组。当前 H5 页面把每一条记录当作独立卡片，并以返回条数推断是否还有下一页，无法正确展示层级、默认展开状态和按关系组分页的结果。
+
+## What Changes
+
+- Consume `children` recursively and render a main-package card with its associated addon-package cards.
+- Honor `expand_by_default` for the initial expanded state and allow users to expand or collapse a group without losing any child records.
+- Preserve and render relationship metadata needed by the contract, including `master_usage_id` for addons and `relationship_status` / `relationship_status_name` for a `master_missing` standalone item.
+- Use the response pagination shell (`page`, `size`, `total`) as top-level relationship-group pagination; never infer completion from the number of returned nodes.
+- Keep the complete returned group when the API filter matches either its main package or one of its addons. The client will pass filters through unchanged and will not re-filter individual nodes.
+- Update the local API documentation to match the hierarchical response fields and pagination shell.
+
+## Impact
+
+- Affected capability: `asset-package-history-display` (new)
+- Affected code: `pages/asset-package-history/asset-package-history.vue`, `api/modules/asset.js`, `docs/API.md`
+- Affected API: `GET /api/c/v1/asset/package-history`
+- No backend filtering, relationship recovery, or error-code mapping is implemented in this H5 repository; the client continues to surface the API's unified error response through the shared request layer.

openspec/changes/update-asset-package-history-hierarchy/specs/asset-package-history-display/spec.md

@@ -0,0 +1,56 @@
+## ADDED Requirements
+
+### Requirement: Hierarchical package history display
+
+The H5 client SHALL render each item returned by `GET /api/c/v1/asset/package-history` as a top-level relationship group and SHALL render its recursively supplied `children` as associated addon-package entries without flattening, omitting, or moving them to another page.
+
+#### Scenario: Main package with addon children
+
+- **WHEN** a returned top-level package has one or more `children`
+- **THEN** the client displays the main package and all supplied children within the same relationship group
+- **AND** each node retains its own package, usage, status, and traffic-display fields
+
+#### Scenario: Relationship exception item
+
+- **WHEN** a top-level item has `relationship_status` equal to `master_missing`
+- **THEN** the client displays it as a standalone relationship-exception item
+- **AND** displays `relationship_status_name` when supplied
+
+### Requirement: Group expansion behavior
+
+The H5 client SHALL initialize a package group's visibility from `expand_by_default` and SHALL allow the customer to toggle groups that have children. Addon nodes SHALL retain their supplied `master_usage_id` metadata.
+
+#### Scenario: Default-expanded relationship group
+
+- **WHEN** a top-level group is returned with `expand_by_default` equal to true
+- **THEN** its children are visible on initial render
+
+#### Scenario: Customer expands a collapsed group
+
+- **WHEN** a top-level group with children is returned with `expand_by_default` equal to false and the customer activates its expand control
+- **THEN** every returned child in that group becomes visible
+- **AND** no additional API request is made to retrieve those children
+
+### Requirement: Relationship-group pagination
+
+The H5 client SHALL treat `page`, `size`, and `total` from the package-history response as pagination metadata for top-level relationship groups. It SHALL not use a child count or the number of returned nodes to decide whether more pages are available.
+
+#### Scenario: Last page has a full number of groups
+
+- **WHEN** the response contains `size` top-level groups and `page * size` is greater than or equal to `total`
+- **THEN** the client indicates that no more relationship groups are available
+
+#### Scenario: Filtered group response
+
+- **WHEN** the API returns a complete relationship group because either its main node or an addon node jointly matches the supplied `status` and `package_type` filter
+- **THEN** the client displays the complete returned group without applying node-level filtering
+
+### Requirement: Package history failure handling
+
+The H5 client SHALL rely on the shared request layer for non-success package-history responses, preserving the API-provided unified error message and authentication handling.
+
+#### Scenario: Related master cannot be read
+
+- **WHEN** the API returns a non-success response because a related master record exists but cannot be displayed
+- **THEN** the client does not synthesize a relationship item
+- **AND** the shared request layer displays the unified API error response

openspec/changes/update-asset-package-history-hierarchy/tasks.md

@@ -0,0 +1,16 @@
+## 1. API contract and data handling
+
+- [x] 1.1 Document the hierarchical node fields, relationship exceptions, and top-level pagination shell for package history.
+- [x] 1.2 Add a client-side response normalizer that preserves recursively returned `children` and all relationship metadata.
+- [x] 1.3 Use `total` and returned top-level groups to drive pagination, so children never consume page capacity or cross pages.
+
+## 2. Package history UI
+
+- [x] 2.1 Render returned top-level relationship groups and their addon children with the existing package metrics and status styling.
+- [x] 2.2 Initialize groups from `expand_by_default` and add an accessible expand/collapse control for groups with children.
+- [x] 2.3 Render `master_missing` as a standalone relationship-exception item and preserve normal shared-request error handling for all other API failures.
+
+## 3. Verification
+
+- [x] 3.1 Verify nested, collapsed, expanded, filtered-group, `master_missing`, and multi-page response fixtures.
+- [x] 3.2 Run the H5 production build and inspect the changed files for contract consistency.