Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
16 KiB
订单按类别拆分 → 套餐沉默期:前端修改汇总
日期:2026-10-27
范围:Iteration/8-11 提交 eb9f12d1(后台订单按类别拆分)至 af57de0d(沉默期配置口径调整),均已部署测试环境。
接口字段以 docs/admin-openapi.yaml 为准;本文说明页面要改什么。
一、总览
| # | 变更 | 前端是否要改 | 章节 |
|---|---|---|---|
| 1 | 后台订单按平台 / 代理商 / 在线支付拆分列表与导出 | 要改:拆三个页面 | 二 |
| 2 | 企业账号只能访问授权给本企业的资产 | 要改:企业账号隐藏部分资产操作 | 三 |
| 3 | 实名即生效套餐沉默期、延期办理 | 要改:套餐配置、购买、资产套餐展示、延期页面、总开关、政策 | 四 |
| 4 | 卡 / 设备首次购买套餐时间 | 要改:列表列、筛选、详情、记录弹窗 | 五 |
| 5 | 后台线下下单不再绕开实名 | 不改接口,展示需知晓 | 六 |
| 6 | 退款 0 元可提交审批 | 不改接口 | 六 |
| 7 | 排队激活停复机、孤儿套餐、微信查单 | 不涉及前端 | — |
二、后台订单按类别拆分
2.1 新接口
| 页面 | 列表接口 | 导出场景(POST /api/admin/export-tasks 的 scene) |
包含 |
|---|---|---|---|
| 平台订单 | GET /api/admin/orders/platform |
order_platform |
后台下单且线下支付:平台自营、赠送、平台代购代理名下的卡 |
| 代理商订单 | GET /api/admin/orders/agent |
order_agent |
后台下单且从代理钱包扣款:代理自购、代理给下级购买、平台代扣代理钱包、代理 OpenAPI 下单 |
| 在线支付订单 | GET /api/admin/orders/online |
order_online |
个人客户在客户端下的单:微信、支付宝、卡钱包支付,自动续费,自动购买,待支付 |
- 三个列表接口的查询参数、返回结构与
GET /api/admin/orders完全相同,不需要也不接受类别参数。 - 三类互不重叠:相同筛选条件下三个
total之和等于GET /orders的total。 - 导出
query.filters与scene=order相同,表头相同。导出任务列表里新任务的scene是新值,显示中文请按上表映射。 - 订单详情仍用
GET /api/admin/orders/{id};GET /orders与场景order保留不变。
{ "scene": "order_online", "format": "xlsx",
"query": { "filters": { "payment_status": 2, "start_time": "2026-10-01T00:00:00+08:00", "end_time": "2026-10-26T23:59:59+08:00" } } }
2.2 账号可见范围
| 账号 | 平台订单 | 代理商订单 | 在线支付订单 |
|---|---|---|---|
| 超管、平台 | 全部 | 全部 | 全部 |
| 代理 | 平台为本店名下卡代购的单 | 买家是本店的钱包订单 | 始终为空,隐藏此页面 |
| 企业 | 无权限 | 无权限 | 无权限 |
企业账号调用以下接口返回无权限("企业账号无权访问订单"):GET /orders、/orders/platform|agent|online、GET /orders/{id}、POST /orders/purchase-check。
2.3 前端改动
- 订单管理下拆三个页面,分别调用对应列表接口,导出按钮传对应场景。
- 原"订单列表"页可保留或下线。
- 代理账号隐藏"在线支付订单";企业账号隐藏订单菜单。
三、企业账号的资产访问范围
/api/admin/assets/:identifier/* 对企业账号收紧:
- 只能访问当前授权给本企业的卡或设备。未授权与不存在一样返回"未找到"。涉及资产解析、实时状态、刷新、套餐、当前套餐、钱包、订单、操作日志、停机 / 复机。
- 以下操作企业账号一律无权限(即使资产已授权),返回
CodeForbidden"企业账号无权执行该资产操作":
| 接口 | 操作 |
|---|---|
PATCH /assets/:identifier/packages/:package_usage_id/expires-at |
改套餐有效期 |
PATCH /assets/:identifier/packages/:package_usage_id/used-data |
改已用量 |
PATCH /assets/:identifier/deactivate |
停用 |
PATCH /assets/:identifier/polling-status |
开关轮询 |
PATCH /assets/:identifier/realname-status |
改实名状态 |
- 停机 / 复机(
POST /stop、/start)对已授权资产仍可用。
前端改动:企业账号登录时隐藏上表 5 个操作按钮;资产搜索结果为"未找到"时按普通未找到提示,不要提示"无权限"。
四、实名即生效套餐沉默期
规则见
docs/沉默期技术方案/实名即生效套餐沉默期技术方案_v3.md与 OpenSpecadd-package-silence-period。
4.1 总开关对页面的影响
总开关 package.silence.enabled 默认关闭。
| 页面 / 功能 | 关闭时 | 打开时 |
|---|---|---|
资产套餐列表、H5 套餐历史里的 silence 对象 |
不返回,页面不显示沉默期 | 返回,显示状态、截止日 |
| "延期"入口 | 不显示 | silence.extendable = true 时显示 |
| 延期资格、试算、下单、线下登记、特殊延期 | 返回 1274 | 可用 |
| 套餐默认沉默期、延期政策、企微审批场景配置 | 可用 | 可用 |
| 购买时调整沉默期 | 可用 | 可用 |
总开关只能用专用接口切换(通用"系统配置"接口里只读):
GET /api/admin/package-silence/switch:返回enabled与打开前 4 项检查precheck[](code、name、passed、count)。PUT /api/admin/package-silence/switch{ "enabled": true|false }:仅超级管理员。打开前检查不通过返回 1275,data.failed_items为未满足项,直接展示;关闭不检查。
前端改动:新增"沉默期总开关"设置页(超管可见),展示 4 项检查结果与开关。
4.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(含"本身购买即生效、但有店铺分配覆盖为实名即生效"的套餐);套餐导出同样传该筛选。套餐导出新增"默认沉默期(天)""是否支持付费延期"两列。
前端改动:套餐表单加两个字段(按 expiry_base、package_type 控制显示与必填);套餐列表加"未配置沉默期"筛选。
4.3 后台购买时调整沉默期
POST /api/admin/orders 新增可选字段:
silence_period_days(≥ 1,不设上限)、silence_reason(填了天数时必填)。- 需要
package_silence:override权限,无权限传值返回 1261。 - 不超过默认值直接生效;超过默认值时按延期政策直接生效,或先按默认值购买并提交企微审批。发起人未绑定企微成员时购买被拒。
- 只对"资产未实名时购买的实名即生效主套餐"生效,其他情况忽略。
前端改动:后台下单弹窗增加"本次沉默期(天)""调整原因",有权限才显示。
4.4 资产套餐展示
后台资产套餐历史 / 当前套餐、H5 套餐历史(GET /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=。
前端改动:套餐列表显示沉默期状态与截止日、"延期"入口、"沉默期流水"弹窗(后台与 H5)。
4.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,前端渲染为二维码 |
POST /orders/offline |
package_silence:offline |
登记线下付款:package_usage_id、days、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 |
— | 延期订单列表 / 详情;导出场景 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;优惠价有收款时填收款方式、交易单号、凭证。批量逐行校验,失败返回 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。
前端改动:新增页面——延期弹窗(资格 + 试算 + 二维码 / 线下登记 / 特殊延期三种方式)、延期订单、延期批次与异常处理、即将过期 / 已过期套餐、延期政策管理。
4.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:沉默期流水。
4.7 退款
沉默期已过期的套餐申请退款返回 1268(总开关打开时)。
4.8 企微审批场景
在"企微审批场景"配置业务类型 沉默期审批(package_silence_approval)。模板需有"申请类型"单选控件,选项映射:购买时调整沉默期、特殊延期、线下付费延期。可映射的业务字段见场景配置页。
前端改动:审批场景页的业务类型下拉加入"沉默期审批"。
4.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) |
4.10 新增权限点
package_silence:override、package_silence:extend、package_silence:extend_batch、package_silence:offline、package_silence:exception、package_silence:policy。前端按权限控制按钮显示,角色配置页需能勾选。
五、卡 / 设备首次购买套餐时间
- 卡列表、设备列表返回
first_purchase_at,支持first_purchase_start、first_purchase_end(RFC3339)筛选;卡详情、设备详情、资产解析返回first_purchase_at。 - 卡、设备导出末尾新增"首次购买套餐时间"列。
- 首次购买套餐记录:
GET /api/admin/package-silence/assets/:asset_type/:id/first-purchase-records(asset_type为card/device),按世代倒序,含来源(首次购买套餐 / 历史回填)、订单号、结束时间与原因。 - 换货后的新资产不会因换货得到该时间,要等它在当前世代真正支付套餐订单;旧资产换货回库后该时间清空,旧记录带结束原因"换货回库"。
- 绑定在设备上的卡不记录;只读,不提供修改。不受沉默期总开关影响。
前端改动:卡 / 设备列表加列与时间范围筛选,详情显示该时间,加"首次购买套餐记录"弹窗。
六、只影响展示、不改接口
- 后台线下下单不再绕开实名(
69ec98aa):后台给平台自营资产线下下单、或线下下单赠送套餐时,若资产未实名、套餐是实名即生效,套餐现在是"待生效(等待实名)",实名后才生效;以前会直接"生效中"。订单buyer_type仍是personal。前端不用改,测试和运营看到状态变化属正常。 - 退款 0 元可提交审批(
c9e5d655):以前 0 元退款提交审批报数据库错误,现在正常。前端若对退款金额做了> 0校验,可放宽为≥ 0。
七、前端改动清单
- 订单管理拆三页(平台 / 代理商 / 在线支付),各自导出场景;代理隐藏在线支付页;企业隐藏订单菜单
- 企业账号隐藏资产的改有效期、改已用量、停用、开关轮询、改实名状态 5 个按钮
- 沉默期总开关设置页(超管)
- 套餐表单:默认沉默期、是否支持付费延期;套餐列表"未配置沉默期"筛选
- 后台下单弹窗:本次沉默期、调整原因(
package_silence:override) - 资产套餐列表(后台 + H5):沉默期状态、截止日、延期入口、沉默期流水
- 后台延期:资格 / 试算、二维码、线下登记、特殊延期(单个 + 批量导入)
- 延期订单、延期批次与异常处理、即将过期 / 已过期套餐页面(含导出)
- 延期政策管理页
- H5:延期资格、试算、自助下单、我的延期订单、流水
- 企微审批场景业务类型加"沉默期审批"
- 角色权限配置加 6 个
package_silence:*权限点 - 卡 / 设备:首次购买套餐时间列、筛选、详情、记录弹窗、导出列
- 错误码 1260~1275 的提示文案