feat(aihr): support signed position mappings

docs/API_INTEGRATION.md

@@ -15,7 +15,7 @@
 | 案例媒体安全 | `GET /api/knowledge/case/records/{caseId}/media` | 案例详情只返回 `mediaOssId`，不返回原始 `sys_oss.url`；媒体下载会重复执行登录、后台角色或 APP 项目范围校验，再由服务端流式读取 OSS。管理端与 `mobile-uni` 通过鉴权 blob/temp 文件播放，关闭详情页时释放本地对象 URL |
 | SOP知识库 `/knowledge/sop` | `POST /api/knowledge/search`、`POST /api/knowledge/answer-feedback`、`GET /api/knowledge/position-sop`、`GET /api/aihr/mobile/onboard/tasks`、`POST /api/aihr/mobile/onboard/tasks/{id}/complete`、`GET /api/aihr/mobile/qualification`、`POST /api/knowledge/doc/upload` | 已接入 MySQL Fulltext + Qdrant 混合召回、岗位学习适配摘要、OSS-first 文档上传、txt/md/PDF/Word/Excel/PPT 解析和 embedding 写入，失败回退 seed；搜索返回 `reviewId` 与 `promptVersion`，员工反馈回传并保存该评审批次，SOP 人工评审记录同时保留答案生成提示词版本，管理端可继续复核；员工学习页按当前 APP 身份读取正式岗前/入职任务，员工只能将本人处于“待完成/进行中”的任务确认完成，服务端按组织快照/手机号归属更新 `status/completed_time`，不接受前端身份参数；资格证据无正式数据时明确返回 `NOT_CONFIGURED`，不以 AI 分数代替上岗资格；`position-sop` 仍保留一期生活顾问学习导航语义 |
 | 资料处理 `/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` 快照，分页参数使用 `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` 才允许覆盖；重复 `ext_party_id` 始终拒绝写入。2026-07-15 线上已完成覆盖同步：公司 17、部门 963、员工 3417，`phoneLinked=3392`、`maskedPhone=25`、`suspectText=0`，在职 2943、离职 474。当前开放员工项只有 `position_id`，没有上述岗位名称字段，开放 API 也无岗位字典资源；生产岗位统一回退为“员工/一线”，主管数为 0。人员/手机号同步已就绪，但主管身份与项目权限仍依赖上游岗位字段/字典或 HR 正式映射 |
+| 组织人员同步 | `POST /api/aihr/org/sync` | 从开放组织同步系统的 `/api/open/v1/sync/snapshot` 拉取 `company/department/employee` 快照，分页参数使用 `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` 才允许覆盖；重复 `ext_party_id` 始终拒绝写入。外部员工缺岗位名称时，可由运维配置 HR 签认的 `AIHR_ORG_POSITION_MAP_JSON`，按 `position_id` 填充岗位名称/层级；外部显式岗位字段优先，映射层级只允许“一线/主管/项目经理”。2026-07-15 线上已完成覆盖同步：公司 17、部门 963、员工 3417，`phoneLinked=3392`、`maskedPhone=25`、`suspectText=0`，在职 2943、离职 474。当前开放员工项只有 `position_id`，没有上述岗位名称字段，开放 API 也无岗位字典资源；生产尚未配置签认映射，岗位统一回退为“员工/一线”，主管数为 0 |
 | 移动端手机号登录 | `GET /resource/sms/code`、`POST /auth/mobile/sms-login` | 已复用 sms4j 阿里云配置 `config1` 和 RuoYi `sms` 授权策略；短信发送成功后才写 Redis 验证码；手机号不存在时自动注册 `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` | 认证后按手机号匹配组织快照；`position_level` 为“主管/项目经理”时进入主管端，否则进入员工端；接口失败回退员工端。生产当前因上游岗位字段缺失只能识别为“一线”，不能用手工选择生活顾问替代主管身份验收 |
@@ -101,6 +101,7 @@ Qdrant 本地默认值可不配；需要覆盖时用 JVM property 或环境变
 | `AIHR_ORG_SYNC_CLIENT_ID` / `-Daihr.org-sync.client-id` | 空 | 开放平台应用 `client_id`，也用于签名头 `X-Client-Id` |
 | `AIHR_ORG_SYNC_CLIENT_SECRET` / `-Daihr.org-sync.client-secret` | 空 | `POST /auth/token` 换取访问令牌 |
 | `AIHR_ORG_SYNC_SIGNING_SECRET` / `-Daihr.org-sync.signing-secret` | 空 | 可选 HMAC-SHA256 签名密钥；为空时使用 `AIHR_ORG_SYNC_CLIENT_SECRET`，业务请求带 `X-Client-Secret/X-Timestamp/X-Nonce/X-Signature`，签名 path 必须包含 `/api/open/v1` |
+| `AIHR_ORG_POSITION_MAP_JSON` / `-Daihr.org-sync.position-map-json` | 空 | HR 签认岗位映射，例如 `{"1683":{"name":"项目经理","level":"项目经理"}}`；只在外部员工缺岗位名称时按 `position_id` 兜底，层级仅允许“一线/主管/项目经理”，dry-run 的 `warnings` 会返回映射命中人数及解析出的主管/项目经理人数 |
 
 本地启动脚本会先加载根目录 `.env.local`，再加载 `backend/.env`。如果 `backend/.env` 沿用开放平台字段名 `client_id` / `client_secret`，脚本会映射为 `AIHR_ORG_SYNC_CLIENT_ID` / `AIHR_ORG_SYNC_CLIENT_SECRET`。
 

docs/BRD_IMPLEMENTATION_AUDIT.md

@@ -22,7 +22,9 @@
 
 - 2026-07-15 开放平台岗位契约复核：直接只读检查外部快照键，员工项包含 `position_id`，但不包含 `position_name/job_title/post_name/job_name/role_name/title`；单员工详情同样只有 `position_id`，`position/positions/post` 快照资源均不可用。因此不能在 AIHR 端猜测 `position_id` 角色，需开放平台补岗位名称/岗位字典，或由 HR 签字提供 `position_id → 岗位名称/主管层级` 映射后重新同步。当前生产只读缺口为 SOP 文档 `3/5`、案例 `0/20`、校准 `0/20`、SOP 人工评审 `0`、满意度 `0`、候选资料 `0`、正式岗位适用 `0`、入职任务 `0`、资格门禁 `0`；在职手机号可用 `2927/2943`。
 
-- 2026-07-15 B11 岗位映射输入准备：按现有开放平台鉴权契约只读遍历员工快照并仅聚合非 PII 字段，得到 `90` 个不同 `position_id`，合计员工 `3417`、在职 `2943`，与生产组织快照总量一致；已生成 `docs/BRD-B11岗位映射签认清单-20260715.csv`，供 HR 填写岗位名称、层级和主管标记。进一步核对确认生产 `aihr_org_snapshot` 当前没有 `position_id` 列，现有同步也未持久化该字段；因此短期 HR 映射必须先由开放平台套用并随员工快照返回岗位名称。若改为本系统持久化/自动套用映射，必须单独批准并先执行 schema 迁移。本轮未修改生产 schema 或业务数据。
+- 2026-07-15 B11 岗位映射输入准备：按现有开放平台鉴权契约只读遍历员工快照并仅聚合非 PII 字段，得到 `90` 个不同 `position_id`，合计员工 `3417`、在职 `2943`，与生产组织快照总量一致；已生成 `docs/BRD-B11岗位映射签认清单-20260715.csv`，供 HR 填写岗位名称、层级和主管标记。进一步核对确认生产 `aihr_org_snapshot` 当前没有 `position_id` 列，不能在同步完成后直接按该键回填；可由开放平台随快照返回岗位名称，或由同步服务在写入前套用签认映射。本轮未修改生产 schema 或业务数据。
+
+- 2026-07-15 B11 签认映射最小实现：组织同步新增私密配置 `AIHR_ORG_POSITION_MAP_JSON`，在外部员工缺岗位名称时按 `position_id` 填充 HR 签认的岗位名称/层级；上游显式岗位字段始终优先，配置层级严格限制为“一线/主管/项目经理”，非法配置在同步前直接拒绝。该方案复用现有同步入口和 `position_name/position_level` 字段，不新增表、页面或写接口，也不需要持久化 `position_id`。`AihrOrgSyncServiceTest` 真跑 `13/13` 通过；代码尚未发布，生产映射仍为空，主管数仍为 0。
 
 - 2026-07-15 管理端资料处理分页静态发布：已备份生产根目录至 `/opt/wygj/backups/www-20260715134936`，再同步 `frontend/dist/`；根目录同步未使用 `--delete`，因此未覆盖同目录的 `/h5`。线上 `processing-yUVzof10.js` SHA-256 与本地构建一致。真实管理员会话确认任务分页共 97 页、第二页仍展示 10 条，状态筛选后回到第一页；根站、H5 和租户接口均返回 `200`。本轮未发布后端、迁移数据库或写入业务数据。
 

docs/DEV_SETUP.md

@@ -123,6 +123,7 @@ AIHR_AI_SPEECH_ENABLED=true
 - `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仍用于权限与身份映射。
+- 外部员工只有 `position_id`、没有岗位名称时，可在私密环境配置中设置 HR 签认映射，例如 `AIHR_ORG_POSITION_MAP_JSON='{"1683":{"name":"项目经理","level":"项目经理"}}'`；只允许“一线/主管/项目经理”三种层级，外部显式岗位字段优先。该配置会影响主管权限，必须先 dry-run，再执行覆盖同步并复核主管数与项目范围。
 - 本地组织 seed 带演示手机号，可用 `13900000103` 验证员工端自动识别物业管家岗位，用 `13900000202` 验证主管端项目范围
 - SOP 知识库支持 `.txt/.md/.markdown/.pdf/.doc/.docx/.xls/.xlsx/.ppt/.pptx` 上传到 MinIO 后解析入库，接口为 `POST /api/knowledge/doc/upload`，单文件上限 100MB；管理端上传请求单独放宽到 180s，PDF 解析/归类/向量化较慢时不要改全局 axios 超时。资料处理中心异步接口另支持 `.zip`（≤500MB），后台安全解压后逐文件入队；最多 1000 个子文件、解压总量 ≤2GB，不支持嵌套 ZIP
 - 视频（`.mp4/.mov/.avi/.mkv/.webm/.m4v`，≤500MB、≤60 分钟）只走资料处理中心批量导入（异步队列）：ffmpeg 抽音轨分段调 asr 转写 + 抽关键帧调 vision 提取画面文字，合并后归类切片入库，片段带 `[mm:ss]` 时间戳；**依赖服务器安装 ffmpeg/ffprobe**（macOS `brew install ffmpeg`，Linux `apt install ffmpeg`）

docs/下一步工作计划-BRD对齐-20260715.md

@@ -1,6 +1,6 @@
 # 下一步工作计划(BRD 对齐版)
 
-> 版本:v2.3(2026-07-15 执行复核:发布完成;B11 已生成 90 个岗位 ID 的 HR 签认清单,确认本地快照尚未保存 `position_id`)
+> 版本:v2.4(2026-07-15 执行复核:发布完成;B11 已生成 90 个岗位 ID 的 HR 签认清单并补齐同步时签认映射能力)
 > 基准:《物业AI人力资源系统业务需求文档BRD.md》v1.2(唯一事实源)
 > 阶段边界:《银城员工端APP分阶段实施总纲.md》阶段一(陪练)+ 2026-07-08《数字师傅学练问报整合方案》定案
 > 现状证据:《BRD_IMPLEMENTATION_AUDIT.md》2026-07-15 最新条目 + 本日生产只读复核
@@ -47,7 +47,7 @@
 | # | 需要的输入 | 提供方 | 负责人 | 回复期限 | 兜底触发日 | 阻塞的 BRD 条款 | 不给的后果 |
 |---|---|---|---|---|---|---|---|
 | B3 | **试点项目圈定(1–2 个住宅项目)+ 窗口起止日期 + ≥20 名员工名单 + 每项目至少 1 名主管**(员工可从手机号映射中圈定,主管需与 B11 的正式岗位映射一致) | HR 负责人 | 待指派 | 07-18 | 07-22 | 10.2-D | M5 全部指标无分母;半年会没有"真实使用数据" |
-| B11 | **补齐岗位契约**:开放员工快照直接返回 `position_name/job_title`，或开放岗位字典资源；HR 可直接填写 `BRD-B11岗位映射签认清单-20260715.csv`(90 个岗位 ID,合计 3417 人/在职 2943 人)并提供试点主管名单。当前 `aihr_org_snapshot` 未保存 `position_id`,所以短期映射必须由开放平台套用后随快照返回岗位名称；若要求本系统自动套用,须另行批准 schema 变更并先发布迁移。不得按 ID 猜角色 | 开放平台+HR | 待指派 | 07-18 | 07-22 | 5.4、G3、L1-B | 生产 2943 名在职人员全部落为“一线”，主管端和项目级权限无法认证态验收 |
+| B11 | **补齐岗位契约**:开放员工快照直接返回 `position_name/job_title`，或开放岗位字典资源；HR 可直接填写 `BRD-B11岗位映射签认清单-20260715.csv`(90 个岗位 ID,合计 3417 人/在职 2943 人)并提供试点主管名单。若开放平台短期不能改接口,运维可将签认结果配置为 `AIHR_ORG_POSITION_MAP_JSON`,系统只在外部缺岗位名称时按 `position_id` 套用,层级仅允许“一线/主管/项目经理”；先 dry-run,再覆盖同步并验收项目权限。不得按 ID 猜角色 | 开放平台+HR | 待指派 | 07-18 | 07-22 | 5.4、G3、L1-B | 生产 2943 名在职人员全部落为“一线”，主管端和项目级权限无法认证态验收 |
 | B2 | 补 2 份真实 SOP 文档(现 3/5),并由业务确认全部五类核心流程的成功条件、价格/取消规则、回访口径;随后完成 14 条场景/SOP 的人工评审(现 0/14) | 内容负责人/HR | 待指派 | 07-20 | 07-24 | 4.3.4、L1-B(SOP≥5) | SOP 覆盖与 RAG 可用率(≥80%)无法验收 |
 | B9 | **历史案例批量提供**:试点前 **≥20 条**历史案例语音/材料入库并脱敏审核,不依赖试点新增量补齐验收底线;试点期继续按"每周每项目 1 条"采集新案例 | 各项目负责人 | 待指派 | 07-22 | 07-25 | 4.6、L1-B(案例≥20) | 案例库验收必然失败 |
 | B4 | 方言 ASR 厂商选型(**阶段一只选 1 种方言**,按试点区域确认;BRD 9.1 只要求 1 条路径)+ 费用授权 + **同时确认 CER 达标阈值**(BRD 只定了 ≤5s 响应,识别准确率的验收线需业务拍板,否则 C3 实测无法判定"达标") | 技术组+HR | 待指派 | 07-20 | 07-24 | 4.3.3、9.1、L1-C | MVP 阻塞项零实测,且测了也无法判定通过 |
@@ -118,7 +118,7 @@
 ## 7. 风险与止损
 
 1. **B3 试点圈定拖延是当前最大单点风险**(组织数据已就位,决策成本已最低):07-22 仍无答复,升级 HR 负责人;试点每晚一周,半年会"真实使用数据"窗口就少一周。
-2. **B11 主管岗位缺失**:当前开放快照只有 `position_id`,生产主管数为 0;90 个岗位 ID 已整理为 HR 签认清单,但本地快照不保存该键。07-22 前拿不到上游岗位名称/字典,或未批准本系统持久化并套用映射,主管复盘/跨项目权限不能验收,试点只能暂停而不能猜角色替代。
+2. **B11 主管岗位缺失**:当前开放快照只有 `position_id`,生产主管数为 0;90 个岗位 ID 已整理为 HR 签认清单,同步服务已支持签认 JSON 映射且不需改库。07-22 前拿不到上游岗位名称/字典或 HR 正式映射,主管复盘/跨项目权限不能验收,试点只能暂停而不能猜角色替代。
 3. **案例 20 条**:依赖 B9 存量导入;若试点前不足 20 条,立即提高采集频率(每项目每周 2–3 条)并如实下调收口预期,不用未脱敏或演示数据凑数。
 4. **发布失败**:A3 原子流程任一步失败即按备份回滚,当天不重试第二次,先归因。
 5. **范围失控**(BRD 附录 C 头号风险):任何新页面/新功能请求一律进 `docs/BACKLOG.md`;每周对照本计划复盘一次偏差。
@@ -127,4 +127,4 @@
 
 ---
 
-*本计划由工程侧起草,v2.3 已按 2026-07-15 生产执行结果及 B11 外部接口复核修订;B 表负责人/期限需业务方确认后生效。执行进展回写《BRD_IMPLEMENTATION_AUDIT.md》,本文件只改计划不记证据。*
+*本计划由工程侧起草,v2.4 已按 2026-07-15 生产执行结果及 B11 外部接口复核修订;B 表负责人/期限需业务方确认后生效。执行进展回写《BRD_IMPLEMENTATION_AUDIT.md》,本文件只改计划不记证据。*