- 字段 outbound_at → first_purchase_at,记录表 tb_asset_outbound_record → tb_asset_first_purchase_record,接口 /outbound-records → /first-purchase-records,筛选参数与导出列同步更名 - 换货后的新资产不因换货写入,在当前世代真正支付套餐订单时才记录;记录来源只保留 order / backfill,去掉换货单字段 - 迁移 000266 重命名列、表、索引与约束;同步 Spec、设计、任务与前端接口变更说明 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
9.6 KiB
实名即生效套餐沉默期 — 前端接口变更说明
对应 OpenSpec Change
add-package-silence-period;规则以docs/沉默期技术方案/实名即生效套餐沉默期技术方案_v3.md为准。接口字段以docs/admin-openapi.yaml为准,本文只说明页面要做什么。
1. 总开关对页面的影响
沉默期总开关 package.silence.enabled 默认关闭。
| 页面 / 功能 | 关闭时 | 打开时 |
|---|---|---|
资产套餐列表、H5 套餐历史里的 silence 对象 |
不返回(字段为空),页面不显示沉默期 | 返回,显示状态、截止日 |
| "延期"入口 | 不显示 | silence.extendable = true 时显示 |
| 延期资格、试算、下单、线下登记、特殊延期 | 返回错误码 1274 | 可用 |
| 套餐默认沉默期、延期政策、企微审批场景配置 | 可用 | 可用 |
| 购买时调整沉默期 | 可用 | 可用 |
| 卡 / 设备首次购买套餐时间 | 不受开关影响 | 不受开关影响 |
后台"系统配置"通用接口不能修改总开关(只读),请用专用接口:
GET /api/admin/package-silence/switch:当前值 + 打开前 4 项检查(precheck[]:code、name、passed、count)。PUT /api/admin/package-silence/switch{ "enabled": true|false }:仅超级管理员。打开前检查不通过返回 1275,data.failed_items为未满足项,直接展示即可;关闭不检查。
2. 套餐配置
- 新增 / 编辑套餐增加
silence_period_days(1~90)、silence_extension_enabled(默认 true)。- 实名即生效的正式套餐必填默认沉默期,新建时前端预填 30;不填或越界返回 1260。
- 购买即生效套餐、加油包不显示、不提交这两个字段。
- 套餐响应增加
silence_period_days、silence_extension_enabled、silence_config_required(是否必须配置)。 - 实名即生效套餐改为购买即生效、店铺分配(单个、批量、系列授权)里覆盖为与套餐不同的生效条件,返回 1262。购买即生效改为实名即生效时,同一请求必须带
silence_period_days。 - "未配置沉默期的实名即生效套餐"清单:套餐列表加
silence_unconfigured=true;导出用套餐导出场景,筛选同样传silence_unconfigured。套餐导出新增"默认沉默期(天)""是否支持付费延期"两列。
3. 后台购买时调整沉默期
POST /api/admin/orders(后台给资产购买套餐)新增可选字段:
silence_period_days(≥ 1,不设上限)、silence_reason(设置时必填)。- 需要
package_silence:override权限,无权限传值返回 1261。 - 不超过默认值:直接生效;超过默认值:按延期政策直接生效,或先按默认值购买并提交企微审批(审批中套餐不会过期)。发起人未绑定企微成员时购买被拒。
- 只对"资产未实名时购买的实名即生效主套餐"生效,其他情况忽略。
4. 资产套餐展示
后台资产套餐历史 / 当前套餐、H5 套餐历史(/api/c/v1/asset/package-history)每笔套餐增加 silence 对象(总开关打开且适用沉默期时返回):
| 字段 | 说明 |
|---|---|
silence_status / silence_status_name |
waiting 待实名(延期后显示"延期待实名")/ expired 沉默期已过期 / ended 沉默期已结束;待实名但已过截止的直接按 expired 返回 |
silence_deadline_at、silence_start_at、silence_period_days |
截止时间(截止日 23:59:59)、起算时间、天数 |
silence_extended_days、silence_paid_extended_days、silence_extension_count、silence_free_extension_used |
延期累计 |
silence_expired_at、silence_adjust_pending |
过期时间、调整审批中 |
extendable |
是否显示"延期"入口 |
套餐沉默期流水:后台 GET /api/admin/package-silence/records?package_usage_id=,H5 GET /api/c/v1/package-silence/records?package_usage_id=。
5. 延期(后台)
均在 /api/admin/package-silence 下:
| 接口 | 权限 | 说明 |
|---|---|---|
GET /eligibility?package_usage_id= |
— | 资格:can_extend、special_extension_available、reason、min_days/max_days、min_months/max_months、unit_price、options[](每档计费天数、金额、新截止日)。金额全部由后端算,前端只传天数 |
GET /quote?package_usage_id=&days= |
— | 输入天数试算(按 30 天向上取整:1→30、31→60) |
POST /orders/qrcode |
package_silence:extend |
运营生成支付二维码:入参 package_usage_id、days、payment_method(wechat/alipay)、request_id、evidence_refs;返回 qr_content 渲染为二维码。已有客户 H5 待支付订单时后端先查单,未付自动关闭旧单 |
POST /orders/offline |
package_silence:offline |
登记线下付款:offline_payment_method_id(线下收款方式字典)、offline_trade_no、paid_amount(必须等于计算金额,否则 1273)、paid_at、payment_voucher_keys(1~5)、evidence_refs、request_id。交易单号重复 1272。默认进企微审批 |
GET /orders、GET /orders/:id |
— | 延期订单列表 / 详情,含 payment_method、payment_merchant_name、third_party_trade_no;导出场景 package_silence_order |
POST /special |
package_silence:extend(批量另需 package_silence:extend_batch) |
特殊延期:extension_type(free/discount/complaint_compensation/system_compensation/special_customer)、items[](package_usage_id + days)、reason、basis、evidence_refs、amount(免费为 0)、优惠价有收款时填收款方式 / 交易单号 / 凭证。批量明细逐行校验,不通过返回 data.rows[](行号与原因)。免费次数用完 1267 |
GET /batches、GET /batches/:id |
— | 批次与明细(has_exception=true 只看含异常的) |
POST /extensions/:id/handle |
package_silence:exception |
异常明细 `action=retry |
| `GET /usages?view=expiring | expired | all` |
延期政策(package_silence:policy):GET/POST /policies、GET/PUT /policies/:id、PUT /policies/:id/status、GET /policies/match?package_id=。同级重叠返回 1269。
6. 延期(H5)
均在 /api/c/v1/package-silence 下,资产须属于当前客户:
GET /eligibility、GET /quote:同后台。POST /orders:自助下单(package_usage_id、days、payment_method、request_id),返回qr_content(支付链接或二维码内容);支付成功自动延期。GET /orders、GET /orders/:id:我的延期订单。GET /records:沉默期流水。
7. 退款
沉默期已过期的套餐申请退款返回 1268(总开关打开时)。
8. 卡 / 设备首次购买套餐时间
- 卡列表、设备列表返回
first_purchase_at,支持first_purchase_start、first_purchase_end(RFC3339)筛选;卡详情、设备详情、资产解析返回first_purchase_at。 - 卡、设备导出末尾新增"首次购买套餐时间"列。
- 首次购买套餐记录:
GET /api/admin/assets/:asset_type/:id/first-purchase-records(asset_type 为 card / device),按世代倒序,含来源(首次购买套餐 / 历史回填)、订单号、结束时间与原因。 - 换货后的新资产不会因换货得到首次购买套餐时间,要等它在当前世代真正支付套餐订单;旧资产换货回库后该时间清空,旧世代记录带结束时间与原因"换货回库"。
- 绑定在设备上的卡不记录首次购买套餐时间;只读,不提供修改。
9. 错误码
| 码 | 名称 | 说明 |
|---|---|---|
| 1260 | silence_period_out_of_range | 沉默期天数不在允许范围 |
| 1261 | silence_override_forbidden | 无权限调整沉默期 |
| 1262 | package_expiry_base_change_forbidden | 不允许变更该套餐的生效条件 |
| 1263 | silence_extension_not_expired | 套餐未过期 / 无沉默期 / 已激活 / 已退款(data.reason 细分) |
| 1264 | silence_extension_disabled | 该套餐不支持付费延期(可申请特殊延期) |
| 1265 | silence_extension_exceeds_limit | 超过可延期期限(data.min_months、data.max_months) |
| 1266 | silence_extension_months_invalid | 延期天数不在允许范围(data.min_days、data.max_days) |
| 1267 | silence_free_extension_used_up | 免费延期次数已用完 |
| 1268 | silence_expired_not_refundable | 沉默期已过期的套餐不能退款 |
| 1269 | silence_policy_overlap | 延期政策重叠 |
| 1270 | silence_extension_no_policy | 未匹配到延期政策 |
| 1271 | silence_extension_order_pending | 已有未结束的延期订单或申请 |
| 1272 | silence_offline_trade_no_duplicate | 线下交易单号已登记 |
| 1273 | silence_offline_amount_mismatch | 实收金额与计算金额不一致(data.expected_amount) |
| 1274 | silence_feature_disabled | 沉默期功能未开启 |
| 1275 | silence_switch_precheck_failed | 总开关打开前检查未通过(data.failed_items) |
10. 企微审批模板
超级管理员在"企微审批场景"配置业务类型 沉默期审批(package_silence_approval),模板需有"申请类型"单选控件,选项映射:购买时调整沉默期、特殊延期、线下付费延期。可映射字段见场景配置页的业务字段列表(申请单号、资产、套餐、原截止日期、延期天数、计费天数、费用、原因、附件、收款方式、交易单号、凭证等)。