junhong_cmp_fiber/openspec/changes/scope-expiry-reminder-to-current-asset/specs/notification-delivery/spec.md

MODIFIED Requirements

Requirement: 套餐临期每日站内提醒

系统 SHALL 在每日扫描时，向最终到期时间可精确推算且剩余 0 至 15 个上海自然日的资产所属店铺后台接收人创建套餐临期站内通知。系统 MUST 对同一资产、同一最终到期日期、同一剩余天数和同一接收人保持幂等。每日扫描 MUST NOT 向个人客户创建套餐临期通知；个人客户的临期提醒只按“H5 进入资产时的套餐临期提醒”产生。

Scenario: 临期窗口内连续两日提醒

• GIVEN 一项资产的最终到期时间可精确推算，昨天剩余 3 个上海自然日，今天剩余 2 个上海自然日，且两日均有有效店铺接收人
• WHEN 每日临期扫描分别执行
• THEN 系统分别为店铺接收人创建昨天和今天的套餐临期通知

Scenario: 不在临期窗口的资产

• GIVEN 一项资产剩余超过 15 个上海自然日、已经到期或最终到期时间不可精确推算
• WHEN 每日临期扫描执行
• THEN 系统不为该资产创建套餐临期通知

Scenario: 每日扫描不通知个人客户

• GIVEN 一项临期资产绑定了个人客户
• WHEN 每日临期扫描执行
• THEN 系统只为店铺接收人创建通知，不为个人客户创建通知

ADDED Requirements

Requirement: H5 进入资产时的套餐临期提醒

个人客户访问 GET /api/c/v1/asset/info 时，系统 SHALL 以令牌中的当前资产，按与每日扫描相同的最终到期推算判断是否临期（剩余 0～15 个上海自然日，≤3 红、≤7 紫、≤15 粉红）。命中且该客户当天（上海自然日）尚未就该资产提醒过时，系统 MUST 在响应中返回临期提醒字段（剩余天数、到期时间、等级），并为当前客户、当前资产写一条 package.expiring 个人通知，通知幂等事件号 MUST 包含资产、到期日、剩余天数与客户。

同一客户、同一资产、同一上海自然日 MUST 至多返回一次提醒字段、至多产生一条通知；去重键为“客户 + 资产标识 + 日期”。系统 MUST 先检查去重键，已存在则不返回字段、不写通知；不存在时先写通知，写入成功后再占用去重键，抢占成功才返回字段。通知写入失败时 MUST NOT 占用去重键、MUST NOT 返回字段，下次进入重试。去重存储不可用时系统按“未提醒过”处理，提醒字段可能当天多次返回，通知由事件号幂等保证不重复。

该通知 MUST 在创建时即为已读（read_at 为创建时间），MUST NOT 计入个人未读数；其他类型的个人直发通知和店铺临期通知 MUST 仍以未读创建。

Scenario: 当天首次进入临期资产

• WHEN 客户首次在当天进入一项剩余 2 天的资产
• THEN 响应返回剩余天数 2、到期时间与红色等级，并新增一条该资产的已读临期通知

Scenario: 同一天再次进入

• WHEN 同一客户当天再次进入该资产
• THEN 响应不返回临期提醒字段，不新增通知

Scenario: 第二天再次进入

• WHEN 同一客户第二天进入该资产且仍在临期窗口
• THEN 再次返回提醒字段并新增一条通知

Scenario: 不同客户进入同一资产

• WHEN 客户 B 当天进入客户 A 已被提醒过的资产
• THEN 客户 B 独立获得一次提醒

Scenario: 非临期资产

• WHEN 客户进入剩余超过 15 天或最终到期不可精确推算的资产
• THEN 响应不返回临期提醒字段，不写通知

Scenario: 临期提醒通知写入即已读

• WHEN 客户当天首次进入临期资产，响应返回了提醒字段
• THEN 新增的该资产临期通知为已读，通知中心可见，个人未读数不增加

Scenario: 其他直发通知仍为未读

• WHEN 系统为个人客户投递换货发货通知或自动续费通知
• THEN 通知以未读创建，计入未读数

Requirement: 个人通知中心临期提醒按当前资产过滤

个人客户通知列表、未读数与“全部已读”（PUT /api/c/v1/notifications/read-all）SHALL 对 type = package.expiring 且 ref_type = asset 的通知，只处理 ref_key 等于当前资产标识的通知（卡为 ICCID；设备优先虚拟号，为空则 IMEI）；MUST NOT 使用 ref_id 过滤。“全部已读”MUST NOT 把其他资产的临期提醒标为已读。其他类型通知 MUST 不受影响，接口入参不变。设备后补虚拟号前产生的历史提醒 ref_key 为 IMEI，补号后不再匹配，属可接受限制。

Scenario: 客户名下两个临期资产

• GIVEN 客户名下资产 A、B 都有临期通知
• WHEN 客户在资产 A 中查询通知列表与未读数
• THEN 临期通知只含 A 的，未读数只计 A 的临期通知与其他类型通知

Scenario: 全部已读只处理当前资产的临期提醒

• GIVEN 客户名下资产 A、B 都有未读临期通知
• WHEN 客户在资产 A 中点“全部已读”
• THEN A 的临期通知与其他类型通知变为已读，B 的临期通知仍为未读，客户进入 B 时仍能看到

Scenario: 非临期通知不受过滤

• WHEN 客户在资产 A 中查询通知列表
• THEN 非 package.expiring 类型的通知照常返回