14 KiB
14 KiB
需求 - 企业微信基础设施规约
版本：1.0 日期：2026-05-09 状态：模块级开发规约 上级事实源：海音达OA-MVP需求规格说明书 相关事实源：需求 - 统一审批中心规约
本规约细化企业微信在 hyb-oa 中的基础设施边界、入口、免登/绑定、通讯录身份、消息通知、deeplink 和打卡原始采集要求。后续企业微信相关开发必须先从本规约拆分 Issue CSV，再进入技术方案和代码实现。
1. 模块目标与边界
1.1 目标
- 企业微信作为
hyb-oa的手机工作台入口、通讯录账号、身份辅助、消息通知和打卡原始采集底座。 - 员工在手机企业微信中进入唯一自建应用
海音达工作台，默认落到 OA 移动端。 - 企业微信消息只做提醒和跳转，审批动作、业务填写、附件查看和正式留痕都在 OA 内完成。
- 企业微信打卡只作为原始采集来源，后续结合 OA 请假、补卡、外出、加班审批形成正式考勤口径。
1.2 不做范围
- 不使用企业微信原生审批作为公司正式审批流。
- 不把企业微信聊天、文件或审批记录作为财务附件主库、业务单据主库或正式审计事实源。
- OA 不重造企业微信打卡采集和风控；ATTV1 起只同步企微打卡摘要并做 OA 考勤解释。
- 首批不在 OA 内重造企业微信打卡的定位、人脸识别、Wi-Fi、排班、设备和防作弊规则。
- 不接入飞书、钉钉或其他办公平台作为首批入口。
2. 角色与权限
| 角色 | 使用目标 | 可做动作 | 权限边界 |
|---|---|---|---|
| 员工 | 从手机进入 OA、接收提醒、完成绑定 | 进入移动工作台、绑定企业微信身份、点击消息 deeplink、查看本人相关业务 | 不能通过企业微信绕过 OA 权限 |
| 审批人 | 在手机端收到待办提醒并回 OA 处理 | 点击通知进入 OA 审批页、在 OA 内审批 | 不能在企业微信原生审批里完成正式审批 |
| 管理员/HR | 管理入口、人员、通讯录同步、绑定异常和离职停用 | 配置可见范围、协助绑定、触发通讯录创建/更新/禁用、处理离职停用、查看通知失败 | 不得手工把一个企业微信身份绑定到多个员工；通讯录同步失败不得回滚 OA 人事主数据 |
| 系统管理员 | 维护企业微信应用配置和消息通道 | 配置 CorpID、AgentID、回调、可信域名、消息开关和重试策略 | 不处理业务审批，不暴露 secret |
| 财务/老板 | 接收关键待办或状态提醒 | 点击 deeplink 回 OA 查看或处理 | 消息中不得出现完整发票、合同正文、敏感报价、银行卡、身份证 |
OA 是员工、账号、角色、数据范围、审批任务和审计的主事实源。企业微信身份和通讯录账号服务于入口、通知、打卡采集和移动工作台，不替代 OA 权限判断。
3. 自建应用与入口
| 场景 | 入口 | 默认落点 | 要求 |
|---|---|---|---|
| 手机企业微信工作台 | 海音达工作台 自建应用 |
/mobile |
已绑定用户直达移动工作台；未绑定用户进入绑定或账号密码回退路径 |
| 企业微信消息 deeplink | 消息卡片或文本链接 | 业务详情或审批页 | 保留目标页面，不只跳首页 |
| 手机普通浏览器 | OA 移动端 URL | /mobile 或登录后移动页 |
不依赖企业微信身份，仍可账号密码登录 |
| PC 浏览器 | OA Web URL | /portal |
PC 用户直接访问 OA，不强制从企业微信进入 |
| 入口失败 | 登录页或错误页 | 账号密码回退 | 提示清晰，不让员工反复重试 |
入口识别应区分企业微信 WebView、普通移动浏览器和 PC 浏览器。企业微信入口只改变登录和跳转体验，不改变业务权限。
4. 免登与绑定
4.1 身份字段
| 字段 | 用途 | 要求 |
|---|---|---|
企业微信 userId |
企业微信成员身份主键 | 与员工绑定时必须唯一 |
| 企业微信手机号 | 辅助匹配员工 | 只能作为候选，不可单独作为登录授权 |
| 企业微信邮箱 | 辅助匹配员工 | 只能作为候选，不可单独作为登录授权 |
OA employee_id |
OA 员工主键 | 权限和业务数据以此为准 |
| 绑定时间 | 审计 | 必须记录 |
| 绑定人/解绑人 | 审计 | 自助绑定和管理员处理都必须记录 |
4.2 绑定规则
- 已绑定且 OA 员工账号正常：从企业微信进入后直达
/mobile或 deeplink 目标页。 - 未绑定：提示“当前企业微信账号尚未绑定”，允许账号密码登录后在个人设置完成绑定。
- 一个企业微信身份只能绑定一个员工。
- 一个员工原则上只绑定一个当前有效企业微信身份；更换账号必须先解绑并留痕。
- 员工离职、账号停用或组织权限移除后，企业微信入口不得继续进入 OA 业务页面。
- 绑定、解绑、绑定失败、停用拦截都必须写入审计日志。
4.3 状态与记录
| 对象 | 状态 | 含义 | 记录要求 |
|---|---|---|---|
| 入口配置 | 未启用 | 企业微信入口不展示或提示不可用 | 记录配置状态，不影响账号密码登录 |
| 入口配置 | 已启用 | 企业微信工作台可进入 OA | 记录启用人、启用时间和可见范围 |
| 绑定关系 | 未绑定 | 企业微信身份尚未关联 OA 员工 | 可回退账号密码登录 |
| 绑定关系 | 已绑定 | 企业微信身份已关联有效 OA 员工 | 记录绑定时间、绑定方式和员工 ID |
| 绑定关系 | 已解绑 | 绑定关系被员工或管理员解除 | 记录解绑人、解绑时间和原因 |
| 绑定关系 | 已停用 | 员工离职、停用或组织权限移除 | 阻断企业微信入口进入业务页面 |
| 通知记录 | 待发送 | 主业务已产生通知任务 | 不阻断主业务 |
| 通知记录 | 已发送 | 企业微信消息发送成功 | 记录接收人和 deeplink |
| 通知记录 | 发送失败 | 企业微信消息发送失败 | 记录失败原因和重试次数 |
| 通知记录 | 已放弃 | 达到重试上限或配置不可用 | 管理员可查看原因 |
状态变更必须写入审计或操作日志。入口、绑定和通知状态不得替代 OA 业务单据状态。
4.4 异常规则
| 异常 | 处理规则 | 用户提示 |
|---|---|---|
| 未绑定 | 回退账号密码登录，登录后可自助绑定 | “当前企业微信账号尚未绑定，请先使用 OA 账号登录并完成绑定” |
| 重复绑定 | 阻断，并提示联系管理员 | “该企业微信账号已绑定其他员工” |
| OA 账号停用 | 阻断进入业务页面 | “账号已停用，请联系管理员” |
| 企业微信回调失败 | 不创建会话，回退登录页 | “企业微信登录失败，请重试或使用账号密码登录” |
| 回跳地址不允许 | 阻断并记录安全日志 | “回跳地址无效，请从工作台重新进入” |
| 配置缺失 | 企业微信入口显示不可用或 SKIP | “企业微信入口暂未启用，请使用账号密码登录” |
5. 消息通知与 deeplink
5.1 通知边界
- 企业微信消息只发送脱敏提醒，不承载正式审批动作。
- 消息内容只包含：标题、业务类型、业务编号、状态、处理入口。
- 消息不得包含完整发票图片、合同正文、敏感报价、银行卡、身份证、大段业务说明或密钥。
- 发送失败不阻断主业务提交、审批、付款或归档；失败记录进入可重试状态。
5.2 Deeplink 目标
| 业务场景 | Deeplink 目标 | 要求 |
|---|---|---|
| 审批待办 | /mobile/approvals 或具体任务详情 |
点击后在 OA 内处理审批 |
| 报销提醒 | 移动报销详情或审批任务 | 展示脱敏摘要，附件和发票需按 OA 权限加载 |
| 请假/补卡/外出/加班 | 移动申请详情或审批任务 | 支持查看状态和处理待办 |
| 移动工作台 | /mobile |
作为兜底入口 |
| 绑定入口 | 个人设置或绑定页 | 仅在已账号密码登录后完成绑定 |
deeplink 必须校验目标地址白名单，避免跳转到非 OA 域名或未授权页面。
5.3 通知验收
- 待办产生后，目标审批人能收到脱敏提醒。
- 点击消息后进入 OA 对应移动页面，而不是企业微信原生审批。
- 未登录或会话过期时，完成登录后应尽量回到原 deeplink 目标。
- 通知失败时业务流程仍成功，管理员可查看失败原因和重试状态。
6. 通讯录身份边界
- HRWD 起，OA 驱动企业微信通讯录成员创建、更新和禁用；OA 员工表仍是权限、审批、业务数据和审计的主事实源。
- HCLT 已完成公网真实写入验证：测试员工
HRWDTEST-20260517214548已完成企业微信通讯录 create/update/disable，三次同步均为wecom_contact_synced且errcode=0。 - 新员工在 OA 创建账号和入职记录后，可在
hr_wecom_directory_sync_v1开启且配置完整时同步创建企业微信成员，并写入wecom_identity_bindings.external_user_id。 - OA 调岗、部门、职位、手机号、邮箱变化后，可触发企业微信成员更新；历史审批和历史业务单据不因调岗被改写。
- 离职完成后默认禁用企业微信成员，不删除成员；绑定关系和历史业务记录保留审计。
- 企业微信通讯录同步使用独立通讯录 Secret：
WECOM_CONTACT_SYNC_ENABLED、WECOM_CONTACT_SECRET、WECOM_CONTACT_DEFAULT_DEPARTMENT_ID。不得默认复用应用消息 Secret，除非企业微信后台明确该 Secret 具备通讯录写权限。 - 缺 Secret、缺默认部门或缺通讯录 API 权限时，OA 人事流程照常完成，通讯录同步记录为
SKIP/BLOCKED_BY_EXTERNAL_CONFIG或失败可重试，不伪造成成功。 - 通讯录同步记录只保存 employeeId、脱敏 externalUserId、操作、状态、错误码、重试次数和脱敏摘要；不得保存 access token、Secret、完整手机号、原始 payload 或敏感身份信息。
当前完成度：
| 项目 | 状态 | 当前口径 |
|---|---|---|
| OA 员工生命周期 | DONE |
支持入职、转正、调岗、离职 checklist、账号禁用、会话失效和审计。 |
| OA 驱动企微通讯录创建/更新/禁用 | DONE_LIVE_VERIFIED |
代码、同步记录、员工管理状态和重试入口已部署；HCLT 公网真实写入闭环通过，HRWDTEST-20260517214548 create/update/disable 均返回 errcode=0。其他环境缺 Secret、默认部门或通讯录 API 权限时仍按 SKIP/BLOCKED_BY_EXTERNAL_CONFIG 或失败可重试处理。 |
| 企业微信原生审批 | FROZEN |
不作为正式审批流，入离职、请假、补卡、外出、加班审批均在 OA 内留痕。 |
7. 打卡原始采集边界
- 企业微信打卡用于原始采集，保留其定位、人脸识别、Wi-Fi、排班和设备能力。
- OA 首批不重造打卡定位、人脸识别、Wi-Fi、排班、设备绑定、防作弊和异常判断引擎。
- ATTV1 新增企微打卡摘要同步、同步批次和 raw hash 留痕；缺 Secret 或 API 权限时同步批次记录
SKIP。 - OA 把企业微信打卡摘要与 OA 请假、补卡、外出、加班审批结果合并，形成正式考勤解释。
- 企业微信打卡异常不直接等于最终考勤异常；最终解释必须结合 OA 审批记录。
REQAUD 复核后，ATTV1 已完成统一入口实现，企业微信打卡边界进一步固定为：
| 项目 | 状态 | 当前口径 |
|---|---|---|
| 企业微信打卡运营使用 | DONE |
员工继续按公司要求使用企业微信打卡，定位、人脸、Wi-Fi、设备和防作弊由企业微信侧承担。 |
| OA 同步企业微信打卡 API | PARTIAL |
同步表、批次、摘要和脱敏错误码已实现；公网真实同步取决于 WECOM_CHECKIN_SECRET 和企微打卡 API 权限。 |
OA 历史 attendance_v1 极简打卡 |
FROZEN_CLOSED |
该模块已从正式入口关闭；旧表保留，旧写接口返回 409，不作为企微打卡能力。 |
| 正式考勤解释 | DONE |
OA 已支持请假、补卡、外出、加班审批和月度解释；不向企业微信原生审批或补卡接口写回。 |
8. 验收场景
| 场景 | 步骤 | 预期结果 |
|---|---|---|
| 已绑定用户直达 | 员工从手机企业微信进入 海音达工作台 |
直达 /mobile 或 deeplink 目标页 |
| 未绑定回退 | 未绑定员工从企业微信进入 | 提示未绑定，可使用账号密码登录后绑定 |
| 重复绑定阻断 | 管理员或员工尝试把同一企业微信身份绑定多个员工 | 操作失败并留下审计记录 |
| 离职停用拦截 | 已停用员工从企业微信入口进入 | 不能进入 OA 业务页面 |
| 审批通知回 OA | 审批待办产生后发送企业微信提醒 | 点击消息进入 OA 审批页，审批动作在 OA 完成 |
| 报销通知脱敏 | 报销状态变化发送提醒 | 消息只有标题、编号、状态和入口，不含完整发票或附件 |
| 通知失败不阻断 | 模拟企业微信消息发送失败 | 主业务成功，通知进入失败可重试 |
| 打卡边界确认 | 员工使用企业微信打卡，OA 查看考勤相关说明 | 文档和界面不暗示 OA 已重造定位、人脸或排班 |
9. 后续开发拆分建议
- A1：企业微信配置探活和入口开关，覆盖启用、禁用、缺配置和 SKIP。
- A2：企业微信 WebView 识别和
/mobile默认入口。 - A3：企业微信 OAuth/免登与账号绑定、解绑、重复绑定阻断。
- A4：离职停用、组织权限和绑定异常拦截。
- A5：企业微信通知 provider 和失败重试，不阻断主业务。
- A6：deeplink 白名单和移动目标页回跳。
- A7：通讯录辅助字段和后续同步边界。
- A8：企业微信打卡 live 同步配置和权限稳定化，缺配置时继续按
SKIP记录。 - A9：企业微信真机 smoke 清单，覆盖工作台入口、绑定、通知和回跳。
涉及真实企业微信凭据、回调域名、可信域名、生产配置或真机验证的 Issue，必须在技术方案中写明配置项、回滚路径和无法自动化时的人工验收步骤。