feat: 套餐加油包变子

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