junhong_cmp_fiber/openspec/changes/refactor-traffic-model-semantics/specs/asset-queries/spec.md

MODIFIED Requirements

Requirement: 套餐历史列表查询

系统 SHALL 提供资产的全量套餐记录查询接口，包含历史和当前生效套餐。

API 端点: GET /api/admin/assets/:asset_type/:id/packages

每条记录响应字段:

• package_usage_id
• package_name
• package_type
• master_usage_id
• real_total_mb
• real_used_mb
• virtual_total_mb
• virtual_used_mb
• reduction_pct
• activated_at
• expires_at
• status
• paid_amount

兼容规则:

• 不再返回 real_data_mb、virtual_data_mb、package_used_mb、package_remain_mb 等旧展示字段

Scenario: 历史列表返回统一五字段

• WHEN 管理员调用 GET /api/admin/assets/card/123/packages
• THEN 每条套餐记录都返回统一五字段和 reduction_pct

Scenario: 无套餐历史时返回空数组

• WHEN 管理员查询一张从未购买套餐的卡
• THEN 系统返回空数组，不报错

Requirement: 当前主套餐详情查询

系统 SHALL 提供查询资产当前生效主套餐的接口，用于展示主套餐详细信息。

API 端点: GET /api/admin/assets/:asset_type/:id/current-package

查询条件: status = 1 AND master_usage_id IS NULL

响应字段:

• 与套餐历史列表中的单条记录字段一致
• 不包含加油包汇总
• 无生效主套餐时返回 HTTP 200，且 data = null

Scenario: 当前套餐只返回主套餐

• WHEN 管理员调用 GET /api/admin/assets/card/123/current-package，该卡存在 1 个生效主套餐和多个加油包
• THEN 系统只返回主套餐的统一五字段与 reduction_pct

Scenario: 无当前主套餐返回 200 + null

• WHEN 管理员查询没有生效中主套餐的资产
• THEN 系统返回 HTTP 200
• AND 响应体中的 data = null