API Changelog Bot 52f72daac2 docs(mp-traveler): 身份证场景 birthday 可空契约 + 前端行动点 (HL #1206 )

前端小程序"添加出行人"身份证场景下, birthday 由后端 parseIdCardInfo
自动解析回填; 前端表单应放行身份证时 birthday 必填校验。

HL Issue #1205, PR #1206

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-04-22 19:45:29 +08:00

3.3 KiB

原始文件 永久链接 Blame 文件历史

date, type, scope, pr, issue, breaking, audience

date	type	scope	pr	issue	breaking	audience
2026-04-22	docs	hl-mp-service,hl-user-service	#待填	#1205	false	frontend

小程序添加出行人: 身份证场景 birthday 可空(后端自动解析回填)

TL;DR(前端行动点)

小程序 "添加出行人" 表单,当 idCardType === 'ID_CARD' 时, 不要再要求用户手动选 birthday。两种任选其一:

推荐: 前端按身份证号第 7-14 位本地解析 YYYYMMDD 自动回填 input (与后端一致, 所见即所得)
最小改动: 前端表单 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} (编辑) 同样规则。

后端行为(只读参考)

// 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)

3.3 KiB 原始文件 永久链接 Blame 文件历史