docs(org): record the incremental employee sync contract

Document the `/api/aihr/org/sync-changes` change feed shipped in 30ef6a8f:
`employee.id` is the stable subject key, the dry-run-then-apply order, and the
fail-closed rules that full `/sync` keeps for masked phone numbers and
duplicate memberships. Adds the endpoint row and a curl example alongside the
existing full-sync entry.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -72,7 +72,7 @@
 - 批量资料和所有视频只走 `/api/knowledge/doc/upload-async` 异步队列；同步 `/api/knowledge/doc/upload` 仅供 SOP 单文件即时预览，禁止把重加工塞回请求线程。格式、大小、超时、OCR/视频解析和重试契约以 `docs/API_INTEGRATION.md` 为准；图片无可用视觉结果时保持「待处理」，视频关键帧不得退回纯 OCR。
 - 资料处理页只保留异步“批量导入”，不得恢复浏览器选目录、服务端目录导入或任务面板；目录导入接口仅供后端运维/调试，且路径必须位于 `aihr.import.root` 下。
 - `ruoyi-ai` 只按 `docs/RUOYI_AI_INCREMENTAL_MIGRATION.md` 分片迁移到 `ruoyi-aihr`，不要整包搬 `ruoyi-chat`；已落地页面保持真实接口/模型优先与 seed fallback，不能退回静态壳。
-- 自有业务表统一使用 `aihr_*`；当前表、接口和同步契约以 `docs/API_INTEGRATION.md`、TechSpec 与正式 SQL 迁移为准。组织快照为 `aihr_org_snapshot`：本地 reset 可有 Demo seed，生产/试点只从开放组织系统同步。
+- 自有业务表统一使用 `aihr_*`；当前表、接口和同步契约以 `docs/API_INTEGRATION.md`、TechSpec 与正式 SQL 迁移为准。组织快照为 `aihr_org_snapshot`：本地 reset 可有 Demo seed，生产/试点只从开放组织系统同步。组织主体身份以稳定 `employee.id` 为准（`employee_number` 不可靠，仅个位数匹配既有主体）；日常岗位/人员变更用 `POST /api/aihr/org/sync-changes` 增量（先 `dryRun=true` 再以同起点 `dryRun=false`），全量 `/sync` 遇脱敏手机号或重复成员关系一律 fail-closed，不得用 `allowPartialReplace` 绕过身份漂移或把手机号刷空。
 
 ## 业务文档
 

docs/API_INTEGRATION.md

@@ -24,7 +24,8 @@
 | 员工直通车 `/pages/user/direct/index`、管理端 `/content/direct` | 员工 `GET /api/aihr/direct/channels`、`POST /api/aihr/direct/feedback`、`GET /api/aihr/direct/mine`、`GET /api/aihr/direct/mine/{id}`；处理端 `GET /api/aihr/direct/admin/feedback`、`POST /api/aihr/direct/admin/feedback/{id}/reply` | 员工可选择总裁、财务、人力、审计、运营并点对点提交；反馈内容支持语音转文字输入（复用 `/api/ai/asr`；文字为主路径，录音不可用或权限失败仅提示改文字输入）。总裁/审计默认匿名；匿名仅表示业务处理界面不显示提交人，系统仍保存内部账号和姓名快照供本人查询、幂等与审计。`direct_president/direct_finance/direct_hr/direct_audit/direct_operations` 仅处理各自频道，`superadmin` 可处理全部；列表、详情和回复均由服务端按角色收窄。一个反馈只允许一次正式回复，员工可在“我的反馈”查看状态和回复；当前不扩展为工单 SLA、转派或多轮聊天。 |
 | 成果投稿（当前页面名“工作上报”）`/pages/user/report/index` | `POST /api/aihr/work-report/organize`、`POST /attachment`、`POST /reports`、`GET /reports/mine`；主管/运营另有列表和审核接口 | 只承载 CASE/VIDEO/SOP/KNOWLEDGE 四类投稿。会话式页面、无状态整理、附件、幂等正式提交和历史状态已部署；审核通过不自动入知识库。当前整理服务不读取图片/视频内容，只把附件名称作为不可信元数据；不得与日常工作记录或“今日工作成果”混用 |
 | 资料处理 `/knowledge/processing` | `GET /api/knowledge/processing/overview`、`POST /api/knowledge/doc/upload-async`、`GET /api/knowledge/doc/upload-items`、`POST /api/knowledge/doc/upload-items/{id}/retry` | 已接入解析任务状态聚合；页面只保留“批量导入”，接口暂存+入队即秒回，后台 worker（并发 2）逐条解析/归类/向量化；ZIP 在 worker 内安全解压后把支持的子文件继续入同一批次队列，页面按批次轮询进度、失败可单文件重试；不提供浏览器目录选择或服务端目录导入入口 |
-| 组织人员同步 | `POST /api/aihr/org/sync` | 从开放组织同步系统的 `/api/open/v1/sync/snapshot` 拉取 `company/department/employee/employee_project_assignment` 快照，分页参数使用 `limit`；员工手机号只落 `person_phone` 用于移动端身份映射，不在组织列表响应暴露；岗位识别 `position/job_title/post/job_name/role/title` 等字段。`dryRun` 必须显式传入 `true`（预检）或 `false`（写入），省略或传 `null` 直接拒绝，避免空请求意外写库；默认 `replaceExisting=true`，写入前必须先用 `{"dryRun":true}`；dry-run 不访问本地快照表、不执行 DDL/写库，返回 `phoneLinked/maskedPhone/suspectText/warnings` 且 `syncedCount=0`。非 dry-run 覆盖写入遇到员工被跳过、手机号不完整、脱敏手机号或疑似乱码时默认拒绝，只有确认 dry-run 结果后显式传 `allowPartialReplace=true` 才允许覆盖。相同员工可由多条有效项目分配展开为多个项目成员行，唯一约束为 `tenant_id + project_code + ext_party_id`；只拒绝同一项目内的重复成员关系。`replaceExisting=false` 不触发不完整快照覆盖闸门，但仍拒绝同项目重复关系。2026-07-15 线上已用 `/api/open/v1` 前缀完成配置、dry-run 和覆盖同步：开放平台返回公司 17、部门 963、员工 3417；生产 `aihr_org_snapshot` 为 3417 行，`phoneLinked=3392`、`maskedPhone=25`、`suspectText=0`，在职 2943、离职 474。该统计发生在多项目成员迁移前；发布迁移后必须重新 dry-run 并核对展开后的项目成员行数。当前剩余 25 人手机号不可用属于上游数据质量问题 |
+| 组织人员同步 | `POST /api/aihr/org/sync` | 从开放组织同步系统的 `/api/open/v1/sync/snapshot` 拉取 `company/department/employee/employee_project_assignment` 快照，分页参数使用 `limit`；员工手机号只落 `person_phone` 用于移动端身份映射，不在组织列表响应暴露；岗位识别 `position/job_title/post/job_name/role/title` 等字段。`dryRun` 必须显式传入 `true`（预检）或 `false`（写入），省略或传 `null` 直接拒绝；默认 `replaceExisting=true`，写入前必须先运行 `{"dryRun":true}`。dry-run 不访问本地快照表、不执行 DDL/写库，返回 `phoneLinked/maskedPhone/suspectText/warnings` 且 `syncedCount=0`。非 dry-run 写入（含 `replaceExisting=false`）遇到脱敏手机号一律默认拒绝，避免空值覆盖本地登录身份；覆盖写入遇到员工被跳过、手机号不完整、疑似乱码或同项目重复关系时同样默认拒绝；`allowPartialReplace=true` 只能在身份字段契约一致且异常逐项确认后使用，不能绕过主体身份漂移或重复成员关系，此时脱敏员工的本地既有有效手机号会被保留而非清空。相同员工可由多条有效项目分配展开为多个项目成员行，唯一约束为 `tenant_id + project_code + ext_party_id`。2026-07-25 生产安全状态：既有快照 3417 行、2938 人在职、3392 个手机号映射；姓名已按稳定 `employee_id` 定向补齐，未执行全量覆盖。当前上游返回 3424 名员工、3398 个脱敏手机号和 1 条重复项目成员关系，优先字段 `employee_number` 仅匹配既有主体 `7/3417`，稳定 `employee_id` 匹配 `3417/3417`；全量覆盖仍只允许 dry-run，日常岗位变化使用下方增量接口。 |
+| 组织人员增量同步 | `POST /api/aihr/org/sync-changes` | 主动拉取上游 `/sync/changes?resource_type=employee`，即使事件没有进入 outbox、`changed_fields` 为空，也会按 `resource_id` 回源 `/employees/{id}`，并结合任职快照只替换受影响员工。主体固定使用稳定 `employee.id`；上游只返回脱敏手机号时保留本地既有有效手机号，上游显式清空手机号时同步清除本地值（对应移动端登录身份失效），手机号字段整体缺失则拒绝写入；范围字段明确不一致视为迁出，写入时删除该员工本地旧记录，范围字段缺失则保守跳过不删。任职快照失败、资源 ID 不一致或项目关系重复时拒绝写入。首次调用必须传 `sinceTime`，后续可传响应的 `nextCursor`；仍须先 `dryRun=true` 再以相同起点执行 `dryRun=false`，且只处理当前租户有效组织绑定范围。 |
 | 移动端手机号登录 | `GET /resource/sms/code`、`POST /auth/mobile/sms-login` | 已复用 sms4j 阿里云配置 `config1` 和 RuoYi `sms` 授权策略；移动专用接口固定服务端默认租户，客户端不传也不能选择 `tenantId`；验证码按“默认租户 + 手机号”隔离。校验在手机号粒度的分布式锁内完成：仅匹配成功才消费，输错不会作废原验证码。移动端令牌只关联 `app_user`；若同一手机号存在任何后台/系统账号（即使同时存在 `app_user`），一律拒绝登录而不复用或并置身份；手机号完全不存在时才自动注册 `app_user`。`aihr.sms.dev-fixed-code` 非空时不真发短信、验证码固定（dev 默认 `123456`）。prod 默认关闭，试点期只有同时设置 `AIHR_SMS_DEV_FIXED_CODE` 与 `AIHR_SMS_PROD_FIXED_CODE_ENABLED=true` 才启用固定码。 |
 | 用户侧三端首页 `mobile-uni` hash 路由；旧 `/h5/user`、`/h5/candidate`、`/h5/supervisor` 兼容重定向 | `GET /api/aihr/mobile/home/{role}` | 未登录请求只返回不读取租户业务统计的公开首屏 seed；已登录移动端请求自动携带 `Authorization/clientid`，才返回员工/主管真实统计；移动端本地 fallback 保演示 |
 | 移动端登录后角色识别 | `GET /api/aihr/mobile/me` | 认证后仅以手机号精确查询 `person_phone`（`activeByMobilePhone`，不使用组织模糊搜索）；`position_level` 为“主管/项目经理”时进入主管端，否则进入员工端。响应返回去重后的 `projects[]` 供页面按项目名称选择，不要求用户输入或记忆编码；同一人员在多个项目的快照行按 `tenant_id + project_code + ext_party_id` 保留。接口失败回退员工端。 |
@@ -180,6 +181,17 @@ curl -fsS "$API_BASE/api/aihr/org/sync" \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"dryRun":false,"replaceExisting":true,"allowPartialReplace":true}'
+
+# 上游岗位等员工字段发生变化时，先增量预检，再以同一起点局部写入
+curl -fsS "$API_BASE/api/aihr/org/sync-changes" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"dryRun":true,"sinceTime":"2026-07-25 16:00:00","pageSize":500}'
+
+curl -fsS "$API_BASE/api/aihr/org/sync-changes" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"dryRun":false,"sinceTime":"2026-07-25 16:00:00","pageSize":500}'
 ```
 
 ## 前端落点