## ADDED Requirements ### Requirement: 实名即生效套餐沉默期按每笔套餐计算 系统 SHALL 在订单支付成功、创建套餐记录的同一事务内,为满足条件的套餐记录设置沉默期:主套餐(`master_usage_id IS NULL`)、生效条件快照为 `from_activation`、购买时资产尚未实名(`pending_realname_activation = true`)、所购套餐已配置默认沉默期。沉默期字段 MUST 保存在套餐记录上,资产上 MUST NOT 保存沉默期字段。同一资产的多笔实名即生效套餐 MUST 各自计算。 截止时间 MUST 按天计算:`(支付成功日期 + 沉默期天数) 当日 23:59:59`,时区 `Asia/Shanghai`,由唯一领域函数计算。 #### Scenario: 资产未实名时购买实名即生效套餐 - **WHEN** 2026-09-24 10:00 为未实名的卡购买默认沉默期 30 天的实名即生效主套餐并支付成功 - **THEN** 套餐记录 `silence_status = waiting`、`silence_start_at` 为支付成功时间、`silence_period_days = 30` - **AND** `silence_deadline_at = 2026-10-24 23:59:59` - **AND** 写入一条沉默期流水(set),含默认值快照、是否调整、操作人、原因 #### Scenario: 不进入沉默期的套餐 - **WHEN** 购买的是加油包、购买即生效套餐,或购买时资产已实名,或套餐未配置默认沉默期 - **THEN** 套餐记录 `silence_status` 为空,行为与现状一致 #### Scenario: 同一资产多笔套餐各自计算 - **WHEN** 同一张未实名卡在 09-01 与 09-20 各购买一笔实名即生效套餐 - **THEN** 两笔套餐的截止日分别按各自的支付日期计算,一笔过期不影响另一笔 ### Requirement: 套餐默认沉默期与是否支持延期配置 实名即生效套餐 MUST 配置默认沉默期 `silence_period_days`(1~90 天,新建时预填 30)与 `silence_extension_enabled`(默认支持);加油包 MUST NOT 写入沉默期;购买即生效正式套餐 MAY 选填默认沉默期(不强制,仅在店铺分配覆盖为 `from_activation` 时使用)。修改默认值 MUST 只影响之后的新购买,并写审计。系统 SHALL 提供"未配置沉默期的实名即生效套餐"清单(筛选与导出)。 配置口径中的"实名即生效套餐"指正式套餐本身为 `from_activation`,**或**存在未删除的店铺分配把它覆盖为 `from_activation`(存量数据)。后者 MUST 计入"未配置沉默期的实名即生效套餐"清单与总开关打开前检查"未配置默认沉默期的套餐"。 #### Scenario: 实名即生效套餐未填默认沉默期 - **WHEN** 新建或编辑 `from_activation` 套餐时未提供 `silence_period_days`,或值不在 1~90 - **THEN** 系统拒绝保存,返回 `silence_period_out_of_range` #### Scenario: 分配覆盖为实名即生效的购买即生效套餐 - **WHEN** 套餐本身为 `from_purchase`,但某店铺分配覆盖为 `from_activation`,且套餐未配置默认沉默期 - **THEN** 该套餐出现在未配置清单中并计入打开前检查;管理员可以为它配置默认沉默期,配置后该店铺的新购买进入沉默期,历史待实名记录可被回填 #### Scenario: 修改默认值不影响已购买记录 - **WHEN** 将套餐默认沉默期从 30 改为 45 - **THEN** 已有套餐记录的截止日不变,之后的新购买按 45 天计算 ### Requirement: 禁止绕过沉默期的生效条件变更 系统 MUST 在套餐服务与店铺分配(单个、批量、系列授权)写入路径的共用校验中阻断:套餐 `from_activation` 改为 `from_purchase`、分配覆盖把 `from_activation` 套餐改为 `from_purchase`、套餐未配置默认沉默期时分配覆盖把 `from_purchase` 套餐改为 `from_activation`(套餐已配置默认沉默期时放行)。套餐 `from_purchase` 改为 `from_activation` 时同一请求 MUST 提供默认沉默期。 #### Scenario: 实名即生效改为购买即生效 - **WHEN** 管理员把实名即生效套餐改为购买即生效,或在店铺分配上覆盖为购买即生效 - **THEN** 系统拒绝,返回 `package_expiry_base_change_forbidden` #### Scenario: 购买即生效套餐在分配上覆盖为实名即生效 - **WHEN** 管理员在店铺分配上把 `from_purchase` 套餐覆盖为 `from_activation` - **THEN** 套餐已配置默认沉默期时允许保存;未配置时拒绝,返回 `package_expiry_base_change_forbidden` ### Requirement: 后台购买时调整沉默期 后台给资产购买会进入沉默期的套餐时,有 `package_silence:override` 权限的运营 SHALL 可以设置本次沉默期(≥ 1 天,不设上限),必须填写原因;优先级为本次设置值高于套餐默认值。 - 设置值不超过默认值:直接生效。 - 设置值超过默认值:按匹配到的延期政策判断;未勾选免审批场景 `purchase_adjust`(含未匹配到政策)时,系统 MUST 先按默认值创建套餐记录,同时提交企微审批(申请类型"购买时调整沉默期"),并标记 `silence_adjust_pending = true`;勾选时直接按设置值生效。 - 审批中的套餐 MUST NOT 因到期而过期。审批通过后按 `起算日期 + 审批天数` 重算截止日;驳回或撤回保持默认值。审批结束后立即重新判定沉默期。 - 自动购包、钱包自动续费等无人参与的路径 MUST 只用默认值。 #### Scenario: 无权限传入调整值 - **WHEN** 无 `package_silence:override` 权限的账号在购买时传入沉默期 - **THEN** 系统拒绝,返回 `silence_override_forbidden` #### Scenario: 超默认值需审批 - **WHEN** 默认 30 天的套餐在后台购买时设置为 120 天,政策未设免审批 - **THEN** 套餐记录按 30 天设置截止日,`silence_adjust_pending = true`,并提交企微审批 - **AND** 审批期间超过 30 天截止日也不会过期 - **AND** 审批通过后截止日改为购买日期 + 120 天;若重算后已过截止且期内未实名,立即过期 #### Scenario: 超默认值且政策免审批 - **WHEN** 匹配到的延期政策勾选了 `purchase_adjust` - **THEN** 套餐记录直接按设置值计算截止日,不提交审批 ### Requirement: 实名与过期判定 系统 SHALL 用统一判定处理 `waiting` 的套餐记录:期内已实名则沉默期结束(`ended`),之后按现有逻辑激活;同资产已有生效主套餐时继续排队,排队期间不再受沉默期限制。已到期、期内未实名且无调整审批的,MUST 标记为 `expired`,`status` 保持 0,记录 `silence_expired_at`,写流水与审计。 实名时间取实际业务时间:卡取 `first_realname_at`;设备取所有已绑定且已实名卡中 `max(卡实名时间, 绑定时间)` 的最小值。卡当前已实名但 `first_realname_at` 为空时 MUST 视为期内已实名,并补写 `first_realname_at` 为判定时间。 判定入口包括:运营商实名观测与人工实名、卡绑定设备、排队接续、指定激活、孤儿套餐扫描、延期生效、调整审批结束、沉默期扫描。 #### Scenario: 截止日当天实名 - **WHEN** 截止日为 10-24 23:59:59,卡在 10-24 23:30 实名 - **THEN** 套餐 `silence_status = ended` 并按现有逻辑激活,有效期从激活时间起算 #### Scenario: 截止后实名 - **WHEN** 卡在 10-25 08:00 才实名 - **THEN** 套餐标记为 `expired`,不激活 #### Scenario: 截止后才绑定已实名卡的设备 - **WHEN** 设备套餐截止后,才绑定一张早已实名的卡 - **THEN** 设备实名时间取绑定时间,晚于截止日,套餐过期 #### Scenario: 期内实名但需排队 - **WHEN** 资产在截止前实名,但同资产已有生效主套餐 - **THEN** 这笔套餐 `silence_status = ended`、`status` 仍为 0 排队,之后按排队接续激活,不再因沉默期过期 #### Scenario: 实名时间为空的已实名卡 - **WHEN** 卡 `real_name_status` 为已实名但 `first_realname_at` 为空 - **THEN** 判定为期内已实名,不判过期,并补写 `first_realname_at` ### Requirement: 沉默期已过期的套餐不能激活 `silence_status = expired` 的套餐 MUST NOT 被任何激活入口激活。`ActivationService.canActivatePendingUsage` MUST 在现有实名判断前先执行沉默期判定,过期时返回不可激活。对外展示 MUST 显示"沉默期已过期(失效)"并返回截止日与过期时间。任何人 MUST NOT 通过修改时间或状态把 `expired` 恢复为 `waiting`;只能通过延期。 #### Scenario: 过期套餐实名后仍不激活 - **WHEN** 已过期套餐所属卡完成实名 - **THEN** 套餐不激活,仍为 `expired` #### Scenario: 已到期但尚未被扫描 - **WHEN** 套餐仍为 `waiting` 但已过截止日,此时触发任一激活入口 - **THEN** 入口先判定为过期,不激活 ### Requirement: 沉默期扫描 系统 SHALL 每 10 分钟运行 `package:silence:scan`,查询 `status = 0 AND silence_status = 'waiting' AND silence_deadline_at < now() AND silence_adjust_pending = false` 的记录(单批 200,最多 20 批,Unique 9 分钟,MaxRetry 3),逐条执行统一判定。状态更新 MUST 带期望状态条件并检查影响行数,重复执行幂等。扫描只在总开关打开时运行。 #### Scenario: 扫描与实时判定一致 - **WHEN** 扫描和实名事件同时处理同一条到期记录 - **THEN** 只有一方更新成功,结果一致,审计只写一次 ### Requirement: 沉默期总开关 系统 SHALL 提供系统配置 `package.silence.enabled`,默认关闭,仅超级管理员可切换,每次切换写审计 `package.silence_switch_changed`(操作人、前后值、检查结果)。 - 关闭时:新购买照常写入沉默期字段(只记录);不拦截激活、不扫描、不拦截退款、不展示沉默期与延期入口;延期资格、下单、线下登记、特殊延期申请返回 `silence_feature_disabled`;套餐与政策配置、审批模板配置、历史回填工具可用;购买时调整照常记录与提交审批。 - 打开前检查:实名即生效套餐全部已配置默认沉默期;没有"待实名、实名即生效主套餐、沉默期字段为空"的记录;存在启用中的"全部套餐"延期政策;企微审批场景 `package_silence_approval` 已配置启用。任一项不满足 MUST 拒绝打开,返回 `silence_switch_precheck_failed` 及未满足项与数量。 - 打开后:所有规则同时生效,扫描开始运行。 - 打开后再关闭:规则暂停、数据保留;已发生的付款回调、查单补偿与审批回调 MUST 照常处理完;关闭期间不接受新的延期申请。 #### Scenario: 默认关闭时行为不变 - **WHEN** 总开关关闭,未实名卡购买实名即生效套餐后超过截止日才实名 - **THEN** 套餐记录有截止日,但实名后照常激活,不判过期 #### Scenario: 检查未通过拒绝打开 - **WHEN** 仍有 3 个实名即生效套餐未配置默认沉默期时尝试打开 - **THEN** 系统拒绝,返回未满足项"未配置默认沉默期的套餐:3" #### Scenario: 应急关闭时处理进行中的付款 - **WHEN** 总开关打开后又关闭,此时一笔延期订单的支付回调到达 - **THEN** 回调照常处理并执行延期 ### Requirement: 历史数据回填 系统 SHALL 提供沉默期回填工具,可在总开关关闭时运行。前提是相关套餐的默认沉默期已补齐。回填范围为 `status = 0 AND pending_realname_activation = true` 的实名即生效主套餐记录;起算为该笔套餐的购买(支付成功)时间;天数取套餐默认沉默期;未配置的套餐不回填并列入清单。回填时 MUST 同时按实名时间判定,截止前已实名的直接记为 `ended`。不给上线宽限:截止早于上线日且期内未实名的,打开总开关后过期。 回填 MUST 先生成影响清单(套餐记录数、按代理与套餐分布、期内已实名数、实名时间为空的已实名数、将过期数、将过期且无法付费延期数),经业务确认后执行;每条写流水(backfill);可重复执行。 #### Scenario: 回填时已实名 - **WHEN** 历史套餐按购买时间算出的截止日之前,卡已实名 - **THEN** 回填记为 `ended`,不会过期 #### Scenario: 回填后截止日已过 - **WHEN** 历史套餐购买于 2026-03-01、默认 30 天,上线日为 2026-11-15,卡未实名 - **THEN** 回填截止日为 2026-03-31 23:59:59,打开总开关后第一轮扫描标记为过期 ### Requirement: 沉默期变更留痕 套餐沉默期的设置、调整、过期、结束、延期、换货迁移、回填 MUST 写入不可变流水 `tb_package_silence_record`(套餐记录、事件类型、变更前后状态与截止时间、天数、默认值快照、是否调整、操作人、原因、审批单号、延期明细、时间),并写对应审计事件。系统 SHALL 提供按套餐查询流水的接口。 #### Scenario: 查询一笔套餐的沉默期历史 - **WHEN** 查询某笔经历过购买、过期、延期的套餐流水 - **THEN** 依次返回 set、expired、extend 三条记录及前后截止时间