From d29253481c3fb5d18f46f396cf0784084a4ef770 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Thu, 11 Jun 2026 17:28:12 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog-v2):=20=E5=8F=B8=E6=9C=BA?= =?UTF-8?q?=E6=89=B9=E9=87=8F=E7=BB=AD=E7=AD=BE(#3699)+=E5=8F=B8=E6=9C=BA?= =?UTF-8?q?=E9=99=A9=E8=B5=B0=E4=BF=9D=E6=B8=B8=E7=BD=91=E6=8A=95=E4=BF=9D?= =?UTF-8?q?=E4=B8=8E=E4=BF=9D=E5=8D=95(#3700)=20=E7=AE=A1=E7=90=86?= =?UTF-8?q?=E5=90=8E=E5=8F=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ..._司机一键批量续签换季-新增接口-管理后台.md | 83 ++++++++++++++++++ ...游网投保与保单-新增接口与保险块变更-管理后台.md | 85 +++++++++++++++++++ 2 files changed, 168 insertions(+) create mode 100644 changelogs-v2/2026-06/11_3699_司机一键批量续签换季-新增接口-管理后台.md create mode 100644 changelogs-v2/2026-06/11_3700_司机险走保游网投保与保单-新增接口与保险块变更-管理后台.md diff --git a/changelogs-v2/2026-06/11_3699_司机一键批量续签换季-新增接口-管理后台.md b/changelogs-v2/2026-06/11_3699_司机一键批量续签换季-新增接口-管理后台.md new file mode 100644 index 0000000..35d52a9 --- /dev/null +++ b/changelogs-v2/2026-06/11_3699_司机一键批量续签换季-新增接口-管理后台.md @@ -0,0 +1,83 @@ +# 【新增接口·管理后台】司机档案——车管一键批量续签(换季) + +> 服务:hl-fleet-service(8087) | 分支:dev-v3 | PR:#3699 | 已部署测试服并实测通过(2026-06-11) +> 契约出处:FLEET API §3.7 | 前端触发位:司机档案列表页「批量续签」按钮(换季时用) + +## ⚠️ 关键说明 + +1. **一键换季动作**:把指定司机(或全部在册 `season=active` 司机)批量转入续签流程——`active → pending` + 为每人生成续签 H5 邀请链接/二维码。**链接需车管手动转发给司机**(本期无自动推送)。 +2. **非在册司机不报错**:`pending/archived/blacklist` 的司机自动跳过,进 `skipped[]` 给原因,不中断整批。 +3. `renewSeasonLabel` 必填但**不落库**,仅入审计日志;`remark` 同理。 +4. 防双击:同参数 3 秒内重复提交返「批量续签处理中,请勿重复提交」。 + +## 1. 新增端点 + +`POST /admin/fleet/drivers/batch-season-renew` + +### 入参(body) + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| driverIds | string[] | 否 | 目标司机ID列表(雪花字符串);**缺省/空数组 = 对全部 season=active 司机全量换季**;含不存在的 ID 整批报 100001 | +| renewSeasonLabel | string | 是 | 续签目标赛季标识(如 `2027`);缺失返 400 | +| remark | string | 否 | 批量动作备注(入审计日志) | + +### 请求示例 + +```bash +curl -k -X POST "https://api.test.1814.love:9443/admin/fleet/drivers/batch-season-renew" \ + -H "Authorization: Bearer {token}" -H "Content-Type: application/json" \ + -d '{"driverIds":["2065002428792492033"],"renewSeasonLabel":"2027","remark":"2027 赛季换季"}' +``` + +### 响应示例(测试服实测) + +```json +{ + "code": 200, + "message": "成功", + "data": { + "matchedCount": 1, + "transitionedCount": 1, + "inviteGeneratedCount": 1, + "invites": [ + { + "driverId": "2065002428792492033", + "driverName": "张师傅", + "token": "e4dc8e393bc54224aeb97a346611cb58", + "url": "https://h5.hl-fleet.com/onboard?token=e4dc8e393bc54224aeb97a346611cb58", + "qrCodeUrl": "data:image/png;base64,iVBORw0KGgo...", + "expireAt": "2026-06-25T17:25:20" + } + ], + "skipped": [] + } +} +``` + +| 出参字段 | 说明 | +|---|---| +| matchedCount | 匹配司机数 | +| transitionedCount | 成功转入续签(active→pending)数 | +| inviteGeneratedCount | 生成续签邀请数(同事务恒等于 transitionedCount) | +| invites[] | 「待发列表」:driverId/driverName/token/url(H5 链接,`?token=` 参数)/qrCodeUrl(**二维码 Base64 DataURL,前端可直接 img src 渲染**)/expireAt(14 天有效) | +| skipped[] | 跳过明细:driverId + reason(如 `season=pending≠active（非在册，跳过）`) | + +### 非 active 司机被跳过(实测) + +```json +{ "matchedCount": 1, "transitionedCount": 0, "inviteGeneratedCount": 0, "invites": [], + "skipped": [ { "driverId": "2065002428792492033", "reason": "season=pending≠active（非在册，跳过）" } ] } +``` + +## 2. 错误码 + +| code | 触发场景 | +|---|---| +| 400 | renewSeasonLabel 缺失/空白(平台参数校验统一口径) | +| 100001 | driverIds 含不存在的司机 ID(消息列出缺失 ID,整批不执行) | + +## 3. 联动效果(前端无需额外调用) + +- 司机列表 §3.1 的 `season` 变 `pending`、`pendingInvitedAt` 有值(卡片可显示「续签链接已发送·{日期}」); +- 每位司机自动生成一条 mode=renew 的待审核记录(司机打开链接走 §4 续签 3 步流程,与单个生成链接 §4.1 完全同机制)。 diff --git a/changelogs-v2/2026-06/11_3700_司机险走保游网投保与保单-新增接口与保险块变更-管理后台.md b/changelogs-v2/2026-06/11_3700_司机险走保游网投保与保单-新增接口与保险块变更-管理后台.md new file mode 100644 index 0000000..e13cdfc --- /dev/null +++ b/changelogs-v2/2026-06/11_3700_司机险走保游网投保与保单-新增接口与保险块变更-管理后台.md @@ -0,0 +1,85 @@ +# 【新增接口+入参变更·管理后台】司机险走保游网——档案页投保/保单/退保 + 保险块字段变更 + +> 服务:hl-fleet-service(8087) + hl-order-service-v3(8086) | 分支:dev-v3 | PR:#3700 | 已部署测试服并实测通过(2026-06-11) +> 契约出处:FLEET API §3.3/§3.4 保险块 + §13.7 | 业务拍板:司机险由车管在**司机档案页手动点「投保」**出单(非派车自动、非定时);保险提供方走 **order-v3** + +## ⚠️ 关键说明(含 2 处破坏性变更) + +1. **🔴 破坏性①——司机保存入参 `insurance.perDayRate` 字段删除**(§3.3 新增/§3.4 编辑):perTrip 日费率改走保游网计划费率,不再手填。前端表单请移除该输入项;继续传该字段会被忽略。 +2. **🔴 破坏性②——`insurance.type=perTrip` 时 `insurancePlanId` 必填**(返 100001):从「司机可选保险计划下拉」(下方接口 1)选计划。`annual`/`none` 传 null;类型从 perTrip 切走时后端自动清空该字段。 +3. 司机详情 §3.2 `insurance` 块新增回显 `insurancePlanId`(perTrip 有值,字符串雪花)。 +4. **投保动作会真实调保游网出单、从保游账户真实扣费**——前端联调请只调下拉/保单列表/校验反例,出单正向请约定后用测试计划操作。 +5. 计划下拉数据源 = 运营在「保险计划打标」端点把计划标为 `DRIVER`/`BOTH`(接口 5,order-v3 管理端);**新同步计划默认 CUSTOMER,司机端不可见**,须显式打标。 + +## 1. 司机可选保险计划下拉 + +`GET /admin/fleet/drivers/insurance/plan-options` + +```json +{ "code": 200, "data": [ + { "planId": "2054773833342451714", "planName": "10万计划", "productName": "山河令（太保山东新）", "usageCategory": "DRIVER" } +], "message": "成功" } +``` + +## 2. 司机险投保(档案页「投保」按钮) + +`POST /admin/fleet/drivers/{driverId}/insurance/purchase` + +| 字段 | 类型 | 必填 | 说明 | +|---|---|---|---| +| planId | string(雪花) | 是 | 司机专用计划(接口 1 选取) | +| coverageStartDate / coverageEndDate | string(yyyy-MM-dd) | 是 | 保障起止;**「按赛季」「按年」快捷预填由前端实现**(仍可手改);起>止返 100001 | +| remark | string | 否 | 缺省后端填「司机险投保: {司机姓名}」 | + +成功返回保单(被保人证件号已脱敏;金额/雪花均字符串): + +```json +{ "code": 200, "data": { + "insuranceOrderId": "1934567890123456789", "policyNo": "...", "extPolicyNo": "BY-2026-...", + "extOrderNo": "...", "totalPremium": "88.00", "status": "INSURED", "statusLabel": "已投保", + "coverageStartDate": "2026-07-01", "coverageEndDate": "2027-06-30", + "insuredPersons": [ { "name": "周师傅", "idCardNo": "1502**********0017" } ] } } +``` + +> 异步出单型产品返回 `status=INSURING`(投保中,`extPolicyNo` 暂空),保游回调落定后翻 `INSURED`/`FAILED`,刷新保单列表即可。 + +## 3. 司机保单列表 + +`GET /admin/fleet/drivers/{driverId}/insurance/policies` → `data` 为接口 2 同构对象数组(createTime 倒序;无保单返 `[]`)。 + +## 4. 司机险退保(仅人工误投时用) + +`POST /admin/fleet/drivers/{driverId}/insurance/policies/{insuranceOrderId}/cancel` + +- 保单不属于该司机 → 100001(越权守卫);仅 `INSURED/INSURING` 可退,否则 540202。 +- 业务拍板:**取消派车不退保、换司机投新单旧单到期自然失效、离职拉黑不自动退**——本端点只服务误投撤销。 + +## 5. 保险计划打标(order-v3 管理端·运营用) + +`PUT /v3/admin/insurance/plans/{planId}/usage-category` body:`{"usageCategory":"DRIVER"}`(白名单 CUSTOMER/DRIVER/BOTH,非法返 540223)。 +配套:计划查询出参(`GET /v3/admin/insurance/products/{productId}/plans` 等)已新增 `usageCategory` 字段,可做打标 UI。客人端选计划**不收紧**(维持全量,拍板)。 + +## 6. 错误码汇总 + +| code | 触发场景 | +|---|---| +| 100001 | perTrip 缺 insurancePlanId / 保障起>止 / 退保保单不属于该司机 | +| 600205 | 司机不存在 | +| 540031 | 该保险计划未标注为司机可用(选了 CUSTOMER 计划) | +| 540032 | 该司机该保障期已有生效保单(一天只一份生效,含投保中) | +| 540202 | 保单当前状态不可退保 | +| 540223 | 计划使用分类非法(打标端点) | +| 605601 | 保险服务不可用(order-v3 不通,稍后重试) | + +### 实测反例示例 + +```bash +# 选 CUSTOMER 计划投保 → 540031 +curl -k -X POST "https://api.test.1814.love:9443/admin/fleet/drivers/{driverId}/insurance/purchase" \ + -H "Authorization: Bearer {token}" -H "Content-Type: application/json" \ + -d '{"planId":"2054773833342451714","coverageStartDate":"2026-07-01","coverageEndDate":"2027-06-30"}' +# => {"code":540031,"message":"该保险计划未标注为司机可用"} + +# perTrip 不带 insurancePlanId 建司机 → 100001 +# => {"code":100001,"message":"参数非法: 保险类型为 perTrip 时缺少必填子字段: insurancePlanId(保险方案id,选保游网司机专用计划)"} +```