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

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