完成UR46后端任务收口

2026-07-23 15:06:48 +09:00
parent 8d65b26e96
commit cde5369b30
8 changed files with 306 additions and 46 deletions
--- a/docs/admin-openapi.yaml
+++ b/docs/admin-openapi.yaml
@@ -1082,6 +1082,10 @@ components:
                    minimum: 0
                    nullable: true
                    type: integer
+                days_until_final_expiry:
+                    description: 距预计套餐到期的上海自然日天数，无法精确推算时为 null
+                    nullable: true
+                    type: integer
                device_model:
                    description: 设备型号
                    type: string
@@ -1099,6 +1103,17 @@ components:
                enable_virtual_data:
                    description: 当前主套餐是否启用虚流量（按套餐使用记录快照返回）
                    type: boolean
+                estimated_final_expires_at:
+                    description: 预计套餐到期时间，无法精确推算时为 null
+                    format: date-time
+                    nullable: true
+                    type: string
+                expiry_estimate_status:
+                    description: 预计套餐到期推算状态 (exact:可精确推算, waiting_activation:待激活后起算, none:无参与套餐, invalid_data:数据异常)
+                    type: string
+                expiry_estimate_status_name:
+                    description: 预计套餐到期推算状态名称（中文）
+                    type: string
                gateway_extend:
                    description: Gateway 卡状态扩展字段，原样返回上游 extend，用于展示运营商侧实际停机原因
                    type: string
@@ -1114,6 +1129,9 @@ components:
                imei:
                    description: 设备IMEI
                    type: string
+                is_expiring:
+                    description: 是否临期（仅精确推算且剩余 0 至 15 个上海自然日时为 true）
+                    type: boolean
                manufacturer:
                    description: 制造商
                    type: string
@@ -1653,6 +1671,10 @@ components:
                    minimum: 0
                    nullable: true
                    type: integer
+                days_until_final_expiry:
+                    description: 距预计套餐到期的上海自然日天数，无法精确推算时为 null
+                    nullable: true
+                    type: integer
                device_model:
                    description: 设备型号
                    type: string
@@ -1671,8 +1693,19 @@ components:
                enable_virtual_data:
                    description: 当前主套餐是否启用虚流量（按套餐使用记录快照返回）
                    type: boolean
+                estimated_final_expires_at:
+                    description: 预计套餐到期时间，无法精确推算时为 null
+                    format: date-time
+                    nullable: true
+                    type: string
                exchange_trace:
                    $ref: '#/components/schemas/DtoAssetExchangeTrace'
+                expiry_estimate_status:
+                    description: 预计套餐到期推算状态 (exact:可精确推算, waiting_activation:待激活后起算, none:无参与套餐, invalid_data:数据异常)
+                    type: string
+                expiry_estimate_status_name:
+                    description: 预计套餐到期推算状态名称（中文）
+                    type: string
                gateway_card_imei:
                    description: 插拔卡业务 IMEI（由 Gateway 卡状态接口同步，非设备自身 IMEI，无业务含义，仅供查看）
                    type: string
@@ -1691,6 +1724,9 @@ components:
                imsi:
                    description: IMSI
                    type: string
+                is_expiring:
+                    description: 是否临期（仅精确推算且剩余 0 至 15 个上海自然日时为 true）
+                    type: boolean
                last_gateway_sync_at:
                    description: 最后 sync-info 同步时间（设备类型时有效）
                    format: date-time
@@ -4819,6 +4855,10 @@ components:
                    description: 创建时间
                    format: date-time
                    type: string
+                days_until_final_expiry:
+                    description: 距预计套餐到期的上海自然日天数，无法精确推算时为 null
+                    nullable: true
+                    type: integer
                device_model:
                    description: 设备型号
                    type: string
@@ -4828,6 +4868,17 @@ components:
                device_type:
                    description: 设备类型
                    type: string
+                estimated_final_expires_at:
+                    description: 预计套餐到期时间，无法精确推算时为 null
+                    format: date-time
+                    nullable: true
+                    type: string
+                expiry_estimate_status:
+                    description: 预计套餐到期推算状态 (exact:可精确推算, waiting_activation:待激活后起算, none:无参与套餐, invalid_data:数据异常)
+                    type: string
+                expiry_estimate_status_name:
+                    description: 预计套餐到期推算状态名称（中文）
+                    type: string
                generation:
                    description: 资产世代编号（初始值1，每次换货转新后+1）
                    type: integer
@@ -4838,6 +4889,9 @@ components:
                imei:
                    description: 设备IMEI
                    type: string
+                is_expiring:
+                    description: 是否临期（仅精确推算且剩余 0 至 15 个上海自然日时为 true）
+                    type: boolean
                last_gateway_sync_at:
                    description: 最后 sync-info 同步时间
                    format: date-time
@@ -8508,12 +8562,27 @@ components:
                data_usage_mb:
                    description: 累计流量使用(MB)
                    type: integer
+                days_until_final_expiry:
+                    description: 距预计套餐到期的上海自然日天数，无法精确推算时为 null
+                    nullable: true
+                    type: integer
                device_virtual_no:
                    description: 绑定设备的虚拟号（未绑定时为空字符串）
                    type: string
                enable_polling:
                    description: 是否参与轮询
                    type: boolean
+                estimated_final_expires_at:
+                    description: 预计套餐到期时间，无法精确推算时为 null
+                    format: date-time
+                    nullable: true
+                    type: string
+                expiry_estimate_status:
+                    description: 预计套餐到期推算状态 (exact:可精确推算, waiting_activation:待激活后起算, none:无参与套餐, invalid_data:数据异常)
+                    type: string
+                expiry_estimate_status_name:
+                    description: 预计套餐到期推算状态名称（中文）
+                    type: string
                gateway_card_imei:
                    description: 插拔卡业务 IMEI（由 Gateway 卡状态接口同步，非设备自身 IMEI，无业务含义，仅供查看）
                    type: string
@@ -8533,6 +8602,9 @@ components:
                imsi:
                    description: IMSI
                    type: string
+                is_expiring:
+                    description: 是否临期（仅精确推算且剩余 0 至 15 个上海自然日时为 true）
+                    type: boolean
                last_data_check_at:
                    description: 最后流量检查时间
                    format: date-time
@@ -8710,8 +8782,6 @@ components:
                    description: 分配生效条件覆盖 (null:跟随套餐默认值, from_activation:实名激活时生效, from_purchase:购买即生效)
                    nullable: true
                    type: string
-            required:
-                - expiry_base_override
            type: object
        DtoUpdateAssetPackageExpiresAtRequest:
            properties:
--- a/docs/ur46-estimated-final-expiry/功能总结.md
+++ b/docs/ur46-estimated-final-expiry/功能总结.md
@@ -25,3 +25,5 @@
 ## 性能与迁移

 列表使用每页资产 ID 的一次批量 Query，不逐资产查询套餐。迁移 `000164_add_package_expiry_query_indexes` 为卡和设备主套餐队列读取增加部分索引，可通过对应 down 迁移回滚。
+
+开发测试库在 2026-07-23 执行 `EXPLAIN ANALYZE`：当前 `tb_package_usage` 仅约 30 行，优化器选择顺序扫描，卡查询执行时间约 0.24ms、设备查询约 0.07ms，均低于 50ms 目标；`TestQueryIndexesExplainAnalyze` 固化了该验证命令。