# sync_ehr_to_ad 使用说明

该 extension 从北森 EHR 拉取当前用户信息，并同步到本地 AD 域中已存在的用户对象。

## Job

- `handler_path`: `extensions.sync_ehr_to_ad.job:SyncEhrToAdUserJob`
- `job_id`: `sync_ehr_to_ad.sync_users`

同步行为：

- 只处理当前在职用户。
- 只更新 AD 中已存在的 `sAMAccountName` 用户，不自动创建 AD 账号。
- 更新前会比对 AD 当前值与 EHR 目标值；一致则跳过，不一致才更新差异字段。
- 默认写入后立即回读校验；如果 LDAP 返回成功但字段未落地，Job 会报失败并记录未生效字段。
- EHR 目标值为空时不会清空 AD 字段。
- 如果配置了 `target_sam_accounts`，只对列表中的 AD 账号执行同步。
- 不同步 AD `title` 字段，不再往 AD 写入职务。
- `proxyAddresses` 只在 AD 当前为空时写入；AD 已有值时跳过，不比较也不覆盖。
- `displayName` 取 `employeeInfo.customProperties.extDDNIC_606508_303466862`。
- `department` 写入“EHR 部门编码 + EHR 部门名称”，例如 `V000076 IT`。
- `streetAddress` 默认取 `translateProperties.extgzddxx1_606508_892394263Text`。
- `st`、`l`、`physicalDeliveryOfficeName` 默认按 `extgzddxx1_606508_892394263` 的原始值做映射。

## public_cfg 示例

```json
{
  "ldap_uri": "ldaps://dc01.vastai.com:636",
  "ldap_base_dn": "DC=vastai,DC=com",
  "ldap_user_filter": "(sAMAccountName={sAMAccountName})",
  "ldap_verify_tls": false,
  "dry_run": true,
  "verify_after_write": true,
  "target_sam_accounts": ["fchen", "jqian"],
  "proxy_alias_domain": "vastaitech.com",
  "default_company": "Vastai Technologies",
  "department_code_ad_attribute": "departmentNumber",
  "postal_code": "201210",
  "location_mappings": {
    "上海": {
      "co": "China",
      "c": "CN",
      "countryCode": 156,
      "st": "Shanghai",
      "l": "Shanghai"
    }
  }
}
```

## secret_cfg 示例

```json
{
  "app_key": "EHR_APP_KEY",
  "app_secret": "EHR_APP_SECRET",
  "ldap_bind_dn": "CN=svc-ehr-ad,OU=Service Accounts,DC=vastai,DC=com",
  "ldap_bind_password": "password"
}
```

## 常用 public_cfg

- `target_sam_accounts`: 可选，字符串数组。传入后只同步这些 AD 账号；不传则同步所有当前用户。
- `dry_run`: 可选，默认 `false`。建议首次配置为 `true`，只记录会变更的字段，不写入 AD。
- `verify_after_write`: 可选，默认 `true`。真实写入后回读 AD 字段，确认修改已落地。
- `ldap_uri`: AD LDAP 地址，如 `ldaps://dc01.vastai.com:636`。
- `ldap_base_dn`: AD 用户搜索根 DN。
- `ldap_user_filter`: 用户搜索过滤器，默认 `(sAMAccountName={sAMAccountName})`。
- `ldap_verify_tls`: 是否校验证书，默认 `true`。
- `proxy_alias_domain`: 生成 `smtp:<sAMAccountName>@domain` 别名时使用的域名。
- `department_code_ad_attribute`: 部门编码写入的 AD 属性，默认 `departmentNumber`。
- `work_location_value_key`: 工作地点原始值字段编码，默认 `extgzddxx1_606508_892394263`，用于映射 AD 省、市、办公室。
- `street_address_key`: 具体地址字段编码，默认 `extgzddxx1_606508_892394263Text`，写入 AD 的 `streetAddress`；取不到时会兜底尝试 `WorkSpacevalue` 和 `extgzddxx_606508_618643707`。
- `default_company`: 固定公司名；不传时尝试取 EHR 根组织名称。
- `location_mappings`: 工作地点原始值到 AD 国家、省、市、办公室字段的映射，可覆盖内置映射。

内置工作地点映射：

| EHR 原始值 | AD st | AD l | AD Office |
| --- | --- | --- | --- |
| `qjjdizcpjk` | 上海 | 上海 | 上海张江 |
| `j1lw6k13ya` | 陕西 | 西安 | 西安环普 |
| `uzwlfke8vd` / `uyglfkg8vd` | 广东 | 深圳 | 深圳田厦 |
| `mrtkjjhoxx` | 上海 | 上海 | 上海徐汇 |
| `t21uyq5qvx` | 北京 | 北京 | 北京 |
| `nhu45qlh80` | 四川 | 成都 | 成都 |
| `5sntzs5dlr` | 加拿大 | 加拿大 | 多伦多 |
| `1` | 上海 | 上海 | 上海闵行 |

## 指定用户同步示例

只验证并同步 `fchen` 一个用户：

```json
{
  "ldap_uri": "ldaps://dc01.vastai.com:636",
  "ldap_base_dn": "DC=vastai,DC=com",
  "ldap_verify_tls": false,
  "dry_run": true,
  "verify_after_write": true,
  "target_sam_accounts": ["fchen"],
  "proxy_alias_domain": "vastaitech.com",
  "default_company": "Vastai Technologies"
}
```

确认日志中的 `changed_attrs` 符合预期后，将 `dry_run` 改为 `false` 即可真实写入。

## 返回统计

Job 返回结果包含：

- `filtered_by_target_sam`: 是否启用了指定用户过滤。
- `target_sam_accounts`: 指定用户数量。
- `processed`: 实际处理的用户数。
- `updated`: 有差异并执行更新的用户数。
- `skipped_unchanged`: AD 与 EHR 一致而跳过的用户数。
- `skipped_not_found_ad`: EHR 有 AD 账号但 AD 中找不到的用户数。
- `failed`: 同步失败的用户数。