API Changelog Bot
父节点
808680ddde
当前提交
d29253481c
@ -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 完全同机制)。
|
||||||
@ -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,选保游网司机专用计划)"}
|
||||||
|
```
|
||||||
正在加载...
x
在新工单中引用
屏蔽一个用户