one-pipe-system/openspec/changes/add-asset-estimated-final-expiry-display/specs/device-management/spec.md

ADDED Requirements

Requirement: Device Estimated Final Expiry Display

The device management list integration SHALL preserve and display the five backend device-level estimated final package expiry fields estimated_final_expires_at, days_until_final_expiry, expiry_estimate_status, expiry_estimate_status_name, and is_expiring returned in data.items[] by GET /api/admin/devices. The status SHALL be one of exact, waiting_activation, none, or invalid_data; non-exact records SHALL have estimated_final_expires_at=null and days_until_final_expiry=null. The frontend SHALL NOT traverse bound cards or calculate package continuation dates. This requirement applies only to the admin device list.

Scenario: Display exact device final expiry estimate

• GIVEN 设备列表接口返回 expiry_estimate_status=exact and estimated_final_expires_at
• WHEN 页面渲染设备列表行
• THEN 页面 MUST display a column labeled 预计套餐到期时间
• AND 该列 MUST format and display estimated_final_expires_at

Scenario: Display activation-pending device final expiry

• GIVEN 设备列表接口返回 expiry_estimate_status=waiting_activation
• WHEN 页面渲染设备列表行
• THEN 预计套餐到期时间 MUST display 待激活后起算
• AND 页面 MUST NOT traverse bound cards or display a fabricated date

Scenario: Display device estimate status names for non-exact states

• GIVEN 设备列表接口返回 expiry_estimate_status=none 或 expiry_estimate_status=invalid_data
• WHEN 页面渲染设备列表行
• THEN none MUST display a stable empty placeholder
• AND invalid_data MUST display 数据异常
• AND 页面 MUST use the status enum to choose the display rule

Scenario: Preserve null fields for non-exact device estimates

• GIVEN 设备列表接口返回 expiry_estimate_status=none 或 expiry_estimate_status=invalid_data
• THEN estimated_final_expires_at MUST be null
• AND days_until_final_expiry MUST be null
• AND 页面 MUST NOT derive either field from绑定卡或套餐数据

Scenario: Highlight expiring device without reordering

• GIVEN 设备列表接口返回 is_expiring=true and days_until_final_expiry
• WHEN 页面渲染该设备的预计套餐到期时间
• THEN 页面 MUST apply the expiring visual treatment based on the backend fields
• AND 页面 MUST NOT change the ordinary device list sort order because of is_expiring

Scenario: Display no-package device placeholder

• GIVEN 设备列表记录没有可预计的最终到期时间
• WHEN 页面渲染预计套餐到期时间列
• THEN 页面 MUST display a stable placeholder
• AND 页面 MUST NOT use an individual package expiry as a substitute

Scenario: Preserve device status name without using it for business calculation

• WHEN 设备列表接口返回 expiry_estimate_status_name
• THEN 前端类型 MUST preserve the field
• AND 页面 MUST NOT calculate or replace the backend status name