# 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 账号执行同步。

## 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`。
- `street_address_key`: 具体地址字段编码，默认 `WorkSpacevalue`，写入 AD 的 `streetAddress`；取不到时会兜底尝试 `extgzddxx_606508_618643707`。
- `default_company`: 固定公司名；不传时尝试取 EHR 根组织名称。
- `location_mappings`: 工作地点到 AD 国家、省、市字段的映射。

## 指定用户同步示例

只验证并同步 `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`: 同步失败的用户数。