九、三方登录与三方集成
菜单入口：系统管理 → 三方登录与三方集成。
三方登录（三方应用、三方用户）解决"用微信/钉钉/企微等账号登录本系统"；三方集成（应用配置、用户映射、通讯录同步、消息发送记录）解决"本系统与钉钉/企业微信自建应用的双向打通"（通讯录自动同步 + 业务消息推送）。
9.1 三方应用
菜单入口：系统管理 → 三方应用。
配置各社交平台的登录客户端凭证（client_id / secret），登录页的三方图标能否正常授权由这里决定。
页面操作：
- 查询：按应用名、社交平台、用户类型、客户端编号、状态过滤，搜索执行、重置清空条件；
- 新增：填写应用名、社交平台（微信/钉钉/企微等）、用户类型、客户端编号（client_id）、客户端密钥（client_secret）、状态等。
| 列 | 说明 |
|---|---|
| 应用名 / 社交平台 | 如"企业微信登录" / 平台类型 |
| 用户类型 | 该登录通道面向的用户类型 |
| 客户端编号 | 服务商侧分配的 client_id |
| 状态 | 启用后登录页展示对应图标 |
业务规则：
- 凭证（client_id/secret）来自三方开放平台创建的应用，须与开放平台后台完全一致；
- 三方应用通常还需在开放平台配置授权回调域名，指向本系统登录页；
- 三方登录流程（经代码验证）：用户在登录页点三方图标 → 跳转三方授权 → 回调本系统。已绑定系统账号的直接登录；未绑定的会提示"未绑定账号，需要进行绑定"，转入绑定页，输入本系统的账号密码完成绑定后即可登录（首次三方登录不会自动注册新账号）；绑定与解绑也可在"个人中心 → 社交账号"中维护。
数据变动：写入三方客户端配置表。该配置被登录页三方授权流程读取；授权成功产生/更新的三方用户档案记录在三方用户。
9.2 三方用户
菜单入口：系统管理 → 三方用户。
查看三方授权用户与本系统账号的绑定档案（openid ↔ 系统用户）。
页面操作：
- 查询：按社交平台、用户昵称、社交 openid、创建时间过滤，搜索执行、重置清空条件。
| 列 | 说明 |
|---|---|
| 社交平台 / 社交 openid | 三方侧的平台与唯一标识 |
| 用户昵称 / 用户头像 | 三方返回的显示信息 |
| 创建时间 / 更新时间 | 首次授权与最近授权时间 |
业务规则：
- 数据由用户三方授权时自动生成/更新（含昵称、头像等快照），页面只读；
- 解绑操作一般在用户"个人中心 → 社交账号"进行，解绑后该三方账号将无法直接登录，需重新绑定；
- 同一三方账号重复授权时更新快照，不会产生重复档案。
数据变动：只读页面；数据由三方授权动作自动写入。绑定关系决定三方登录能落到哪个系统账号。
9.3 三方集成-应用配置
菜单入口：系统管理 → 三方集成 → 应用配置。
配置与外部平台（钉钉/企业微信自建应用）集成的凭证，是三方集成的总开关。
页面操作：
- 查询：按集成渠道过滤，搜索执行、重置清空条件；
- 新增：选择集成渠道（钉钉/企业微信）、填写应用 Key、AgentId、Secret、状态、备注。
| 列 | 说明 |
|---|---|
| 集成渠道 | 对接的平台类型（DINGTALK 钉钉 / WECOM 企业微信） |
| 应用 Key / AgentId | 三方自建应用的标识 |
| 状态 | 启停控制整个集成开关 |
| 备注 / 更新时间 | 说明与最近修改 |
业务规则：
- 应用 Key、AgentId、Secret 来自钉钉/企微开放平台创建的自建应用，需为该应用开通通讯录读取与消息推送权限；
- 状态停用即关闭该渠道集成：通讯录同步、消息推送、免登全部停止；
- 企微回调校验（Token/aesKey）也从本配置读取，凭证变更后需在三方平台同步更新回调配置。
数据变动：写入集成应用配置表。被通讯录同步、用户映射、消息发送、三方免登共同读取；修改密钥后建议立即手动执行一次通讯录同步验证连通性。
9.4 三方集成-用户映射
菜单入口：系统管理 → 三方集成 → 用户映射。
维护"三方平台账号 ↔ 本系统用户"的对应表，是消息能精准推送的前提。
页面操作：
- 查询：按集成渠道、状态、三方姓名过滤，搜索执行、重置清空条件；
- 人工绑定/调整映射：对"待处理"记录指定对应的本系统用户。
| 列 | 说明 |
|---|---|
| 集成渠道 / 三方姓名 / 三方用户 ID | 三方侧身份 |
| 员工工号 / 手机号 | 本系统侧匹配依据 |
| 状态 | 已生效 / 待处理等 |
| 匹配方式 | 自动（工号/手机号）或人工 |
| 待处理原因 | 自动匹配失败的原因（如"工号与手机号均未匹配到员工"） |
业务规则（经代码验证，自动匹配顺序）：
- 工号精确匹配 → 2. 手机号精确匹配 → 3. 都未命中的进入待处理队列并记录待处理原因；
- 待处理记录经人工绑定后生效，下次同步即按新映射执行；
- 同步时已生效的映射会自动刷新三方侧快照（姓名/部门等），无需人工维护。
数据变动：映射数据由通讯录同步自动建立/更新，人工绑定写入对应关系。该数据被消息推送（按用户定向推送时换算三方用户 ID）和免登使用；三方侧成员离职时映射会被回调自动失效。
9.5 三方集成-通讯录同步
菜单入口：系统管理 → 三方集成 → 通讯录同步。
从钉钉/企微拉取通讯录并同步到本系统，每次同步生成一条含统计的执行记录。
页面操作：
- 查询：按集成渠道过滤，搜索执行、重置清空条件；
- 立即同步：手动触发一次所选渠道的通讯录拉取，执行完成后刷新列表查看本次统计。
| 列 | 说明 |
|---|---|
| 集成渠道 / 同步类型 | 渠道与同步内容 |
| 触发方式 | 手动 / 定时 / 回调 |
| 总数 / 成功 / 失败 | 本次同步的总量与结果 |
| 已匹配 / 待处理 | 自动建立映射数与需人工处理数 |
| 结果 / 创建时间 | 执行结论与时间 |
业务规则（经代码验证）：
- 触发方式有三种：手动（点立即同步）、定时（后台定时任务按渠道自动执行）、回调（三方侧通讯录变更事件触发增量处理）；
- 同步内容会按白名单字段（工号、姓名、手机、邮箱、性别、部门名、职位名）写入/更新 HRM 员工档案，并按"工号 → 手机号"自动建立用户映射（见9.4）；
- 三方侧成员离职事件（如企微 user_leave）会自动失效对应映射并标记 HRM 员工离职；
- 首次使用建议先小范围验证：同步后核对"已匹配/待处理"比例，处理完待处理再放开定时同步。
数据变动：同步会更新 HRM 员工档案、写入用户映射关系、生成本条同步记录。该链路决定了消息推送能否按人送达。
9.6 三方集成-消息发送记录
菜单入口：系统管理 → 三方集成 → 消息发送记录。
业务消息推送三方（如钉钉工作通知/企微应用消息）的发送流水。
页面操作：
- 查询：按集成渠道、发送状态、接收人 ID 过滤，搜索执行、重置清空条件。
| 列 | 说明 |
|---|---|
| 集成渠道 / 标题 / 内容 | 推送渠道与消息体 |
| 接收维度 / 接收人 ID / 三方用户 ID | 接收范围（按员工全员 / 按指定用户）与最终换算的三方 ID |
| 发送状态 / 错误信息 | 是否送达与失败原因 |
| 重试次数 | 失败重发的次数 |
业务规则：
- 接收维度按员工（全员可收）推送时不要求映射；按指定用户推送时依赖用户映射换算三方 ID，映射缺失会导致发送失败（此时先到用户映射补齐）；
- 发送失败会记录具体错误信息与重试次数，用于排查"推送不到"；
- 页面只读，仅支持查询。
数据变动：只读页面；数据由业务事件推送三方时自动写入。错误信息与重试次数是定位三方推送问题的核心依据。
9.7 常见问题
Q：短信发不出去怎么排查？ 先到"消息中心 → 短信日志"查该手机号的发送状态：有日志且发送失败 → 检查短信渠道的 API 账号/密钥是否正确；无日志 → 业务侧根本没触发发送。若服务商侧报模板错误，核对短信模板的"短信 API 的模板编号"与服务商后台审核通过的模板 ID 是否一致，再用模板的测试按钮试发验证。
Q：邮件发送失败怎么排查？ 依次检查：① 邮箱账号的 SMTP 服务器域名/端口与加密方式是否匹配（465→SSL、587→STARTTLS）；② 密码是否为邮箱授权码（非登录密码）、是否过期；③ 服务器网络能否访问对应 SMTP 端口。配置改动后用邮件模版的测试按钮试发验证。
Q：改了角色/菜单权限，用户说没生效？ 权限有会话级缓存，让用户退出重新登录（或刷新浏览器页面）后再确认；仍未生效再检查角色是否勾选了对应菜单、用户是否真的挂了该角色（见用户管理），以及相关变更可在操作日志中核实是否保存成功。
Q：三方登录（钉钉/企微/微信）点图标后报错或提示未绑定？ 提示"未绑定账号"属正常流程：在绑定页输入本系统账号密码完成绑定即可。若授权直接报错，检查"三方应用"里的 client_id/client_secret 是否与三方开放平台一致，以及开放平台后台的授权回调域名是否已配置为本系统地址。
Q：通讯录同步后出现一堆"待处理"用户怎么办？ "待处理"= 该三方成员的工号、手机号都匹配不到本系统员工（经代码验证按"工号 → 手机号"顺序匹配）。处理：到"三方集成 → 用户映射"筛选待处理记录，人工绑定对应系统用户；同时建议在 HRM 补齐这些员工的工号/手机号档案，下次同步即可自动匹配。绑定完成后无需重发消息，后续推送自动按新映射执行。
📖 相关文档
- 消息中心（短信/邮件/站内信渠道配置）
- 组织与岗位（通讯录同步写入的员工组织归属）
- 审计日志与 OAuth2（OAuth2 客户端与令牌管理）
- 使用手册首页