# 统一身份认证用户数据同步 - 字段映射说明

## 1. 概述

将校园管理系统（`hzdyjs_xg`）的组织与用户数据，定时同步到统一身份认证中间库 6 张标准表，供第三方平台拉取。

| 目标表 | 说明 | 数据源 |
|--------|------|--------|
| `GXXX_YXSDWJBSJZL` | 院系所单位 | `sys_dept` |
| `GXJG_JZGJCSJZLB` | 教职工基础 | `sys_user`（`account_type='1'`） |
| `GXJG_GRTXFSZL` | 教职工通讯 | `sys_user`（`account_type='1'`） |
| `GXXS_XSJBSJZL` | 学生基础 | `xg_student_msg` |
| `GXXS_GRTXZL` | 学生通讯 | `xg_student_msg` |
| `ZFTAL_XTGL_ERRLOG` | 同步错误日志 | 同步脚本写入 |

**不同步字段**：`zp`（照片 BLOB）按约定不处理。

---

## 2. 单位表 GXXX_YXSDWJBSJZL

| 目标字段 | 源字段 | 转换规则 |
|----------|--------|----------|
| dwh | sys_dept.dept_id | `RIGHT(CAST(dept_id AS CHAR), 10)`（雪花ID超长，取后10位） |
| dwmc | sys_dept.dept_name | 截断至60字符 |
| lsdwh | sys_dept.parent_id | parent_id=0 时 NULL，否则取后10位 |
| dwyxbs | status + del_flag | 正常且未删除='1'，否则='0' |
| zhgxsj | update_time / create_time | `YYYYMMDDhhmmss` |
| scbz | del_flag | '0'→'n'，'1'→'y' |

---

## 3. 教职工表 GXJG_JZGJCSJZLB

| 目标字段 | 源字段 | 转换规则 |
|----------|--------|----------|
| gh | sys_user.user_name | 工号，截断至20字符 |
| dwh | sys_user.dept_id | 取后10位 |
| xm | sys_user.nick_name | 姓名 |
| xbm | sys_user.sex | 0男→'1'，1女→'2'，其他→'0' |
| dqztm | sys_user.status | 0正常→'11'，停用→'99' |
| zhgxsj | update_time / create_time | `YYYYMMDDhhmmss` |
| scbz | del_flag | '0'→'n'，'1'→'y' |

---

## 4. 教职工通讯表 GXJG_GRTXFSZL

| 目标字段 | 源字段 | 转换规则 |
|----------|--------|----------|
| id | sys_user.user_name | 主键，用工号 |
| gh | sys_user.user_name | 工号 |
| yddh | sys_user.phonenumber | 手机号 |
| dzxx | sys_user.email | 邮箱 |
| zhgxsj | update_time / create_time | `YYYYMMDDhhmmss` |
| scbz | del_flag | '0'→'n'，'1'→'y' |

---

## 5. 学生表 GXXS_XSJBSJZL

| 目标字段 | 源字段 | 转换规则 |
|----------|--------|----------|
| xh | xg_student_msg.student_no | 学号 |
| xm | name | 姓名 |
| ywxm | name_english | 英文名 |
| cym | former_name | 曾用名 |
| xbm | gender | 0男→'1'，1女→'2' |
| csrq | birth_date | `YYYYMMDD` |
| jg | native_place | 籍贯 |
| sfzjlxm | - | 固定 '1'（身份证） |
| sfzjh | id_card | 身份证号 |
| zzmmm | political_status | 政治面貌 |
| xxm | blood_type | 血型 |
| sfdszn | is_single_child | 1→'1'，0→'0' |
| dwh | college_id | 学院ID |
| szbh | xg_class_msg.class_code | 关联班级表取班级代码 |
| sfzx | student_status | 1/2/3→'1'在校，其他→'0' |
| sfyby | student_status | 5毕业→'1'，其他→'0' |
| zhgxsj | update_time / create_time | `YYYYMMDDhhmmss` |
| scbz | deleted | 0→'n'，1→'y' |

---

## 6. 学生通讯表 GXXS_GRTXZL

| 目标字段 | 源字段 | 转换规则 |
|----------|--------|----------|
| xh | student_no | 学号 |
| yzbm | postal_code | 邮编 |
| txdz | current_address / home_address | 优先现住址 |
| yddh | phone | 手机 |
| dzxx | email | 邮箱 |
| jstxh | qq / wechat | 优先QQ |
| zhgxsj | update_time / create_time | `YYYYMMDDhhmmss` |
| scbz | deleted | 0→'n'，1→'y' |

---

## 7. 注意事项

1. **单位号 dwh 长度限制**：第三方表 `dwh` 仅 10 位，而 `sys_dept.dept_id` 为雪花ID（19位），当前取后10位；若对方有编码规范需另行映射。
2. **增量同步**：基于源表 `update_time` / `create_time`，状态记录在 `.sync_state`。
3. **全量同步**：设置 `SYNC_MODE=full` 或执行 `./sync_user_to_sso.sh --full --once`。
4. **生产 Oracle**：`TARGET_DB_TYPE=oracle` 时，由 `oracle_gen_merge.py` 从 MySQL 生成 MERGE SQL，再经 `sqlplus` 写入中间库；`verify_sync.sh` 可直接校验 Oracle 表记录数。

---

**版本**: v1.1.0  
**更新时间**: 2026-08-24