Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Failing after 8m39s
- 迁移 000259~000265:套餐记录沉默期字段与扫描索引、套餐默认沉默期、延期政策/流水/订单/批次/明细 5 张表、默认政策与系统配置(总开关默认关闭)、企微审批白名单、卡与设备出库时间及出库记录 - 沉默期设置(订单发放、自动购包、钱包续费)、后台购买时调整(超默认值按政策免审或企微审批)、统一判定与激活闸门、排队与孤儿扫描跳过过期套餐、过期套餐禁止退款、每 10 分钟扫描 - 总开关专用接口与打开前 4 项检查;延期政策;延期资格与计费;H5 自助与后台二维码在线支付(商户池路由)、支付回调与查单恢复、线下登记、特殊/批量延期、异常重试与原路退款;沉默期审批场景与终态处理 - 换货沉默期流水与出库时间;卡/设备列表、详情、导出与出库记录接口;延期订单与即将过期套餐列表及导出;财务流水纳入延期支付 - 沉默期与出库时间回填工具 cmd/silence-backfill;前端接口变更说明 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
122 lines
16 KiB
Markdown
122 lines
16 KiB
Markdown
> 规则细节以 `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` 新增 `outbound_at timestamptz NULL` 与索引;新建 `tb_asset_outbound_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 "未配置沉默期的实名即生效套餐"列表接口(筛选、导出)
|
||
|
||
## 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` 与自动购包入口调用;条件 `outbound_at IS NULL AND generation = 订单世代`;绑定在设备上的卡跳过;影响行数为 1 时插入出库记录
|
||
- [x] 9.3 换货:旧资产世代 +1 的同一事务清空 `outbound_at` 并结束旧记录;新资产写换货完成时间与 `exchange` 记录
|
||
- [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)
|
||
|
||
- [ ] 11.1 部署后确认总开关关闭时行为不变:新购买写入沉默期字段,过期后实名仍激活,延期接口返回 `silence_feature_disabled`
|
||
- [ ] 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~000265(测试库 `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|outbound`,默认只出清单,`-execute` 执行);2026-10-27 在测试库 dry-run:沉默期候选 1 条(套餐未配置默认沉默期、不回填),出库时间可回填卡 9 / 设备 6、无订单卡 7、绑定在设备上的卡 15。
|
||
- 前端说明:`docs/2026-10-27-实名即生效套餐沉默期-前端接口变更说明.md`。
|