feat(org): add incremental employee sync via upstream change feed

- POST /api/aihr/org/sync-changes(superadmin/hr_operator):拉取上游
  /sync/changes,按稳定 employee.id 回源 /employees/{id},只替换受影响
  员工,不再依赖每次全量覆盖;dryRun 仍须显式,首次必须传 sinceTime
- extPartyId 优先级翻转为 employee.id 优先:上游 employee_number 仅
  7/3417 匹配既有主体,稳定 employee_id 匹配 3417/3417
- 脱敏手机号保留本地既有有效值;上游显式清空则同步清除;手机号字段
  整体缺失拒绝写入
- 范围字段明确不一致视为迁出,写入时同事务删除本地旧记录(含登录
  身份);范围字段缺失保守跳过不删;回源详情主体与 resource_id 不一致
  在任何范围动作前拒绝
- 任职快照拉取失败在写入路径 fail-closed,不用员工字段兜底降级覆盖
- 全量同步:脱敏手机号在任何写入模式(含 replaceExisting=false)默认
  拒绝,allowPartialReplace=true 时脱敏员工保留本地手机号
- 测试 38 个(org 域),全模块 690 通过
This commit is contained in:
2026-07-25 18:15:20 +08:00
parent 75469b850b
commit 30ef6a8f6b
7 changed files with 877 additions and 36 deletions
+5 -3
View File
@@ -54,7 +54,9 @@ portless
Qdrant 默认本地无需配置;远端或自定义 collection 可用 `AIHR_QDRANT_URL`、`AIHR_QDRANT_COLLECTION`、`AIHR_QDRANT_API_KEY` 覆盖。服务端资料导入根目录可用 `AIHR_IMPORT_ROOT` 或 `-Daihr.import.root` 覆盖。组织人员同步可用 `AIHR_ORG_SYNC_BASE_URL` 指向外部开放平台 `/api/open/v1` 前缀,并配置 `AIHR_ORG_SYNC_ACCESS_TOKEN` 或 `AIHR_ORG_SYNC_CLIENT_ID`/`AIHR_ORG_SYNC_CLIENT_SECRET`;业务请求会用 client secret 生成 HMAC-SHA256 hex 签名。移动端手机号登录的短信模板 ID、阿里云 AccessKey、Secret 和短信签名都通过环境变量注入;本地放根目录 `.env.local`,`scripts/dev-backend.sh` 会自动加载。若开放平台凭证放在 `backend/.env`,启动脚本也会加载该文件,并把 `client_id`/`client_secret` 映射为组织同步实际读取的 `AIHR_ORG_SYNC_CLIENT_ID`/`AIHR_ORG_SYNC_CLIENT_SECRET`。
组织同步写入前先运行只读预检:`node scripts/verify-demo-questions.mjs --org-dry-run`。dry-run 不检查或变更本地快照表结构,也不写数据库;输出只包含人数、手机号覆盖、脱敏数、疑似乱码数和警告,不输出员工姓名。2026-07-15 当前开放平台数据已满足写入条件:3417 名员工中 3392 人可手机号映射,疑似乱码为 0;仍有 25 人手机号不可用,确认后可用 `allowPartialReplace=true` 覆盖写入。
组织同步写入前先运行只读预检:`node scripts/verify-demo-questions.mjs --org-dry-run`。dry-run 不检查或变更本地快照表结构,也不写数据库;输出只包含人数、手机号覆盖、脱敏数、疑似乱码数和警告,不输出员工姓名。2026-07-25 只读预检返回 3424 名员工、3398 个脱敏手机号和 1 条重复项目成员关系;当前上游优先字段 `employee_number` 仅匹配生产既有主体 `7/3417`,稳定 `employee_id` 匹配 `3417/3417`。全量快照仍存在脱敏手机号和重复关系,不得执行非 dry-run 请求,也不得用 `allowPartialReplace=true` 绕过。
员工岗位等字段的日常变化不要执行不安全的全量覆盖;部署支持增量同步的后端后,使用受 `superadmin/hr_operator` 保护的 `POST /api/aihr/org/sync-changes`。首次传 `{"dryRun":true,"sinceTime":"YYYY-MM-DD HH:mm:ss"}` 预检,再以相同 `sinceTime` 和 `dryRun:false` 写入;接口主动拉 `/sync/changes` 并按稳定 `employee.id` 回源详情,只替换命中的员工,脱敏手机号保留本地有效值,任职快照拉取失败则拒绝写库。
正式试点预检必须指定当前批次租户和时间窗,例如:`AIHR_PILOT_TENANT_ID=000000 AIHR_PILOT_START_DATE=2026-07-07 AIHR_PILOT_END_DATE=2026-07-10 AIHR_PILOT_STRICT=true ./scripts/demo-check.sh`。脚本只接受安全租户编号和 `YYYY-MM-DD` 日期,只统计目标租户窗口内完成的训练、校准和 SOP 评审;人员先按唯一手机号映射到在职组织快照,完训口径为每人至少 10 次已完成对练。
@@ -127,8 +129,8 @@ AIHR_AI_SPEECH_ENABLED=true
- `aihr_practice_mysql8.sql` 已导入;移动端员工训练记录落 `aihr_practice_session`,用于训练历史、主管待复盘列表和能力画像聚合
- `aihr_interview_result_mysql8.sql` 已纳入 reset 脚本;AI 面试评分完成后结果落 `aihr_interview_result`
- `aihr_candidate_material_mysql8.sql` 已纳入;候选人端补充资料文件写 `sys_oss`/MinIO,关系落 `aihr_candidate_material`
- `aihr_org_snapshot_mysql8.sql` 已纳入 reset 脚本;组织人员本地 seed(2 个住宅项目 22 人,项目经理/主管/一线三层)支撑演示,外部开放组织系统配置完成后用 `POST /api/aihr/org/sync` 拉取 `company/department/employee` 快照并覆盖本地 `aihr_org_snapshot`。2026-07-15 生产已完成该配置和覆盖同步,线上快照为 3417 名员工。
- 组织同步生产默认关闭 `aihr.org-sync.store-display-fields`,不把外部姓名/部门写入或返回组织人员展示快照;开发环境显式打开该开关仅用于 Demo。项目范围、岗位和外部主体 ID仍用于权限与身份映射。
- `aihr_org_snapshot_mysql8.sql` 已纳入 reset 脚本;组织人员本地 seed(2 个住宅项目 22 人,项目经理/主管/一线三层)支撑演示,外部开放组织系统配置完成后用 `POST /api/aihr/org/sync` 拉取 `company/department/employee` 快照。2026-07-25 生产快照为 3417 名员工、2938 人在职、3392 个手机号映射;在职姓名已按稳定 `employee_id` 定向补齐,本次未做全量覆盖。
- 源码 `application-prod.yml` 默认关闭 `aihr.org-sync.store-display-fields`;生产当前通过外部配置显式开启,用于主管团队、派发和考试对象显示已授权姓名。关闭该开关会让接口回退为编号/“员工”,修改前必须确认隐私口径与业务验收影响。项目范围、岗位和外部主体 ID仍用于权限与身份映射。
- 本地组织 seed 带演示手机号;从 `aihr_org_snapshot` 按角色查询测试账号,分别验证员工端岗位识别和主管端项目范围,不在文档保存具体号码
- 生产移动端回归同样由执行者从 `aihr_org_snapshot` 只读选择账号,不等待人工提供手机号:限定目标岗位、`employment_status='active'`、11 位 `person_phone`,并确认手机号与 `ext_party_id` 双向唯一。账号值只注入当前浏览器进程,不输出到终端、截图、报告或仓库。试点固定码开启时,登录顺序仍为先请求 `/resource/sms/code`、再提交固定码;直接提交固定码会得到 `Captcha invalid`,不应误判为账号或功能故障。
- SOP 知识库支持 `.txt/.md/.markdown/.pdf/.doc/.docx/.xls/.xlsx/.ppt/.pptx` 上传到 MinIO 后解析入库,接口为 `POST /api/knowledge/doc/upload`,单文件上限 100MB;管理端上传请求单独放宽到 180s,PDF 解析/归类/向量化较慢时不要改全局 axios 超时。