# 修复:id_card_type 列长 VARCHAR(20)→VARCHAR(30) + 字典脏数据修订 (#1523 hotfix)

**类型**: SQL hotfix (修补昨晚 PR #1523)
**关联**: PR #1526 / 修补 PR #1523 / 工单 #1522 仍在
**日期**: 2026-04-28
**影响范围**: hl_user_service 三张活跃表 ALTER + 字典 sys_dict_data UPDATE 2 条

---

## 背景

PR #1523 引入回乡证 enum value `HONGKONG_RESIDENT_PASS` (22 字符),但漏改 DB 列长。测试服回归立即测出:
```
POST /user/traveler  body={"idCardType":"HONGKONG_RESIDENT_PASS",...}
→ 400 "字段【id_card_type】内容过长,请删减后重试"
```
HONGKONG_RESIDENT_PASS = 22 字符 > VARCHAR(20),三张活跃表写入失败。

## 修复

### 1. schema.sql 改 6 处 (含 legacy 表)
- `sql/traveler.sql` (traveler + traveler_ocr_log) VARCHAR(20)→(30)
- `sql/user_personal_info.sql` (user)
- `sql/hl_order_service.sql` (legacy v1 order_traveler)
- `sql/hl_insurance_service.sql` (legacy v1 insured_person)
- `sql/hl_contract_service.sql` (legacy v1 contract_traveler)

### 2. 增量 SQL 必跑 (运维)
**V20260429__id_card_type_extend_to_varchar30.sql** (扩列):
```sql
USE hl_user_service;
ALTER TABLE traveler MODIFY COLUMN id_card_type VARCHAR(30) NOT NULL DEFAULT 'ID_CARD' COMMENT '...';
ALTER TABLE traveler_ocr_log MODIFY COLUMN id_card_type VARCHAR(30) NOT NULL COMMENT '...';
ALTER TABLE user MODIFY COLUMN id_card_type VARCHAR(30) DEFAULT 'ID_CARD' COMMENT '...';
```
idempotent,重复执行无害。

**V20260430__fix_id_card_type_dict_labels.sql** (修字典脏数据):
```sql
USE hl_user_service;
UPDATE sys_dict_data SET dict_label='港澳通行证', updated_at=NOW()
  WHERE dict_data_id=80073 AND dict_value='HK_MACAU_PASS';
UPDATE sys_dict_data SET dict_label='台湾通行证', updated_at=NOW()
  WHERE dict_data_id=80074 AND dict_value='TAIWAN_PASS';
```

为什么需要 V20260430:测试服 80073/80074 历史脏数据 dict_label 与字典口径错位 (80073 错标"回乡证" 与 80077 撞名,80074 错标"台胞证")。下拉框会出现两个"回乡证"引发用户混淆。

## 部署步骤

### 测试服 (运维已跑)
```bash
ssh root@1.182.108.58
cd /opt/hulalv/HL && git pull
mysql -uroot -proot -h 192.168.100.236 hl_user_service < sql/V20260429__id_card_type_extend_to_varchar30.sql
mysql -uroot -proot -h 192.168.100.236 hl_user_service < sql/V20260430__fix_id_card_type_dict_labels.sql
```

### 正式环境 (待运维)
```bash
ssh root@<正式 DB 节点 Node1 47.105.108.0>
mysql -uhl_admin -p<密码> hl_user_service < /opt/hulalv/HL/sql/V20260429__id_card_type_extend_to_varchar30.sql
mysql -uhl_admin -p<密码> hl_user_service < /opt/hulalv/HL/sql/V20260430__fix_id_card_type_dict_labels.sql
```

注: hl-user-service / hl-order-service-v2 **无需重启**,schema 改动 ALTER 后即时生效。

## Phase 2 待办

legacy 库 `hl_contract_service.contract_traveler` / `hl_insurance_service.insured_person` 已逻辑废弃 v2 化,本 PR 不发增量 SQL (避免误执行 v1 库)。如确认 legacy 库仍有写入,后续补独立 V*.sql。

## 经验沉淀

`memory/experience/backend-dev/new-enum-value-check-column-length.md`: 新增枚举字符串值前必先 grep schema.sql 列长度。**单测 Mockito mock DB 不踩真 SQL,字段长度问题永远不会暴露,必须本地+测试服真插入才能爆**。本次 PR #1523 直接漏掉这一步合并到 dev,被测试服 round-trip 立即翻盘。

## 合并

- PR #1526 squash merge 到 dev (sha ac54dd62)
- 工单 #1522 (PR #1523 母工单) 仍在,等运营 SQL 部署 + 前端补下拉 + 12301 联调真实回乡证号
