> 规则细节以 `docs/沉默期技术方案/实名即生效套餐沉默期技术方案_v3.md`(下称"技术方案")为准,任务中的 §n 指技术方案章节。测试环境是唯一验证面(PostgreSQL `junhong_cmp_test`、Redis DB 6、`Iteration` 分支部署、`cmp-test` 日志);迁移用 `~/go/bin/migrate` 与 `.env` 的 `DB_*`;fixture 只创建 / 删除本变更自己的记录;只读诊断用 dbhub。 ## 1. 数据层(§3、§13.1、§17.2) - [x] 1.1 迁移①:`tb_package_usage` 新增 10 个沉默期字段(`silence_status`、`silence_start_at`、`silence_period_days`、`silence_deadline_at`、`silence_extended_days`、`silence_paid_extended_days`、`silence_extension_count`、`silence_free_extension_used`、`silence_expired_at`、`silence_adjust_pending`),计数类 `NOT NULL DEFAULT 0`,布尔 `NOT NULL DEFAULT false`,带列注释;成对 down - [x] 1.2 迁移②:部分索引 `idx_package_usage_silence_scan (silence_deadline_at, id) WHERE deleted_at IS NULL AND status = 0 AND silence_status = 'waiting'` - [x] 1.3 迁移③:`tb_package` 新增 `silence_period_days`(可空)、`silence_extension_enabled`(`NOT NULL DEFAULT true`) - [x] 1.4 迁移④:新建 `tb_package_silence_extension_policy`、`tb_package_silence_record`、`tb_package_silence_extension_order`、`tb_package_silence_extension_batch`、`tb_package_silence_extension`,含 §7.1 / §7.2 的唯一约束与部分唯一索引(同一套餐最多一笔未结束订单、线下收款方式 + 交易单号唯一、`UNIQUE(batch_id, package_usage_id)`、同一套餐最多一条未结束明细) - [x] 1.5 迁移⑤⑥:插入默认延期政策(全部套餐、长期、500 分/月、免费 1 次、累计 6 个月、单次不限、无免审批场景);插入系统配置 `package.silence.enabled`(false)、`package.silence.default_days`(30)、`package.silence.extension_unit_price`(500) - [x] 1.6 迁移⑦:扩展 `tb_wecom_approval_scene.chk_wecom_approval_scene_business`,在 `000216` 现有白名单基础上加入 `package_silence_approval`;down 恢复原白名单 - [x] 1.7 迁移⑧⑨:`tb_iot_card`、`tb_device` 新增 `first_purchase_at timestamptz NULL` 与索引;新建 `tb_asset_first_purchase_record`(`UNIQUE(asset_type, asset_id, generation)`) - [x] 1.8 测试库执行 `up → down → up`,确认约束、索引、默认数据正确 - [x] 1.9 模型:`PackageUsage`、`Package`、`IotCard`、`Device` 增加字段;新增 6 个表的模型 - [x] 1.10 Store:延期政策、沉默期流水、延期订单、批次、明细、首次购买套餐记录的 Store(条件更新方法返回影响行数) - [x] 1.11 常量与错误码:`silence_status` 取值、延期路径与类型、免审批场景枚举、`order_type = silence_extension`、审批业务类型 `package_silence_approval`、审计动作(§11.2)、权限点(§11.1)、错误码(§12.5) ## 2. 领域规则(§4.2、§5.2、§8.2、§3.6) - [x] 2.1 `internal/domain/package/silence.go`:`SilenceDeadline(date, days)`(当日 23:59:59,Asia/Shanghai) - [x] 2.2 沉默期判定:输入当前状态、截止时间、实名时间、是否有调整审批、当前时间,输出 wait / end / expire / noop - [x] 2.3 延期报价:输入截止日、今天、输入天数、政策快照、已付费延期天数、延期类型,输出 overdue、min/max 天数与月数、计费月数与天数、金额、新截止日、能否办理与原因 - [x] 2.4 政策匹配(指定套餐 > 系列 > 全部,启用且在生效期)与同级重叠校验;免审批判断 - [x] 2.5 用 §8.2 示例表四种情况、输入 1/30/31/60 天、跨月跨年日期在测试环境调用路径中核对一次结果(不写自动化测试) - 核对结果(2026-10-27,临时程序调用领域函数,已删除):截止 10-01 时 10-20 / 12-15 / 次年 03-20 / 次年 04-05 分别为 overdue 19/75/170/186、min 1/3/6/7、max 6/6/6/6,选最少新截止 10-31 / 12-30 / 03-30,第四种 `exceeds_limit`;输入 1/30/31/60 天计费 30/30/60/60;09-24 10:00 + 30 → 10-24 23:59:59;跨年 12-20 + 30 → 01-19,跨月 01-31 + 30 → 03-02;判定:截止当天 23:30 实名 → end、截止后实名 → expire、已实名无时间 → end 并补写、调整审批中 → 不过期。 ## 3. 套餐配置(§3.2、§3.3) - [x] 3.1 套餐新增 / 编辑 DTO 与校验:实名即生效套餐必填 `silence_period_days`(1~90)、`silence_extension_enabled`;普通套餐禁止写入;修改默认值写审计 `package.silence_default_changed` - [x] 3.2 生效条件变更约束:套餐服务与店铺分配(单个、批量、系列授权)共用校验函数,阻断 §3.3 的三种变更,`from_purchase → from_activation` 要求同时提供默认沉默期 - [x] 3.3 "未配置沉默期的实名即生效套餐"列表接口(筛选、导出) - [ ] 3.4 分配覆盖口径(design D11):共用条件"正式套餐本身 `from_activation` 或存在未删除的分配覆盖为 `from_activation`",用于未配置清单(列表、导出)与打开前检查;购买即生效正式套餐允许选填默认沉默期(不强制),加油包仍禁止;分配覆盖 `from_purchase → from_activation` 在套餐已配置默认沉默期时放行(单个、批量、系列授权共用校验) - [ ] 3.5 测试环境核对:套餐 708 / 710 / 712 出现在未配置清单与打开前检查中;配置默认沉默期后回填套餐记录 20005;未配置时分配覆盖为实名即生效被拒绝,配置后放行 ## 4. 沉默期设置、判定与激活拦截(§4、§5) - [x] 4.1 应用层 `internal/application/packagesilence/resolve.go`:`ResolveUsageSilence`(加锁、读实名事实、条件更新、写流水与审计);实名时间按 §5.1(卡 `first_realname_at`;设备取绑定卡 `max(实名, 绑定)` 的最小值;已实名但时间为空的视为期内并补写) - [x] 4.2 订单 `activatePackage` 与自动购包 `activatePackages`:创建套餐记录时按 §4.1 设置沉默期并写流水(总开关关闭也写) - 备注:除订单 `activatePackage` 与自动购包 `activatePackages` 外,钱包自动续费(`internal/application/assetautorenewal/renew.go`)也创建套餐记录,同样接入(无人参与,只用默认值);三处都在创建记录的同一事务内调用 `packagesilence.Setter.ApplyOnUsageCreatedInTx`。 - [x] 4.3 后台购买:DTO 增加 `silence_period_days`、`silence_reason`;权限 `package_silence:override`;超默认值按政策决定直接生效或提交调整审批(`silence_adjust_pending = true`);无人参与路径只用默认值 - 备注:审批实例 `(business_type, business_id)` 唯一,三种申请共用 `package_silence_approval`,因此购买时调整也建一个批次(`path = adjust`,迁移 000262 已含该取值与 `adjust_*` 字段),审批统一关联批次 ID。调整值经上下文传入 `activatePackage`(后台下单为钱包 / 线下即时支付,同一请求内发放套餐)。 - [x] 4.4 `canActivatePendingUsage` 在实名判断前调用 `ResolveUsageSilence`(仅总开关打开时拦截) - 备注:`ActivateByRealname` 不经过 `canActivatePendingUsage`,同样在主套餐激活前加了闸门;挂在过期主套餐下的待实名加油包随主套餐不激活(D21)。 - [x] 4.5 `getNextPendingMainPackage` 跳过 `silence_status = expired`;`findAndActivateOrphanPackages` 候选查询排除 `expired`(总开关打开时) - [x] 4.6 全局排查 `PackageUsageStatusPending` 的 42 处查询,逐一确认过期套餐的处理(激活、排队、展示、统计、停复机评估、换货、退款),在任务备注中列出结论 - 排查结论(2026-10-27): - 需改并已改:激活闸门 `canActivatePendingUsage`、实名激活 `ActivateByRealname`、排队队首 `getNextPendingMainPackage`、主套餐到期后提交下一个激活任务 `polling.activateNextPackage`、孤儿扫描 `findAndActivateOrphanPackages`、加油包挂靠 `FindAttachableMainPackageForAddon`(过期主套餐不能再挂加油包)、退款申请创建(4.7)。 - 不改(过期仍按待生效处理是正确的):换货迁移 `migration.go:105`(随记录迁移)、退款 / 资产失效 `InvalidatePackagesForRefund`、`InvalidateAllPackagesByAsset`(失效照常)、加油包级联失效、实名轮询范围 `polling_realname_scope.go`(过期后仍需采集实名时间,延期后才能判定期内已实名并立即激活)、订单 / 自动购包 / 续费创建时的状态赋值、套餐到期提醒与续费查询 `query/packageexpiry`、`query/assetautorenewal`、运营报表 `domain/operationsreport`(统计口径不变)、`HasPendingPackageUsage`(优先轮询收敛条件)、`agent_open_api` 与各展示处的状态名(展示在 4.8 处理)。 - 已知影响:资产若只有一笔沉默期已过期的待生效主套餐,钱包自动续费资格仍按"存在待生效主套餐"拦截(与现状一致,不在本变更范围)。 - [x] 4.7 退款申请创建拦截 `silence_status = expired`(总开关打开时),返回 `silence_expired_not_refundable` - [x] 4.8 资产套餐列表 / 详情(后台与 H5)增加沉默期字段与状态名;`waiting` 但已过截止的展示为"沉默期已过期";总开关关闭时不返回沉默期展示字段与延期入口标记 - [x] 4.9 套餐沉默期流水查询接口 ## 5. 扫描任务与总开关(§3.7、§5.4) - [x] 5.1 定时任务 `package:silence:scan`:每 10 分钟、单批 200、最多 20 批、Unique 9 分钟、MaxRetry 3;只在总开关打开时处理;注册到 worker 与调度 - [x] 5.2 总开关读取(系统配置缓存)与各入口的统一判断函数 - [x] 5.3 总开关写接口(仅超级管理员):打开前 4 项检查,不满足返回 `silence_switch_precheck_failed` 与未满足项数量;切换写审计 `package.silence_switch_changed` - [x] 5.4 关闭时延期资格、下单、线下登记、特殊延期申请返回 `silence_feature_disabled`;已发生的支付回调、查单、审批回调不受开关影响 ## 6. 延期政策(§3.6) - [x] 6.1 政策应用层:列表、详情、新增、编辑、启停、查询某套餐当前匹配政策;保存时重叠校验;写审计 - [x] 6.2 后台 Handler 与路由,权限 `package_silence:policy` ## 7. 延期办理(§7、§8) - [x] 7.1 延期资格接口(后台与 H5):按 §12.2 返回全部字段;前置条件与原因码 - [x] 7.2 在线下单(H5 自助):参照 `agentrecharge/online_creation.go`,创建延期订单、批次、明细与 `tb_payment`,商户池路由并 `FreezeRoute`,冻结政策快照与金额 - [x] 7.3 后台二维码:运营创建订单(上传申请依据),调用渠道适配器生成支付内容写入 `qr_content` 返回;已有待支付订单时先查单,未付关闭旧单、已付不新建 - [x] 7.4 支付回调:`internal/handler/callback/payment.go` 按 `order_type = silence_extension` 分发到延期用例;金额核对;`pending_payment → paid → completed` 条件更新幂等 - [x] 7.5 支付恢复:未支付订单查单与超时关闭(参照 `recover_online_payment.go`),处理"订单不存在" - [x] 7.6 线下登记:参照 `offline_creation.go`,收款方式字典、交易单号唯一、实收金额等于计算金额、凭证;按政策快照决定提交审批或直接执行;权限 `package_silence:offline` - [x] 7.7 特殊延期:单个申请与批量导入(Excel 明细、逐行校验);免费次数校验与并发控制;优惠价登记收款信息;按政策快照决定审批或直接执行;批量权限 `package_silence:extend_batch` - [x] 7.8 延期执行用例(§8.6):同事务锁载体与套餐、重校验、更新字段、写明细 / 批次 / 流水 / 审计;提交后调用 `ResolveUsageSilence`;以明细状态条件更新保证幂等 - [x] 7.9 执行异常:明细 `exception`;在线订单按冻结商户原路退款(复用退款渠道适配)并写订单退款字段;后台异常明细重试 / 关闭接口,权限 `package_silence:exception` - [x] 7.10 确认延期订单不触发佣金计算、不计入代理累计充值与业绩 ## 8. 企微审批(§11.3) - [x] 8.1 接入 `internal/application/approval` 创建与可靠提交:业务类型 `package_silence_approval`,申请类型控件与三种申请的表单映射(§11.3 表);发起人未绑定企微成员拒绝提交 - [x] 8.2 回调分发:按审批实例关联的调整申请 / 延期批次 / 延期订单处理通过、驳回、撤回;重复事件只处理一次 - [x] 8.3 调整审批通过后重算截止日并调用 `ResolveUsageSilence`;驳回保持默认值并立即判定 ## 9. 换货与首次购买套餐时间(§9、§17) - [x] 9.1 换货迁移写沉默期流水(换货单号、前后资产、截止时间);确认 `expired` 记录随迁移且不重算 - [x] 9.2 首次购买套餐时间写入函数:订单 `activatePackage` 与自动购包入口调用;条件 `first_purchase_at IS NULL AND generation = 订单世代`;绑定在设备上的卡跳过;影响行数为 1 时插入首次购买套餐记录 - [x] 9.3 换货:旧资产世代 +1 的同一事务清空 `first_purchase_at` 并结束旧记录;换货后的新资产不因换货写入,当前世代真正购买套餐时才记录 - 备注(2026-10-27):按业务决定取消"新资产写换货完成时间与 `exchange` 记录",并把"出库时间"更名为"首次购买套餐时间"(字段 `first_purchase_at`、表 `tb_asset_first_purchase_record`、接口 `/first-purchase-records`),迁移 000266 在测试库已 up → down → up。 - [x] 9.4 卡 / 设备列表返回并可按首次购买套餐时间筛选;详情与资产解析返回;导出增加"首次购买套餐时间"列;首次购买套餐记录查询接口 ## 10. 展示、导出、文档与回填工具(§12、§6、§17.4) - [x] 10.1 延期订单列表、详情、导出(字段与线上订单一致);H5 我的延期订单;即将过期 / 已过期套餐列表与导出;延期批次与明细查询 - [x] 10.2 财务交易流水(`internal/query/audit/finance.go`)纳入延期订单支付类型 - [x] 10.3 新增 Handler 同步路由、`cmd/api/docs.go`、`cmd/gendocs/main.go`,重新生成 OpenAPI 文档 - [x] 10.4 沉默期回填工具(`cmd/`):`--dry-run` 输出影响清单(§6 第 7 条各项);执行模式分批、只处理空值、可重复执行、按实名时间判定 `ended`、写流水 - [x] 10.5 首次购买套餐时间回填工具:按当前世代最早已支付 / 已退款套餐订单回填,排除绑定在设备上的卡,插入 `backfill` 记录,输出可回填数与无订单数 - [x] 10.6 前端接口变更说明(新增接口、字段、错误码、总开关对页面的影响) - [x] 10.7 `gofmt`、`go build ./...`、`go vet`、`openspec validate add-package-silence-period` ## 11. 测试环境验证(§14、§17.6) - [x] 11.1 部署后确认总开关关闭时行为不变:新购买写入沉默期字段,过期后实名仍激活,延期接口返回 `silence_feature_disabled` - 验证结果(2026-10-27,部署 `69ec98aa`):总开关 `enabled=false`;代理 539 未实名卡 8019 后台钱包购买验证套餐 823(订单 892)→ 套餐记录 20175 `waiting`、30 天、截止 2026-11-26 23:59:59,流水 `set / order_paid`,首次购买套餐时间与记录写入;资格、试算、二维码下单、线下登记、特殊延期均返回 1274,未产生延期订单 / 批次 / 明细;把 20175 截止改为 2026-10-20 后将卡标为已实名,孤儿扫描 10 秒内激活(status=1),`silence_status` 保持 `waiting`、不写判定流水。 - 发现并修复(`69ec98aa`):后台平台自营资产与赠送套餐线下订单 `buyer_type=personal`,`activateMainPackage` 误判为 C 端购买,未实名也直接生效、不进沉默期;增加 `order.Source == client` 条件后,代理卡 8030 线下购买赠送套餐 824(订单 893)→ 记录 20176 待实名、`waiting`、30 天。 - 待 11.10 清理:套餐 822 / 823 / 824、分配 288、订单 891(卡 11895)/ 892(卡 8019,代理 539 钱包扣 1 分)/ 893(卡 8030)及其套餐记录、沉默期流水、首次购买套餐时间与记录;卡 8019 恢复 `real_name_status=0`、`first_realname_at=NULL`、`enable_polling=true`。 - [ ] 11.2 总开关打开前检查:逐项制造不满足条件,确认拒绝及返回内容;全部满足后打开成功并写审计 - [ ] 11.3 沉默期设置、购买时调整(直接生效 / 审批通过 / 驳回 / 免审批)、实名与过期判定(§14 第 1~12 条) - [ ] 11.4 延期资格与计费(§14 第 13~15 条,含示例表四种情况) - [ ] 11.5 四种延期办理(§14 第 16~21 条):H5 微信或支付宝真实小额支付、后台二维码扫码、线下登记审批、特殊与免费延期、批量部分失败、跨天支付异常退款 - [ ] 11.6 延期政策与免审批开关(§14 第 22~23 条) - [ ] 11.7 换货与历史回填(§14 第 24~25 条):回填 dry-run 清单与执行、重复执行结果不变 - [ ] 11.8 首次购买套餐时间(§17.6 全部场景) - [ ] 11.9 应急关闭:打开后关闭,确认规则暂停、数据保留、进行中支付回调照常完成 - [ ] 11.10 清理本变更创建的测试数据,记录验证结果到本文件 ## 实施备注(2026-10-27) - 迁移编号 000259~000266(000266 为首次购买套餐时间更名;测试库 `junhong_cmp_test` 已执行 up → down 7 → up,默认政策、三项系统配置、扫描索引、部分唯一索引、审批白名单核对正确)。 - 审批关联:三种申请共用 `package_silence_approval`,审批实例 `business_id` 统一为批次 ID;购买时调整也建批次(`path = adjust`),线下付费的批次与订单一一对应。 - H5 自助与后台二维码都复用代理在线充值的渠道适配器 `CreatePaymentURL`,返回 `qr_content`(支付链接 / 二维码内容),未新增 JSAPI 支付方式。 - 在线订单执行异常(跨天、金额不一致、订单关闭后到账等)自动按冻结商户原路退款,恢复任务 `package:silence:order_recover` 每 5 分钟重试;线下与特殊延期的异常只能人工重试或关闭。 - 支付截止时间不跨天(不晚于当天 23:59:59),降低跨天支付进入异常的概率。 - 总开关在通用系统配置接口中只读,只能通过 `PUT /api/admin/package-silence/switch` 切换;进程内缓存 5 秒。 - 回填工具:`cmd/silence-backfill`(`-target silence|first_purchase`,默认只出清单,`-execute` 执行);2026-10-27 在测试库 dry-run:沉默期候选 1 条(套餐未配置默认沉默期、不回填),首次购买套餐时间可回填卡 9 / 设备 6、无订单卡 7、绑定在设备上的卡 15。 - 前端说明:`docs/2026-10-27-实名即生效套餐沉默期-前端接口变更说明.md`。