Files
junhong_cmp_fiber/docs/2026-10-27-订单拆分至沉默期-前端修改汇总.md
邹进 c33cc6f6c3
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 1m32s
docs: 沉默期 11.1、3.5 测试环境验证结果与前端修改汇总
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 18:07:46 +09:00

247 lines
16 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.
# 订单按类别拆分 → 套餐沉默期:前端修改汇总
日期: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` 保留不变。
```json
{ "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 前端改动
1. 订单管理下拆三个页面,分别调用对应列表接口,导出按钮传对应场景。
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` 与 OpenSpec `add-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|close` + `reason` |
| `GET /usages?view=expiring|expired|all` | — | 即将过期(默认 7 天内)/ 已过期套餐;导出场景 `package_silence_usage` |
延期政策(`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 的提示文案