52f72daac2
前端小程序"添加出行人"身份证场景下, birthday 由后端 parseIdCardInfo 自动解析回填; 前端表单应放行身份证时 birthday 必填校验。 HL Issue #1205, PR #1206 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
71 行
3.3 KiB
Markdown
71 行
3.3 KiB
Markdown
---
|
|
date: 2026-04-22
|
|
type: docs
|
|
scope: hl-mp-service,hl-user-service
|
|
pr: "#待填"
|
|
issue: "#1205"
|
|
breaking: false
|
|
audience: frontend
|
|
---
|
|
|
|
# 小程序添加出行人: 身份证场景 birthday 可空(后端自动解析回填)
|
|
|
|
## TL;DR(前端行动点)
|
|
|
|
小程序 "添加出行人" 表单,当 `idCardType === 'ID_CARD'` 时, **不要再要求用户手动选 birthday**。两种任选其一:
|
|
|
|
1. **推荐**: 前端按身份证号第 7-14 位本地解析 `YYYYMMDD` 自动回填 input (与后端一致, 所见即所得)
|
|
2. **最小改动**: 前端表单 validator 对 `birthday` 必填校验放行 `idCardType=ID_CARD` 场景, 让请求直接发后端, 后端解析后 GET 详情时前端再刷新展示
|
|
|
|
## 背景
|
|
|
|
用户反馈: 身份证类型下, 填好证件号 + 姓名 + 手机号点 "确认添加", 被前端 Toast `请选择出生日期` 拦截。
|
|
|
|
后端早已支持 "填身份证 idCardNo 可不传 birthday" 契约 —— `TravelerService.addTraveler()` 在 `save()` **前**调用 `parseIdCardInfo()`, 按 `idCardNo.substring(6,14)` 用 `LocalDate.parse(str, BASIC_ISO_DATE)` 自动回填 `birthday` 写入 DB。
|
|
|
|
但此契约在 `@ApiModelProperty` 里没写清楚, 前端未读到导致表单校验写死 birthday 必填。
|
|
|
|
## 接口契约(本次明确)
|
|
|
|
POST `/mp/user/traveler` (添加出行人) — 请求字段规则:
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|------|------|------|------|
|
|
| `name` | String | ✅ | 姓名 |
|
|
| `idCardType` | String | 推荐填 | `ID_CARD`(身份证) / `PASSPORT`(护照) / 其它 |
|
|
| `idCardNo` | String | 依业务 | 身份证 18 位 / 护照号等 |
|
|
| `birthday` | yyyy-MM-dd | **条件性** | **填身份证(ID_CARD)时可空, 后端自动解析 idCardNo 第 7-14 位回填; 护照等其它证件类型需前端传值** |
|
|
| `gender` | String | 否 | 身份证时后端从 idCardNo 第 17 位奇偶推断(填了则覆盖) |
|
|
| `phone` | String | 否 | 手机号 |
|
|
| 其余 | - | 否 | 见 knife4j |
|
|
|
|
PUT `/mp/user/traveler/{id}` (编辑) 同样规则。
|
|
|
|
## 后端行为(只读参考)
|
|
|
|
```java
|
|
// hl-user-service: TravelerService.parseIdCardInfo
|
|
if (!"ID_CARD".equals(idCardType) || idCardNo == null || idCardNo.length() != 18) return;
|
|
if (traveler.getBirthday() == null) {
|
|
String birthStr = idCardNo.substring(6, 14);
|
|
traveler.setBirthday(LocalDate.parse(birthStr, DateTimeFormatter.BASIC_ISO_DATE));
|
|
}
|
|
```
|
|
|
|
- 身份证号位数不对 / 解析失败: 后端仅 `log.debug` 不抛异常, birthday 留 null
|
|
- 证件类型非 `ID_CARD`: 后端不解析, 前端必须传 birthday, 否则 `travelerType` 会默认 ADULT
|
|
|
|
## 护照场景(保持不变)
|
|
|
|
护照等非 ID_CARD 证件, 后端**不会**自动回填 birthday, 前端表单需要保留 birthday 选择器并要求用户填写 (否则后端按 `traveler_type_age_rule` 兜底为 ADULT)。
|
|
|
|
## 本次后端改动
|
|
|
|
仅 2 个 DTO 的 `@ApiModelProperty` 文案补充(`MpTravelerRequest.birthday` / `TravelerRequest.birthday`), 无业务逻辑变化、无签名变化、无字段增减。前端零风险, 本 changelog 是提醒前端调整表单校验。
|
|
|
|
## 关联 Issue / PR
|
|
|
|
- Issue #1205 (前端 BUG: 前端表单校验写死 birthday 必填, 未识别身份证自动解析契约)
|
|
- PR #待填
|
|
- 关联前期 PR 链: #1197 (travelerType 不入参+实时算) / #1198 (冷启动 SysDictService 回源) / #1199 (删 TravelerTypeResolver)
|