88 lines
6.9 KiB
Markdown
88 lines
6.9 KiB
Markdown
## Context
|
||
|
||
- 后端 8-11 提供的沉默期 C 端能力（接口说明见 `junhong_cmp_fiber/docs/2026-10-27-实名即生效套餐沉默期-前端接口变更说明.md` 第 4、6、9 节）：
|
||
- 套餐历史 `GET /api/c/v1/asset/package-history` 每笔套餐带 `silence` 对象，总开关关闭或不适用时不返回。
|
||
- `/api/c/v1/package-silence`：`GET /eligibility`、`GET /quote`、`POST /orders`、`GET /orders`、`GET /orders/:id`、`GET /records`。资产须属于当前客户。
|
||
- C 端现状（`iteration/8-11`）：
|
||
- 套餐历史页 `pages/asset-package-history` 通过 `components/PackageHistoryNode.vue` 递归渲染主套餐与加油包，`api/modules/asset.js` 的 `normalizePackageHistoryNode` 用展开运算保留原字段，`silence` 会原样透传。
|
||
- 接口统一走 `utils/request.js`：`code !== 0` 时 reject 原始响应（含 `code`、`msg`、`data`），`showError: false` 可关闭默认提示。
|
||
- 支付：套餐购买走 `orderApi.create/pay`，微信用公众号 JSAPI（`wechatH5Pay`），支付宝走 `pages/alipay-payment`（`u-qrcode` 渲染二维码 + 复制链接），返回刷新用 `markPendingPaymentRefresh` / `consumePendingPaymentRefresh`。
|
||
- 支付方式标签与过滤在 `utils/payment-methods.js`，资产信息返回 `allowed_payment_methods`。
|
||
- 后端延期下单的支付：`POST /orders` 只返回 `qr_content`，按商户池路由：支付宝为 WAP 支付链接，微信为微信 H5 支付链接（`H5URL`），富友为扫码内容。没有返回 JSAPI 支付参数。
|
||
- 约束：基于 `iteration/8-11`，只部署测试环境；不改停复机逻辑；不改现有套餐购买流程。
|
||
|
||
## Goals / Non-Goals
|
||
|
||
**Goals:**
|
||
- 套餐历史可见沉默期状态与截止日，可延期的套餐有入口。
|
||
- 客户能自助完成付费延期并看到结果。
|
||
- 金额、可选天数、新截止日全部以后端为准。
|
||
|
||
**Non-Goals:**
|
||
- 特殊延期、线下登记、批量延期（后台功能）。
|
||
- 后端改动，包括为延期订单增加微信 JSAPI 支付。
|
||
- 生产发布。
|
||
|
||
## Decisions
|
||
|
||
### D1 沉默期展示放在 `PackageHistoryNode` 内
|
||
|
||
在套餐卡片"到期时间"下方加沉默期区域，`node.silence` 为空时整块不渲染；加油包节点复用同一组件，规则一致。不新开详情页，客户在原页面即可看到状态。状态名直接用后端 `silence_status_name`，前端只按 `silence_status` 选颜色（waiting 蓝、expired 红、ended 灰）。
|
||
|
||
备选：在套餐历史页顶部汇总沉默期。拒绝原因：一个资产可能有多笔套餐，按笔展示更清楚。
|
||
|
||
### D2 新增接口模块 `api/modules/packageSilence.js`
|
||
|
||
与现有模块风格一致，导出 `packageSilenceApi`：`getEligibility`、`quote`、`createOrder`、`getOrders`、`getOrder`、`getRecords`。下单和资格请求 `showError: false`，由页面按错误码映射提示（D6）。订单列表默认带当前资产 `asset_identifier`，只看当前资产的订单。
|
||
|
||
### D3 页面结构
|
||
|
||
新增三个页面并在 `pages.json` 注册：
|
||
|
||
| 页面 | 用途 |
|
||
|---|---|
|
||
| `pages/silence-extension/silence-extension` | 资格、选天数、试算、选支付方式、下单 |
|
||
| `pages/silence-orders/silence-orders` | 我的延期订单列表，点击进入详情（详情用同目录 `detail` 页） |
|
||
| `pages/silence-records/silence-records` | 某笔套餐的沉默期流水 |
|
||
|
||
延期页参数 `package_usage_id`，流水页参数 `package_usage_id`。入口：套餐卡片"延期""沉默期记录"；"我的延期订单"放在套餐历史页右上角或延期页底部。
|
||
|
||
### D4 天数选择与试算
|
||
|
||
优先展示 `options` 档位（每档计费天数、金额、新截止日），默认选第一档；同时提供"自定义天数"输入，输入停止 500ms 后调 `quote`，以最后一次请求结果为准（丢弃过期响应）。前端只校验 `min_days ≤ days ≤ max_days` 和整数，金额一律显示后端值（分转元，两位小数）。
|
||
|
||
### D5 下单幂等与支付拉起
|
||
|
||
- `request_id` 在客户点击"确认支付"时生成（时间戳 + 随机串），存在页面状态中；同一次提交的网络重试复用，天数或支付方式变化后清空。
|
||
- 提交中按钮置为 loading，禁止重复提交。
|
||
- 支付宝：复用 `openAlipayPayment` 跳 `pages/alipay-payment`，二维码与复制链接都用 `qr_content`。
|
||
- 微信：后端返回的是微信 H5 支付链接或扫码内容，不是 JSAPI 参数。实现时先按"`qr_content` 是 http(s) 链接则 `window.location.href` 跳转，否则用 `u-qrcode` 渲染二维码并提示截图扫码"处理，见 Open Questions。
|
||
- 拉起前 `markPendingPaymentRefresh('silence-extension')`；延期页与订单详情 `onShow` 时 `consume` 到标记即查询订单详情。
|
||
|
||
### D6 错误码映射
|
||
|
||
在 `utils/silence-errors.js` 维护 1263～1274 的客户提示文案，1265、1266 用 `data` 中的范围拼接文案；资格接口的 `reason` 也映射为文案（not_expired、no_silence、extension_disabled、no_policy、exceeds_limit、refunded、order_pending、activated、adjust_pending）。未映射的错误码回退为后端 `msg`。
|
||
|
||
### D7 测试
|
||
|
||
沿用 `tests/october-h5.test.mjs` 的运行方式新增测试：套餐卡片沉默期显示与入口条件、天数校验、`request_id` 复用规则、错误码映射、支付返回刷新。
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- [微信 H5 支付链接在微信内置浏览器中通常无法直接支付] → C 端主要在公众号内打开。上线测试前需要确认测试环境商户池给延期订单路由的微信渠道；若确实不能在微信内支付，短期只开放支付宝或二维码，长期需后端为延期订单提供 JSAPI 支付（另开后端变更）。
|
||
- [总开关默认关闭，测试环境看不到沉默期] → 验证前请超级管理员在后台打开总开关（打开前有 4 项检查）。
|
||
- [支付回跳不可靠] → 不依赖回跳，统一在 `onShow` 查订单详情；订单列表也可手动刷新。
|
||
- [延期下单不涉及停复机] → 延期只改套餐沉默期截止日；后端在延期生效后是否复机由后端规则决定，测试环境资产已全部在只读表中，不会真实复机。
|
||
|
||
## Migration Plan
|
||
|
||
1. 在 `iteration/8-11` 上实现并本地 `build:h5`（development 模式，接测试后端）。
|
||
2. 推送 `iteration/8-11` 部署测试环境（C 端 CI 目前推送未触发构建，需先查原因或手动部署）。
|
||
3. 测试环境打开沉默期总开关，用测试资产验证：展示、资格、试算、下单、支付、流水。
|
||
4. 回退：回滚 `iteration/8-11` 对应提交重新部署；后端关闭总开关时前端自动不显示沉默期。
|
||
|
||
## Open Questions
|
||
|
||
- 延期订单的微信支付方式：测试与生产商户池对延期订单走哪种微信渠道？是否需要后端提供 JSAPI 支付？决定前按 D5 的兜底方式实现。
|
||
- "我的延期订单"入口位置（套餐历史页右上角 / 首页功能卡 / 延期页底部），默认放套餐历史页右上角。
|