Files
junhong_cmp_fiber/openspec/changes/add-package-silence-period/proposal.md
邹进 909f4d0ec2
Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Failing after 8m39s
feat: 实名即生效套餐沉默期、延期办理与资产出库时间
- 迁移 000259~000265:套餐记录沉默期字段与扫描索引、套餐默认沉默期、延期政策/流水/订单/批次/明细 5 张表、默认政策与系统配置(总开关默认关闭)、企微审批白名单、卡与设备出库时间及出库记录
- 沉默期设置(订单发放、自动购包、钱包续费)、后台购买时调整(超默认值按政策免审或企微审批)、统一判定与激活闸门、排队与孤儿扫描跳过过期套餐、过期套餐禁止退款、每 10 分钟扫描
- 总开关专用接口与打开前 4 项检查;延期政策;延期资格与计费;H5 自助与后台二维码在线支付(商户池路由)、支付回调与查单恢复、线下登记、特殊/批量延期、异常重试与原路退款;沉默期审批场景与终态处理
- 换货沉默期流水与出库时间;卡/设备列表、详情、导出与出库记录接口;延期订单与即将过期套餐列表及导出;财务流水纳入延期支付
- 沉默期与出库时间回填工具 cmd/silence-backfill;前端接口变更说明

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 16:32:58 +09:00

41 lines
5.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## Why
实名即生效套餐在资产实名前一直处于待生效,现在没有任何期限:客户买了套餐长期不实名,套餐永远挂着,既不能失效也不能收取延期费用。业务已确认《实名即生效套餐沉默期规则需求确认稿_10.16》及 10-27 的补充决定,需要为这类套餐加上沉默期:期限内实名正常生效,过期失效,失效后可付费或经审批延期。同时卡与设备需要记录出库时间(首次购买套餐时间)用于展示。技术方案见 `docs/沉默期技术方案/实名即生效套餐沉默期技术方案_v3.md`(以下简称"技术方案"),规则以技术方案为准。
## What Changes
- **沉默期按每笔套餐计算**:实名即生效主套餐在资产未实名时购买,从支付成功起计算沉默期,截止日当天 23:59:59 到期;字段建在套餐记录上,资产上不建沉默期字段。
- **套餐配置**:实名即生效套餐必填默认沉默期(1~90 天,新建预填 30)和"是否支持延期";禁止把实名即生效套餐改成购买即生效(套餐与店铺分配两处);存量套餐由业务在后台补齐。
- **后台购买时调整沉默期**:默认值以内直接生效;超过默认值默认需企微审批(先按默认值购买,审批中不过期,通过后重算),不设上限。
- **过期与激活拦截**:截止前实名正常激活(或排队);截止后仍未实名标记为"沉默期已过期",套餐状态保持待生效,由激活入口统一拦截;排队与孤儿套餐恢复跳过过期套餐;过期套餐不能退款。每 10 分钟扫描到期套餐。
- **沉默期总开关**:默认关闭;关闭时只记录沉默期、不执行任何规则;参数配置与历史回填完成、通过打开前检查后由超级管理员打开;可应急关闭。
- **延期政策(可配置)**:适用范围(全部 / 系列 / 指定套餐)、每月单价、免费延期次数、付费累计与单次最多月数、免审批场景(多选)、生效时间、启停;预置默认政策(5 元/月、免费 1 次、累计 6 个月)。
- **延期计费**:从原截止日往后加;客户按天输入,按每月 30 天向上取整计费,延长天数等于计费天数;系统计算最少 / 最多天数,最少超过最多则不能付费延期。
- **四种延期办理**:H5 自助与后台二维码(在线支付、商户池路由、不审批);线下付款登记(默认审批,可配免审批);特殊延期(免费、优惠、补偿、特殊客户、批量;默认审批,可配免审批,不设上限)。延期订单单独建表,记录支付方式、收款商户、交易流水号或线下收款信息;延期费不分佣、不退(执行异常除外)。
- **企微审批**:新增一个审批场景,用"申请类型"区分购买时调整、特殊延期、线下付费延期。
- **换货**:沉默期字段随套餐迁移,不重新起算。
- **历史回填**:按购买时间起算,不给上线宽限;截止前已实名的记为已结束;先出影响清单,业务确认后执行。
- **出库时间**:卡、设备新增出库时间(当前世代首次购买套餐的支付时间)与出库记录表;设备上绑定的卡不记;换货新资产取换货完成时间;只做记录展示,不受总开关控制。
- 不做通知提醒(确认稿第七节不实现)。
## Capabilities
### New Capabilities
- `package-silence-period`:实名即生效套餐沉默期的设置、购买时调整、实名与过期判定、激活拦截、扫描、总开关与历史回填。
- `package-silence-extension`:延期政策、延期资格与计费、四种延期办理、延期订单与支付、企微审批与免审批、延期执行与异常处理。
- `asset-outbound-time`:卡与设备的出库时间与出库记录。
### Modified Capabilities
- `package-queue-activation`:排队接续与孤儿待生效套餐恢复必须跳过沉默期已过期的套餐。
- `order-refund-exchange`:沉默期已过期的套餐不能申请退款;换货迁移时沉默期随套餐迁移、不重新起算。
## Impact
- 数据库:迁移 9 项(技术方案 §13.1)——`tb_package_usage` 新增 10 个沉默期字段与扫描索引;`tb_package` 新增 2 个字段;新建延期政策、沉默期流水、延期订单、延期批次、延期明细 5 张表;默认政策与系统配置(含总开关,默认关闭);扩展企微审批场景业务类型白名单;`tb_iot_card`、`tb_device` 新增出库时间与出库记录表。总开关关闭前不改变任何现有行为。
- 代码:套餐服务与分配、订单支付后发放套餐(`internal/service/order/service.go`、`internal/task/auto_purchase.go`)、激活服务(`internal/service/package/activation_service.go`)、排队与孤儿扫描(`internal/polling/package_activation_handler.go`)、退款、换货、支付回调(`internal/handler/callback/payment.go`)、商户池与支付渠道适配、企微审批(`internal/application/approval/`)、新应用层 `internal/application/packagesilence/`、领域规则 `internal/domain/package/`、定时任务、后台与 H5 Handler、导出、财务流水。
- 接口:新增延期政策、延期资格、延期下单、线下登记、特殊延期、延期订单查询、总开关、出库记录等接口;套餐、购买、资产套餐、卡与设备列表和详情增加字段。H5 新增延期入口。
- 数据:上线后先补齐套餐默认沉默期,再执行历史回填与出库时间回填;打开总开关后,截止已过且期内未实名的历史套餐会失效(不给宽限)。
- 运营配置:延期政策、企微审批模板、权限分配、商户池与线下收款方式检查(技术方案 §18.3)。