From 22beadf4db0ceaa75c9cc82f37c82a90d5ffec8b Mon Sep 17 00:00:00 2001 From: kangwenjing <1138819403@qq.com> Date: Thu, 5 Nov 2026 16:41:26 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=E6=B5=81=E7=A8=8B?= =?UTF-8?q?=E6=98=8E=E7=BB=86=E5=AF=BC=E5=87=BA=E5=8A=9F=E8=83=BD=E5=8F=8A?= =?UTF-8?q?=E7=9B=B8=E5=85=B3=E4=BC=98=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增流程明细导出页面、权限码与接口;优化消息通知推送逻辑,将外发任务叫醒通路统一管理;修复移动端表单展示逻辑,优化同步历史与投递记录明细显示;调整生产环境配置与镜像版本,适配新功能需求。 --- README.md | 89 +- backend/app/api/export.py | 353 +++-- backend/app/api/notify_channels.py | 196 ++- backend/app/api/org.py | 112 +- backend/app/api/runtime.py | 43 +- backend/app/dbconfig.py | 60 +- backend/app/hubconfig.py | 64 + backend/app/main.py | 17 +- backend/app/models.py | 27 +- backend/app/permissions.py | 8 +- backend/app/schemas.py | 61 + backend/app/service/channels.py | 902 ++++++++++++- backend/app/service/detail_export.py | 1202 +++++++++++++++++ backend/app/service/events.py | 3 + backend/app/service/exportfmt.py | 218 +++ backend/app/service/hub.py | 51 +- backend/app/service/hub_sync.py | 895 +++++++++++- backend/app/service/outbox.py | 56 +- backend/app/service/wake.py | 85 ++ backend/config.toml | 2 +- backend/config.toml.example | 29 + backend/scripts/check_detail_export.py | 621 +++++++++ backend/scripts/check_hub_sync_details.py | 348 +++++ backend/scripts/check_hub_sync_lock_leak.py | 332 +++++ .../scripts/check_hub_sync_lost_account.py | 430 ++++++ backend/scripts/check_hub_sync_shell_units.py | 258 ++++ .../scripts/check_hub_sync_unit_reclaim.py | 334 +++++ .../scripts/check_hub_sync_wecom_mirror.py | 319 +++++ backend/scripts/check_notify_hub.py | 749 ++++++++++ backend/scripts/check_notify_hub_api.py | 350 +++++ backend/scripts/check_notify_landing.py | 212 +++ backend/scripts/check_notify_wake.py | 256 ++++ backend/scripts/check_org_tree_managers.py | 191 ++- backend/scripts/check_presence_guard.py | 35 +- backend/scripts/purge_test_data.py | 7 + deploy/k8s/README.md | 2 +- deploy/k8s/unis-oa.yaml | 44 +- docs/hub-integration.md | 355 ++++- docs/mobile-approval-layout.md | 48 +- docs/mobile-form-layout-config.md | 21 +- docs/notification-channels-design.md | 110 +- docs/process-detail-export-design.md | 437 ++++++ docs/wecom-app-notification-plan.md | 21 +- docs/wecom-work-notification-spec.md | 12 +- frontend/src/api/client.ts | 10 + frontend/src/api/exportDetail.ts | 176 +++ frontend/src/api/hub.ts | 107 +- frontend/src/api/index.ts | 1 + frontend/src/api/notify.ts | 33 +- frontend/src/api/org.ts | 37 + frontend/src/components/layout/AppHeader.vue | 36 +- frontend/src/components/layout/AppSidebar.vue | 1 + .../src/components/oa/FormFieldControl.vue | 10 +- .../oa/HubSyncButton.preview.spec.ts | 254 ++++ frontend/src/components/oa/HubSyncButton.vue | 129 +- frontend/src/components/oa/SyncJobPanel.vue | 22 +- .../src/components/oa/mobile/MobileFold.vue | 7 +- .../oa/mobile/MobileFormReader.spec.ts | 30 + .../components/oa/mobile/MobileFormReader.vue | 2 +- .../oa/mobile/MobileFormSummary.spec.ts | 26 + .../oa/mobile/MobileFormSummary.vue | 15 +- .../oa/mobile/MobileTaskView.spec.ts | 55 +- .../components/oa/mobile/MobileTaskView.vue | 35 +- .../components/oa/mobile/mobileFixtures.ts | 9 +- .../components/oa/mobile/useFormPlan.spec.ts | 78 +- .../src/components/oa/mobile/useFormPlan.ts | 142 +- frontend/src/constants/permissions.ts | 1 + frontend/src/dev/mobilePreview.ts | 58 +- frontend/src/i18n/locales/en.ts | 185 ++- frontend/src/i18n/locales/zh.ts | 184 ++- frontend/src/router/index.ts | 7 + frontend/src/types/index.ts | 61 +- frontend/src/utils/formRuntime.ts | 16 + frontend/src/utils/hubSync.spec.ts | 130 +- frontend/src/utils/hubSync.ts | 62 +- frontend/src/utils/returnPath.spec.ts | 10 + frontend/src/utils/returnPath.ts | 13 +- frontend/src/utils/ssoJump.spec.ts | 104 ++ frontend/src/utils/ssoJump.ts | 117 ++ frontend/src/views/auth/LoginView.sso.spec.ts | 117 ++ frontend/src/views/auth/LoginView.vue | 55 +- .../auth/SsoCallbackView.landing.spec.ts | 140 ++ frontend/src/views/auth/SsoCallbackView.vue | 12 +- .../oa/NotifyChannelView.pagination.spec.ts | 174 +++ .../oa/NotifyChannelView.receiver.spec.ts | 168 +++ frontend/src/views/oa/NotifyChannelView.vue | 259 +++- .../src/views/oa/ProcessDetailExportView.vue | 1072 +++++++++++++++ frontend/src/views/oa/ProfileView.vue | 1 + .../views/oa/SyncScheduleView.options.spec.ts | 288 ++++ frontend/src/views/oa/SyncScheduleView.vue | 156 ++- frontend/src/views/oa/TaskDetailView.vue | 15 + sql/schema.sql | 5 + .../20261105_notify_receiver_field.sql | 28 + 93 files changed, 13978 insertions(+), 640 deletions(-) create mode 100644 backend/app/service/detail_export.py create mode 100644 backend/app/service/exportfmt.py create mode 100644 backend/app/service/wake.py create mode 100644 backend/scripts/check_detail_export.py create mode 100644 backend/scripts/check_hub_sync_details.py create mode 100644 backend/scripts/check_hub_sync_lock_leak.py create mode 100644 backend/scripts/check_hub_sync_lost_account.py create mode 100644 backend/scripts/check_hub_sync_shell_units.py create mode 100644 backend/scripts/check_hub_sync_unit_reclaim.py create mode 100644 backend/scripts/check_hub_sync_wecom_mirror.py create mode 100644 backend/scripts/check_notify_hub.py create mode 100644 backend/scripts/check_notify_hub_api.py create mode 100644 backend/scripts/check_notify_landing.py create mode 100644 backend/scripts/check_notify_wake.py create mode 100644 docs/process-detail-export-design.md create mode 100644 frontend/src/api/exportDetail.ts create mode 100644 frontend/src/components/oa/HubSyncButton.preview.spec.ts create mode 100644 frontend/src/utils/ssoJump.spec.ts create mode 100644 frontend/src/utils/ssoJump.ts create mode 100644 frontend/src/views/auth/LoginView.sso.spec.ts create mode 100644 frontend/src/views/auth/SsoCallbackView.landing.spec.ts create mode 100644 frontend/src/views/oa/NotifyChannelView.pagination.spec.ts create mode 100644 frontend/src/views/oa/NotifyChannelView.receiver.spec.ts create mode 100644 frontend/src/views/oa/ProcessDetailExportView.vue create mode 100644 frontend/src/views/oa/SyncScheduleView.options.spec.ts create mode 100644 sql/upgrade/20261105_notify_receiver_field.sql diff --git a/README.md b/README.md index 92c846b..ebcfb87 100644 --- a/README.md +++ b/README.md @@ -73,6 +73,10 @@ unisoa/ │ ├── scripts/check_selector_kinds.py # 设计器那两问(它是哪一类/和谁重名):跳档省往返、改了组织当场重来 │ ├── scripts/check_write_payload.py # 写接口收尾:报文在提交前拼完、报文与库里逐字段一致、拼不出来就回滚 │ ├── scripts/check_action_surface.py # 批处理/挂起/待阅/评论四条写路径端到端:逐条成事、挂起真冻住、两种待阅口径不互顶 +│ ├── scripts/check_notify_hub.py # 经 Hub 代发企业微信:假 Hub 钉住预算、幂等键、逐人原因分档与请求级错误 +│ ├── scripts/check_notify_hub_api.py # 同一路的接口层:真 TestClient + 假 Hub,验 meta、保存校验、测试发送与回查 +│ ├── scripts/check_notify_landing.py # 卡片点开那一跳的落地侧:ticket+redirect 验票、短码一次性、深链只认站内 +│ ├── scripts/check_notify_wake.py # 渠道提醒与订阅事件什么时候真的发出去:入队提交当场叫醒、回滚与没排上不空叫 │ ├── scripts/check_person_ref.py # 认人只认登录账号:认不出就不是一个人,改名不影响历史 │ ├── scripts/check_identity_refs.py # 配置里的引用不能还压着身份 DN:岗位角色成员要真解析得出人 │ ├── scripts/check_memberships.py # 一个人挂几处岗位:反查与正向解析同口径、且不随人数排队 @@ -81,11 +85,14 @@ unisoa/ │ ├── scripts/check_simulate_paths.py # 设计器逐环节试算:配好的路由能不能真的解析出审批人 │ ├── scripts/check_log_timeline.py # 流转日志时间线:留痕不倒挂、上一条不每趟回库 │ ├── scripts/check_completed_dedup.py # 已办按单折叠:一张单只摆一条,次数与角标/导出/工作台四处同口径 +│ ├── scripts/check_detail_export.py # 流程明细导出:未操作者五类口径、按流程分表与合并表头、七项筛选与两条上限 │ ├── scripts/check_delete_unstarted.py # 待办上删掉还没发起的单:谁能删、删干净没有、额度、嵌页面的账与给第三方的那一句一起收尾 │ ├── scripts/check_begin_resubmit_todo.py # 退回到发起人又重新提交:同一张单在「我的待办」里只留一条(开始环节提交三条路共用) │ ├── scripts/check_leader_lease.py # 多副本那把租约:过期可接管、别人抢不走、库读不动时后台照跑 │ ├── scripts/check_outbox_wake.py # 写回投递的即时性:入队当场叫醒、回滚不空叫、一轮把一张单排着的发干净 │ ├── scripts/check_hub_breaker.py # Hub 不回话时的自保闸:冷却、探测、自检绕开、并发第一波限量(本地造假 Hub) +│ ├── scripts/check_hub_sync_details.py # 同步记录要能核对:改名/让位/认回部门计数成列、名单有界、提示按条留底;三条熔断底线跟着配置走 +│ ├── scripts/check_hub_sync_shell_units.py # Hub 换主键留下的空壳部门:判据、删不掉的三种原因、一键清理只删干净的 │ ├── scripts/check_job_payload.py # 单据详情:定义并发拆开问再拼回,顺序/表单清单/归档分支与串着问一字不差 │ ├── scripts/check_org_tree_managers.py # 部门树的负责人:复用已读进内存的人员行,停用/系统账号/范围外三种照样写得出名字 │ ├── scripts/check_pool_reset.py # 连接归还口径:还回池子的连接一律已自己收尾(含一次故意的脏归还反向自检) @@ -132,7 +139,7 @@ unisoa/ ├── docs/integration-contract.md # 给上游看的接口契约:字段、金额单位、幂等键、批量与对账口径 ├── docs/expense-thirdparty-field-update.md # 费用报销:财务在第三方改审定金额怎么回写 OA(decide 带 data、生产配置与可写字段清单) ├── docs/platform-open-api-design.md # 开放平台:外部系统调 OA 的钥匙 / 作用域 / 限流 / 留痕,与事件推送的分工 -├── docs/notification-channels-design.md # 消息渠道:邮件与钉钉/飞书/企微群机器人,投递留痕、退避重试与死信 +├── docs/notification-channels-design.md # 消息渠道:邮件、三家群机器人、自定义回调,与经 Hub 代发的企业微信应用消息;投递留痕、退避重试与死信 ├── docs/mobile-pwa-design.md # 移动端:为什么是 PWA、离线外壳只兜底不缓存接口、底部导航与安全区 ├── docs/mobile-approval-layout.md # 手机端审批版式:只换版式不换逻辑、首页五张卡片、四问抬头、表单三层归置、bottom sheet ├── docs/mobile-form-layout-config.md # 手机端表单版式配置:手机上只出一节,摆哪几格、什么顺序、每格怎么摆都能配(存 layout.mobile,没动后端) @@ -397,15 +404,15 @@ OA_ENV=prod ./scripts/prod-api.sh # 或者 systemd/docker 里设 OA 这两个文件已从仓库删掉,如果部署机上还留着, 后端启动时会在日志里提醒一句「不再被读取」然后忽略它们,不会被误当成生效配置。 -### 运行配置(113 项,存库即生效) +### 运行配置(123 项,存库即生效) | 组 | 界面上的名字 | 项数 | 都管什么 | | --- | --- | --- | --- | | `site` | 站点信息 | 5 | 站点名、Logo、描述、**系统访问地址**(发出去的邮件与群消息里的单据链接用它拼全链接)、是否开放注册 | | `security` | 登录令牌 | 3 | 访问令牌分钟数、刷新令牌天数、空闲多久要求重新登录 | -| `hub` | 统一身份登录 | 32 | Hub 地址与开关、九个接口各走什么路径、登录模式(含只允许门户免登)、验 token、免登三件套(应用编码 / 应用密钥 / 门户地址)、目录密钥与服务端凭证、Hub 不回话时的两道自保闸(冷却秒数与同时等待上限,见 `docs/hub-integration.md` §14)、应急总闸… | +| `hub` | 统一身份登录 | 33 | Hub 地址与开关、九个接口各走什么路径、登录模式(含只允许门户免登)、验 token、免登三件套(应用编码 / 应用密钥 / 门户地址)、目录密钥与服务端凭证、Hub 不回话时的两道自保闸(冷却秒数与同时等待上限,见 `docs/hub-integration.md` §14)、应急总闸… | | `approval` | 审批口径 | 1 | 是否严格按环节配置找人(关掉会往上级与部门兜底) | -| `hub_sync` | 组织人员同步 | 20 | 定时同步总开关(**只在界面上配**,文件与环境变量不认)与排期(频率 / 时间 / 每周哪几天 / 每月哪几天 / 间隔分钟)、失败补试、增量同步(周期 / 单批条数 / 落后回全量)、停用策略、单次人数上限、按编码认领本地部门… 都在「同步定时任务」这一页配 | +| `hub_sync` | 组织人员同步 | 25 | 定时同步总开关(**只在界面上配**,文件与环境变量不认)与排期(频率 / 时间 / 每周哪几天 / 每月哪几天 / 间隔分钟)、失败补试、增量同步(周期 / 单批条数 / 落后回全量)、停用策略、单次人数上限、按编码认领本地部门、账号让位、**三条熔断底线**(离职停用人数底线 / 部门停用个数底线 / 让位名单的清单人数下限)… 都在「同步定时任务」这一页配 | | `ai` | 大模型能力 | 3 | 调不调大模型的总闸、失败补试次数、日志里记不记提示词原文 | | `hub_perm` | 统一身份权限 | 16 | 从 Hub 取角色 / 权限码 / 数据范围。默认关:关着时权限完全按本系统角色矩阵走 | | `storage` | 文件存放位置 | 16 | MinIO 地址账号密钥桶与上传路径、本地根目录、大小与扩展名限制、超时 | @@ -456,6 +463,8 @@ OA_ENV=prod ./scripts/prod-api.sh # 或者 systemd/docker 里设 OA | `OA_HUB_SERVICE_TOKEN`(或 `OA_HUB_SERVICE_ACCOUNT` + `..._PASSWORD`) | 空 | 老的 Bearer token 口径,没配目录密钥时才用 | | `OA_HUB_SYNC_WHEN` / `OA_HUB_SYNC_TIME` | `daily` / `01:00` | 定时全量同步的频率(`daily`/`weekly`/`monthly`/`interval`)与时间点,配套 `..._WEEKDAYS` / `..._MONTHDAYS` / `..._INTERVAL_MINUTES`(见「同步定时任务」)。「允许定时同步」那个总开关**不在这里**,只在界面上配 | | `OA_HUB_SYNC_OFFBOARD` / `OA_HUB_SYNC_MEMBER_LIMIT` | `true` / `5000` | Hub 消失的人是否停用 / 单次人员上限 | +| `OA_HUB_SYNC_OFFBOARD_GUARD_PERCENT` | `40` | **离职停用熔断**:一趟里等着停用的人超过本地同步账号总数的这个百分比(且超过 20 人)时,这一趟一个都不停用,只报数并标成 `partial`;`0` = 关掉。Hub 换环境/重导数据时不至于把整家公司判成离职。同一个百分比也管部门:要停用的部门超过 `max(5, 同步部门数 × 百分比)` 时一个都不停 | +| `OA_HUB_SYNC_RECLAIM_LOST_ACCOUNTS` | `true` | **僵尸账号让位**:已停用、且这一趟完整清单里查无此人的同步账号,把登录名腾开(改成 `hub-lost--<原名>`,人与权限都不动),Hub 的现任主人当趟就能拿回账号名。只在人数对得上的**全量**同步里生效:增量事件、被截断或突然缩水的清单(Hub 正在清库/重导)一律不让位 | | `OA_HUB_SYNC_BIND_LOCAL_BY_CODE` | `true` | 本系统自建的部门若编码与 Hub 某个部门一一对上,就认成同一个部门(补 `hub_org_id`),不另建重名部门 | | `OA_HUB_DIRECTORY_NEEDS_TOKEN` | `false` | 老口径:目录接口除密钥外还要带 Bearer token 时打开 | | `OA_HUB_PASSWORD_MANAGED_BY_HUB` | `false` | 密码归 Hub 管,本地不再设/改登录密码 | @@ -1280,6 +1289,12 @@ python3 scripts/audit_storage.py --to-minio # 把本该进 MinIO - **带完还能不能改**看字段自己的「只读」:配上来源默认锁死,勾上「带出后允许填写人修改」 才放开——环节权限、后端提交时的取值过滤(`formruntime.editable_keys`)认的都是这一条, 不另设第二套开关; +- **只读回显按类型念**:选人那一格念「姓名(账号)」(`utils/personLabel.ts`),部门那一格念部门名, + 也就是路径末段(`components/oa/mobile/useFormPlan.ts:deptText` 与桌面那格的下拉 label 同一个口径), + 不把整条组织路径摊给人看;星期几、多选月份、定位这三类桌面与手机共用 `utils/formRuntime` + 那三份读法(`weekText` / `monthsText` / `locationText`),手机上不会看到 `1-7` 与 `['2026-10']`, + 也不会因为落到兜底那句而**整格念成空的**;金额与数字两边都读 `formatNumber`(千分位 / 小数位 / + 货币按格子配置),金额没配单位也补「元」,明细里的金额列与合计同一个口径; - **存的是身份不是姓名**,所以申请人、审批人这两格能直接当「按表单字段找人」的来源用, 也能进条件分支;只读回显顺手补了一处:选人字段那一格存的是一串登录账号,详情页、打印页 统一念成「姓名(账号)」(`utils/personLabel.ts`); @@ -1506,7 +1521,7 @@ python3 scripts/audit_storage.py --to-minio # 把本该进 MinIO | 门户中心 | `portal:home` `portal:document` `portal:meeting` `portal:schedule` `portal:file` `portal:manage` | | 流程设计 | `design:process` `design:form` `design:category` `design:quota` `design:datasource` `design:integration` `design:openapi` | | 组织架构 | `org:unit` `org:person` `org:role` `org:authrole` | -| 监控与系统 | `monitor:work` `statistics:view` `log:view` `system:setting` `system:notify` | +| 监控与系统 | `monitor:work` `monitor:export` `statistics:view` `log:view` `system:setting` `system:notify` | `/auth/me` 与登录响应一并返回 `permissions` / `data_scope` / `roles`。前端拿它决定侧栏渲染哪些 菜单、路由是否放行(受控路由都带 `meta.permission`,无权限时按「首页 → 工作台 → 待办 → @@ -1590,7 +1605,10 @@ python3 scripts/audit_storage.py --to-minio # 把本该进 MinIO `source='local'` 的账号与 `role='admin'` 的超管不参与同步。人员清单被 `member_limit` 截断时只写不撤,Hub 返回空清单时整趟放弃,避免误伤一片账号。 这一趟跑成过就不再跑,失败了按 `OA_HUB_SYNC_RETRY_MINUTES` 补试,每次执行都记在 - `oa_hub_sync_run`。 + `oa_hub_sync_run`。**记录要能核对**:改名、僵尸账号让位、按编码认回部门这三类动作各自成列 + (`renamed` / `reclaimed` / `units_rebound`),名单级明细存 `details`(每类前 20 条 + 完整总数 + + 按条原文的提示,`message` 那 2000 字裁掉后半句也不丢信息),只改了名的一趟不算「无变更」。 + 验收见 `backend/scripts/check_hub_sync_details.py`。 - **几十秒内跟改**:`GET /api/v1/auth/directory/changes` 按游标轮询变更流水 (`OA_HUB_SYNC_CHANGES_*`,默认每 45 秒),人与部门的小改动不必等排期全量。游标只在 一批真的落干净(`has_more=false`)之后才往前推;流水被裁剪、本地落后过多,或收到只带 @@ -1612,6 +1630,22 @@ python3 scripts/audit_storage.py --to-minio # 把本该进 MinIO 因此不会被失败补试重新捞起来跑;「已终止」只说这一趟没跑完,已经写进库的人员与部门不回滚, 下一趟照常从 Hub 全量重对齐。返回里 `stopping=true` 说明终止时确实有一趟在跑、马上会停手。 验收见 `backend/scripts/check_hub_sync_cancel.py`。 +- **"明明没同步,却提示「已有同步任务正在执行,请稍后再试」"**:这句话只可能由本进程那把 + `threading.Lock` 抛出来(跨副本 Redis 那把挡下来的是另一句「另一个副本正在跑同步」),而页头按钮的 + `busy` 只是页面加载时读到的一次 `running` 快照、不轮询,所以后台那趟增量同步(默认每 45 秒,与手动 + 同步共用同一把锁)撞上时,界面上看着什么都没跑、点下去却被挡回来 —— 等几秒再点是正常的。不正常的是 + **漏锁**:`sync_users` / `_pull_changes` 先拿锁、再写那条「进行中」的记录,这一段原先在收尾那个 + `try` 之外,库断了或表结构落后(`Unknown column 'oa_hub_sync_run.renamed'`)就让异常从这段漏出去, + 本进程那把锁从此永久握着:跨副本那把最多一小时自己过期,这把只能等重启,于是每一次同步(连调度线程 + 每几十秒那趟增量一起)都只剩这一句提示,而同步历史里连一条记录都不会有。现在这一段自己负责交还锁, + 失败就当场如实报库的错误,不会再伪装成"有任务在跑"。 + 验收见 `backend/scripts/check_hub_sync_lock_leak.py`。 +- **换过主键的部门能一键收尾**:Hub 挪了 `organization_id` 之后,本地靠「编码 + 名称」认回原部门, + 旧的那一具就脱成停用的空壳子(同名同码、身份已被在职部门接走,同步既不再认它也不会合并)。 + `GET /api/v1/org/units/shells` 列出这些壳子并逐条说明删不掉的原因(挂着人 / 有下级 / + 被权限角色当数据范围),`POST /api/v1/org/units/shells/cleanup` 只删三样都干净的那几具, + 删除前逐条重算判据,不认前端传来的旧名单;体检对话框上直接给按钮。 + 验收见 `backend/scripts/check_hub_sync_shell_units.py`。 ### 同步定时任务 @@ -1927,16 +1961,24 @@ sqlite 上(55 项:谁按得动、窗口怎么算、留痕与通知、终止 | 单据有动静就通知外部系统一声 | 事件订阅 `oa_open_webhook`(七个事件,HMAC 签名,默认不带表单数据) | 「开放平台」页 | | 外部系统主动查/发起/代办 | 开放接口 `/api/v1/open/*`(应用令牌 + 五个作用域 + 限流与调用留痕) | 「开放平台」页建应用 | | 同一条待办提醒送到邮箱 / 钉钉飞书企微群 | 消息渠道 `oa_notify_channel`(六个事件各渠道订阅) | 「消息通知」页 | +| 待办推到个人手机上,点开就是那条待办 | `hub_wecom` 渠道:交给统一身份 Hub 代发企业微信应用消息(本系统不持有企微密钥,卡片点开回到现成的免登回调) | 「消息通知」页,见 `docs/hub-integration.md` §15 | -三条外发路共用同一套投递底线:**与业务动作同一事务入队 → 后台线程退避重发 → 重试用满进死信 → -停在"发送中"当结果未知、绝不盲发第二遍**。订阅方挂了不该让审批人办不成单, -所以入队这一步永远不把异常抛回业务代码。设计文档: +三条外发路共用同一套投递底线:**与业务动作同一事务入队 → 提交那一刻把后台投递线程当场叫醒 → +退避重发 → 重试用满进死信 → 停在"发送中"当结果未知、绝不盲发第二遍**。叫醒那一步原先只有写回 +发件箱有(`service/outbox.py`),消息渠道与事件订阅只能干等下一个轮询周期——量过:一条企业微信推送 +从入队到发出等了 28~60 秒,而真发那一次只用 1 秒,**慢的不是发送,是没人叫醒**。现在三条路共用 +`service/wake.py` 这一个通路(本进程直接置事件,跨副本发一条 Redis 广播),15/60 秒那一档轮询退回 +"叫不醒也要发出去"的兜底;一轮投递另有 20 秒的时间预算,一个慢 SMTP 网关拖不住整队消息, +没发完的下一轮接着发。验收:`scripts/check_notify_wake.py`。 +订阅方挂了不该让审批人办不成单,所以入队这一步永远不把异常抛回业务代码。设计文档: [docs/platform-open-api-design.md](docs/platform-open-api-design.md)、 [docs/notification-channels-design.md](docs/notification-channels-design.md)。 两个容易踩的分寸写在文档里,这里点名: -**收件人不做配置项**(站内信发给谁、这一路就发给谁,账号没邮箱就在投递记录里落一条 `skipped` -并说清去哪补,不静默丢);**群机器人一批发一条**(三个人会签不会往群里甩三条一模一样的消息)。 +**收件人不做配置项**(站内信发给谁、这一路就发给谁,账号没邮箱、没绑企业微信就在投递记录里 +落一条 `skipped` 并说清去哪补,不静默丢);**群机器人一批发一条**(三个人会签不会往群里甩三条 +一模一样的消息),**但推到人手机上的 `hub_wecom` 反过来是一人一条**——卡片点开是"我那条待办", +而且谁没绑企微、谁不在可见范围,得有一行记录留得下那个原因。 ### 装到手机桌面上(PWA) @@ -1952,7 +1994,8 @@ sqlite 上(55 项:谁按得动、窗口怎么算、留痕与通知、终止 从企微卡片点进来的多半是待办详情,那一页在 <768 的屏上换一套版式:抬头先答完四问 (这一单是什么、谁提的、多少钱、卡在哪一步几号到期),本环节要填的格子提到最前, 四十几格按类型归置——空值不渲染、系统取数折成一行、明细收成「12 条 · 合计」, -底下只吸三颗:`同意` / `退回` / `···`,办完直接跳下一条。弹层一律从屏幕下沿推上来, +底下只吸三颗:`同意` / `退回` / `···`,办完关掉这一张回待办列表——列表重新挂载就重新取一次,剩下的几条摆在眼前。 +弹层一律从屏幕下沿推上来, 每条出口上写着它去哪儿。**判据只有宽度,而且只作用于版式**:审批逻辑仍是桌面那一份 (`TaskDetailView` provide 出去,`components/oa/mobile/` 只负责摆),后端零改动。 手机上打开系统第一眼就是这一屏:`utils/returnPath.ts` 的 `landingPath()` 按设备挑表、再按权限挑那条真进得去的 @@ -2005,7 +2048,14 @@ sqlite 上(55 项:谁按得动、窗口怎么算、留痕与通知、终止 没勾这一档的表单走的还是上面那套按字段类型的自动归置,一个字没变;勾了之后环节字段权限、 整单「默认隐藏」、本环节要填的那几格三道闸照旧,末尾「完整单据」按配置给不给——不给的话 那条路收进顶栏的 `···`,要的是"只有一节",不是"这一单在手机上看不全"。 -取舍、口径与验收见 [docs/mobile-form-layout-config.md](docs/mobile-form-layout-config.md)。 +这一档又收掉两处手机上的废话:**节名没配、整屏又只有这一节的时候不摆那一行标题**(从前那行写的是 +代码补的「表单内容」,可上面那排页签已经写着这三个字,等于同一句话占两行,还搭上「11 项」和一颗 +没用的折叠箭头;现在 `planForm` 给每一节标 `generic`,摘要与「完整单据」两屏同一个口径, +好几节的时候节名照摆——那时候它是把正文分开的记号)、 +**部门那一格只念部门名**(库里存的是组织路径 `紫光汇智\软件开发事业部`,从前这一格和选人格子共用 +读法,路径被当人员引用问了一遍姓名接口,回来拼成「路径(路径)」摊三行;现在 `deptText` 取路径末段, +与桌面只读态取的部门下拉 label 是同一个名字)。取舍、口径与验收见 +[docs/mobile-form-layout-config.md](docs/mobile-form-layout-config.md)。 另一处顺手修的:没配核验闸门的单子不再摆「外部核验」那块面板(后端一直发着 `configured`, 是前端没认;真送过一次审的单子仍然照摆)。 @@ -2157,6 +2207,7 @@ sqlite 上(55 项:谁按得动、窗口怎么算、留痕与通知、终止 | 设计 | `GET\|POST\|PUT\|DELETE /process/categories` `/process/forms` `/process/processes`;`PUT /process/processes/{id}/design`;`POST .../validate` `.../publish` `.../disable` `.../copy`;`GET .../title/variables`(标题规则的变量清单);`POST /process/form-title/variables` + `POST /process/form-title/preview`(规则配在表单字段上时的同一份清单与预览,带画布上未保存的字段草稿);`POST /process/form-serial/preview`(编号预览,只读不占号) | | 运行 | `POST /job`(发起)`POST /job/serial/reserve`(编号时机配成 `create` 的新单先占号,回 `{serial, ticket, expiresIn}`,凭条在提交/存草稿时原样交回)`POST /job/title/preview`(发起页标题实时预览)`POST /job/{job}/title/preview`(办理页:按将要提交的那份改动算一句「提交后会变成什么」,只读不写库)`GET /job/{job}` `GET /work/{id}` `GET /work/related` `GET /work/summaries` `GET /task/processing`(每行带 `deletable`:本人创建、还停在开始环节、没压在别人手上)`/task/completed` `POST /task/{id}/execute` `POST /task/batch-execute` `/goback` `/addtask` `/transfer` `/press` `POST /job/{job}/terminate` | | 导出 | `GET /export/works?scope=created\|admin` `GET /export/tasks?scope=processing\|completed`(CSV,带 UTF-8 BOM) | +| 流程明细导出 | `GET /export/detail/catalog` `POST /export/detail/{count,preview,download}`(独立权限码 `monitor:export`,侧栏一条独立菜单;自选流程与字段,默认按流程分 sheet,也能合并成一张表,CSV 只走合并) | | 支撑 | `/attachment` `/attachment/{id}/download` `/draft` `/notification` `/read` `/worklog` `/statistics/*` `/settings` `/system/storage` `/system/storage/test` `/system/storage/reload` `/operation-logs` | | 门户 | `GET /portal/home`;`/cms/channels` `/cms/documents`(含封面上传);`/meetings` `/meetings/coming` `/meetings/invited` `/meetings/{id}/answer`;`/schedules` `/schedules/month` `/schedules/day`;`/files` `/files/{id}/download` | | 网盘 | `GET\|POST /files`;`PUT\|DELETE /files/{id}`;`GET /files/{id}/download`(`scope=mine\|shared\|mine_only`,固定落本地磁盘) | @@ -2215,7 +2266,12 @@ sqlite 上(55 项:谁按得动、窗口怎么算、留痕与通知、终止 - 统一身份:`api/hub.ts`(状态含 `sso` / `changes` 两段、一键同步、拉取变更、体检、自检)、 `components/oa/HubSyncButton.vue`(人员管理页头:「立即同步」+「同步前体检」+「拉取变更」, 带同步结果与历史,启用统一身份且有 `system:setting` 时旁边还有跳「同步定时任务」的入口; - 有同步卡在「进行中」时再多一颗「终止」)、 + 有同步卡在「进行中」时再多一颗「终止」;体检对话框把会动到什么摆成数字格子——真停用多少人/部门、 + 熔断线算到几个、几个登录名改名、几个僵尸账号让位、几个重名壳子部门,并点名是哪几个)、 + `views/oa/SyncScheduleView.vue`(「同步定时任务」页:排期、增量轮询、执行记录,外加**同步落库口径** + 这一段——同步部门、带上已停用的组织、按编码认领本地部门、离职停用与它的熔断百分比、账号让位、 + 版本没变就跳过、保护本地管理员、单次人数上限、建号补全域名、统一身份管理员账号; + 改完按每一项所属的组分别保存,保存即生效), `components/oa/HubStatusCard.vue`(接入状态卡:模式、同步时间、 凭证来源、免登通道、增量游标、上次结果、测试连接)、 `components/oa/HubKillSwitchCard.vue`(系统设置页的「统一身份应急总闸」开关:就是配置项 @@ -2269,6 +2325,7 @@ python3 scripts/check_hidden_field_rules.py # 本环节把这一格藏起来时 python3 scripts/check_writeback_revisit.py # 环节写回重发:提交时/到达时/审批通过后各发一次,退回改值再提交与撤回后重办能否再发(影子模式,跑完自己删干净) python3 scripts/check_writeback_trigger.py # 「什么时候发」拆两处:终态可多勾 / 一条都不勾是合法态 / 旧写法一键搬进环节(跑完自己删干净) python3 scripts/check_outbox_wake.py # 写回什么时候真的发出去:入队提交当场叫醒 / 回滚不空叫 / 一轮发干净一张单(影子模式,跑完自己删干净) +python3 scripts/check_notify_wake.py # 渠道提醒与订阅事件什么时候真的发出去:入队提交当场叫醒 / 回滚与没排上不空叫 / 人工重发也叫醒(连开发库,跑完自己删干净) python3 scripts/check_writeback_config.py # 写回配置全库体检:先报现库哪几条会静默不发/多发,再把八种病各造一遍自证(--report 只报不当闸门) python3 scripts/check_terminate_control.py # 终止管不管得住:谁能按、四档窗口、留痕与通知、终止那一刻的写回与冲销(内存 sqlite,不碰生产库) @@ -2310,13 +2367,17 @@ python3 scripts/check_flush_defer.py # 动过引擎里 db.flush 的作用 python3 scripts/check_simulate_paths.py # 动过审批人解析 / 环节路由 / 试算 python3 scripts/check_log_timeline.py # 动过流转日志留痕 python3 scripts/check_completed_dedup.py # 动过「我的已办」按单折叠(app/service/completed.py 与四处计数):全程在未提交事务里跑,库里不留行 +python3 scripts/check_detail_export.py # 动过流程明细导出(app/service/detail_export.py 与 app/api/export.py 的 /export/detail/*):未操作者五类口径各造一条真行验命中与不命中,分表与合并两种表头、七项筛选、两条上限一起对;自己建流程与单据,跑完删干净 python3 scripts/check_delete_unstarted.py # 动过「删除还没发起的单」(engine.delete_unstarted / deletable_task_ids / POST /job/{job}/delete,含删单那一刻给第三方那一句通知):建自己的流程与单据,跑完删干净 python3 scripts/check_begin_resubmit_todo.py # 动过开始环节提交(engine.start_from_begin:界面那颗「提交」、第三方 auto 回写、发起人确认第三方备好的表态三条路共用):退回到发起人再提交之后,这张单在「我的待办」里只许留一条,且这一步照常进已办与审批记录(建自己的流程与单据,跑完删干净) python3 scripts/check_intervention_title.py # 动过干预「修正表单」与标题的联动(engine.fix_data / _refresh_title / titles.sync_pending_titles / titles.preview_refresh):人填、自动重算、不重算三种口径各跑一张真单子,改完待办 / 待阅 / 监控三张列表一起对得上,保存前的预告也一并校(自己建流程自己删) python3 scripts/check_serial_timing.py # 动过编号时机(numbering.timing_* / engine.issue_serial / drafts.reserve_serial):五档时机各跑一张真单子(create 那一档连凭条三道闸一起跑),自己建流程自己删 python3 scripts/check_leader_lease.py # 动过跨进程租约(app/service/leader.py)/ 准备开 OA_WORKERS 多进程 python3 scripts/check_outbox_wake.py # 动过写回投递时机(service/outbox.py 的 wake / run_due / refresh_pending,或 main.py 调度线程的睡眠与叫醒) +python3 scripts/check_notify_wake.py # 动过外发任务的叫醒通路(service/wake.py,或 channels.enqueue_for / events.emit / channels.resend 里的 mark,或 main.py 调度线程的睡眠与叫醒) python3 scripts/check_hub_breaker.py # 动过 Hub 传输层与熔断(app/service/hub.py)——不连库、不碰真 Hub +python3 scripts/check_hub_sync_details.py # 动过同步记录的落库与回显(hub_sync.run_details / _finish / serialize_run)或三条熔断底线(dbconfig + hubconfig) +python3 scripts/check_hub_sync_shell_units.py # 动过空壳部门判据与一键清理(hub_sync.find_shell_units / api/org.py 的 /units/shells*) python3 scripts/check_job_payload.py # 动过单据详情的拼装(runtime._job_response / definition.build) python3 scripts/check_design_cache.py # 动过详情页什么时候问设计缓存(runtime._job_response 与 definition.design_cache_enabled) python3 scripts/check_org_tree_managers.py # 动过部门树/部门列表补负责人姓名(api/org.py::_managers_by_id) diff --git a/backend/app/api/export.py b/backend/app/api/export.py index e0323ca..85bd537 100644 --- a/backend/app/api/export.py +++ b/backend/app/api/export.py @@ -1,4 +1,11 @@ -"""列表导出:把「当前筛选条件」下的数据导成 CSV。 +"""列表导出:把「当前筛选条件」下的数据导成 CSV,外加**流程明细导出**那一整页。 + +两半共用同一套底层:值怎么渲染看 :mod:`app.service.exportfmt`,数据范围与筛选条件走 +:mod:`app.api.runtime` 里流程监控那一份查询。所以界面上看不到的单子一定导不出来, +不会出现「列表里没有、导出却有」的越权。 + +后半段(``/export/detail/*``)挂的是独立权限码 ``monitor:export``,界面是侧栏里 +「流程明细导出」那条独立菜单,设计稿见 ``docs/process-detail-export-design.md``。 只做读路径,不碰流转。查询条件与列表接口逐字复用同一套函数 (``_created_query`` / ``_task_filter`` / ``_admin_work_page`` / ``_admin_task_stmt``), @@ -19,30 +26,36 @@ import io from datetime import datetime from urllib.parse import quote -from fastapi import APIRouter, Depends, Query, Response +from fastapi import APIRouter, Depends, Query, Request, Response from sqlalchemy import select from sqlalchemy.orm import Session -from .. import models +from .. import models, schemas from ..db import get_db -from ..deps import CurrentUser, current_user -from ..envelope import forbidden +from ..deps import CurrentUser, current_user, require_permission +from ..envelope import bad_request, forbidden, ok from ..service import completed as completed_service +from ..service import detail_export from ..service import dicts as dicts_service -from ..service import formruntime -from .runtime import _admin_task_stmt, _admin_work_page, _created_query, _task_conditions, _task_filter +from ..service.exportfmt import ( # noqa: F401 - 值渲染搬进了 service/exportfmt.py,老名字照旧可用 + WORK_STATUS_LABELS, + cell_text, + relation_names as _job_names, + duration_text as _duration_text, + dt as _dt, + form_export_fields, + relation_ids as _relation_ids, + scalar_text as _scalar_text, + status_label as _status_label, + table_text as _table_text, +) +from .runtime import ( # noqa: PLC2701 - 共用条件与留痕,明细导出走的就是监控那一份查询 + _admin_task_stmt, _admin_work_page, _created_query, _log_operation, + _task_conditions, _task_filter, +) router = APIRouter(tags=["export"]) -#: 工作状态下拉框里的取值 -> 中文标签,与前端 utils/oa.ts 的口径一致。 -WORK_STATUS_LABELS = { - "running": "在途", - "completed": "办结", - "terminated": "终止", - "canceled": "作废", - "pending": "待处理", -} - #: 一次导出的行数上限。列表接口每页最多 200,导出是给整月报表用的, #: 但不能没有上限:一张宽表单导出几万行会把浏览器和数据库连接一起拖垮。 EXPORT_LIMIT = 5000 @@ -54,156 +67,11 @@ TASK_COLUMNS = ("单号", "标题", "流程", "分类", "环节", "处理人", " "到达时间", "完成时间", "处理动作", "处理意见", "是否超期") -# --------------------------------------------------------------------------- -# 值 -> 单元格文本 -# --------------------------------------------------------------------------- - - -def _dt(value: datetime | None) -> str: - return "" if value is None else value.replace(microsecond=0).isoformat(sep=" ") - - -def _status_label(value: object, paused: bool = False) -> str: - key = str(value or "") - label = WORK_STATUS_LABELS.get(key, key) - # 挂起不改流程状态,导出的 CSV 里就得靠这一眼看出来:筛完「只看挂起」导出去, - # 状态列如果还只写「运行中」,这张表等于把干预动作全抹掉了。 - return f"{label}(已挂起)" if paused and key == "running" else label - - -def _duration_text(seconds: object) -> str: - try: - total = int(seconds or 0) # type: ignore[arg-type] - except (TypeError, ValueError): - return "" - if total <= 0: - return "" - days, rest = divmod(total, 86400) - hours, rest = divmod(rest, 3600) - minutes = rest // 60 - parts = [] - if days: - parts.append(f"{days}天") - if hours: - parts.append(f"{hours}小时") - if minutes or not parts: - parts.append(f"{minutes}分") - return "".join(parts) - - -def _scalar_text(value: object) -> str: - if value is None: - return "" - if isinstance(value, bool): - return "是" if value else "否" - if isinstance(value, (list, tuple, set)): - return "、".join(str(item) for item in value if str(item or "").strip() != "") - if isinstance(value, dict): - return ";".join(f"{key}={_scalar_text(item)}" for key, item in value.items()) - return str(value) - - -def cell_text( - field: dict, value: object, cache: dicts_service.DictCache, jobs: dict[str, str] | None = None -) -> str: - """单个表单字段落地成什么文本:选项翻标签,明细表压一行,附件只留文件名。""" - kind = str(field.get("type") or "") - if value is None or (isinstance(value, str) and not value.strip()): - return "" - if kind == "signature": - # 签名是几十 KB 的 base64,导进表格既打不开也没意义,只留"签没签"这个事实。 - return "已签名" if str(value).strip() else "" - if kind in ("relation", "picker"): - if dicts_service.source_kind_of(field) != dicts_service.SOURCE_PROCESS: - # 这一格关联的是字典项或外部数据源的编码,不是单据 job: - # 拿单据名册去翻只会原样吐回一串看不懂的主键,按候选来源翻才念得人话。 - return dicts_service.option_labels(field, value, cache) - names = jobs or {} - labels = [names.get(str(item), str(item)) for item in _relation_ids(value)] - return "、".join(label for label in labels if label) - if kind == "table": - return _table_text(field, value, cache, jobs) - if kind in ("select", "radio", "checkbox"): - return dicts_service.option_labels(field, value, cache) - if kind == formruntime.CASCADER_TYPE: - # 级联的值是一条自上而下的路径,用斜杠分开才看得出是"华东 / 上海"而不是两个并列选项。 - return dicts_service.option_labels(field, value, cache, sep=" / ") - if kind == "switch": - return "是" if value in (True, "true", 1, "1") else "否" - if kind in ("attachment", "image"): - names = [str(item.get("name") or "") for item in formruntime.rows_of(value)] - return "、".join(name for name in names if name) or _scalar_text(value) - if kind in ("daterange", "timerange"): - # 区间那两项念成"起 ~ 止",直接转字符串会把中括号和引号一起灌进单元格 - text = formruntime.range_text(value) - if text: - return text - if kind == "week": - return formruntime.week_text(value) - if kind == "months": - # 多选月份存的是 YYYY-MM 数组,念成"2026年10-11月"才像一句人话 - return formruntime.months_text(value) - if kind == formruntime.LOCATION_TYPE: - return formruntime.location_text(value) - if kind == "richtext": - # 存的是 Markdown 原文:去掉记号再进表格,否则一格里躺着的是 ## 和 - 而不是话 - return formruntime.markdown_text(value) - if kind == "money" and field.get("uppercase"): - upper = formruntime.chinese_upper(value) - return f"{_scalar_text(value)}({upper})" if upper else _scalar_text(value) - return _scalar_text(value) - - -def _relation_ids(value: object) -> list[str]: - """关联审批单的值收成 job 列表:单个字符串、对象数组、字符串数组都认。""" - if isinstance(value, str): - return [value] if value.strip() else [] - if isinstance(value, dict): - return [str(value.get("job") or "")] if value.get("job") else [] - if isinstance(value, (list, tuple)): - out: list[str] = [] - for item in value: - out.extend(_relation_ids(item)) - return out - return [] - - -def _table_text( - field: dict, value: object, cache: dicts_service.DictCache, jobs: dict[str, str] | None = None -) -> str: - """明细表压成一格:``姓名=张三;金额=500 | 姓名=李四;金额=800``。""" - columns = formruntime.columns_of(field) - lines: list[str] = [] - for row in formruntime.rows_of(value): - pieces: list[str] = [] - if columns: - for column in columns: - key = str(column.get("key") or "") - text = cell_text(column, row.get(key), cache, jobs) - if text: - pieces.append(f"{column.get('label') or key}={text}") - else: - pieces = [f"{key}={_scalar_text(item)}" for key, item in row.items()] - if pieces: - lines.append(";".join(pieces)) - return " | ".join(lines) - - # --------------------------------------------------------------------------- # 查询与列拼装 # --------------------------------------------------------------------------- -def form_export_fields(db: Session, form_id: str) -> list[dict]: - """这张表单要摊成列的字段:有字段名、且真的参与录入。""" - row = db.get(models.FormElement, form_id) if form_id else None - return [ - item - for item in formruntime.fields_of(row.content if row else {}) - if str(item.get("key") or "") and formruntime.fillable(item) - ] - - def _work_lines(rows: list, db: Session, cache: dicts_service.DictCache, with_form: bool): """返回 (表头, 数据行)。只有一张表单时才追加表单字段列。""" form_ids = {str(row.form or "") for row in rows if getattr(row, "form", "")} @@ -234,28 +102,6 @@ def _work_lines(rows: list, db: Session, cache: dicts_service.DictCache, with_fo return headers, lines -def _job_names(db: Session, rows: list, fields: list[dict]) -> dict[str, str]: - """把关联字段里出现的 job 一次性翻成「单号 标题」,避免逐行查库。""" - wanted: list[str] = [] - for row in rows: - data = dict(row.data or {}) - for field in fields: - # 只有「候选来自流程单据」的那几格存的是 job,别的来源不用去单据表里翻 - if str(field.get("type") or "") not in ("relation", "picker") \ - or dicts_service.source_kind_of(field) != dicts_service.SOURCE_PROCESS: - continue - for job in _relation_ids(data.get(str(field.get("key") or ""))): - if job not in wanted: - wanted.append(job) - if not wanted: - return {} - names: dict[str, str] = {} - for model in (models.Work, models.WorkCompleted): - for row in db.execute(select(model).where(model.job.in_(wanted))).scalars().all(): - names.setdefault(row.job, f"{row.serial or ''} {row.title}".strip()) - return {job: names.get(job, job) for job in wanted} - - def _task_lines(rows: list) -> list[list[str]]: lines: list[list[str]] = [] for row in rows: @@ -279,20 +125,25 @@ def _task_lines(rows: list) -> list[list[str]]: return lines +def _attachment(body: bytes, filename: str, media_type: str) -> Response: + return Response( + content=body, + media_type=media_type, + headers={ + # 中文文件名走 RFC 5987,另留一个 ASCII 兜底给老版 Excel 和 curl -O。 + "Content-Disposition": f"attachment; filename=\"export\"; filename*=UTF-8''{quote(filename)}", + "Cache-Control": "no-store", + }, + ) + + def _csv(headers: list[str], rows: list[list[str]], filename: str) -> Response: buffer = io.StringIO() writer = csv.writer(buffer) writer.writerow(headers) writer.writerows(rows) - return Response( - content=("\ufeff" + buffer.getvalue()).encode("utf-8"), - media_type="text/csv; charset=utf-8", - headers={ - # 中文文件名走 RFC 5987,另留一个 ASCII 兜底给老版 Excel 和 curl -O。 - "Content-Disposition": f"attachment; filename=\"export.csv\"; filename*=UTF-8''{quote(filename)}", - "Cache-Control": "no-store", - }, - ) + return _attachment(("\ufeff" + buffer.getvalue()).encode("utf-8"), filename, + "text/csv; charset=utf-8") # --------------------------------------------------------------------------- @@ -404,3 +255,121 @@ def export_tasks( stmt = _task_filter(models.Task, user, keyword, process, category, "", expired, start_date, end_date) rows = list(db.execute(stmt.order_by(models.Task.start_time.desc()).limit(EXPORT_LIMIT)).scalars().all()) return _csv(list(TASK_COLUMNS), _task_lines(rows), f"我的待办_{datetime.now():%Y%m%d_%H%M}.csv") + + +# --------------------------------------------------------------------------- +# 流程明细导出(独立菜单 / 独立权限码) +# --------------------------------------------------------------------------- + +#: 这一页的四条接口挂同一码;与 monitor:work 互不为前置,理由见设计稿 §2。 +DETAIL = require_permission("monitor:export") + + +def _detail_plan(body: schemas.ExportDetailBody, db: Session, user: CurrentUser): + """报文 → (筛选, 列定义),顺带把界面上不该出现的组合挡掉。""" + filters = detail_export.filters_from_body(body.filters.model_dump()) + detail_export.validate(filters, body.columns, body.layout, body.fmt) + specs = detail_export.build_columns( + db, filters.processes, body.columns, body.columns_only, body.activities) + if not specs: + raise bad_request("勾选的列在这些流程里都不存在,请重新选择") + limit = detail_export.max_columns() + if len(specs) > limit: + raise bad_request(f"这次要出 {len(specs)} 列,超过单张表上限 {limit} 列:请少勾几列或收起环节列") + return filters, specs + + +def _process_names(db: Session, process_ids: list[str]) -> dict[str, str]: + if not process_ids: + return {} + return { + str(row.id): str(row.name or "") + for row in db.execute( + select(models.Process).where(models.Process.id.in_(process_ids))).scalars().all() + } + + +@router.get("/export/detail/catalog") +def export_detail_catalog( + db: Session = Depends(get_db), user: CurrentUser = Depends(DETAIL) +) -> dict: + """可选流程清单 + 每条流程的字段目录 + 「相关核算项目」那一格在哪。""" + return ok(detail_export.catalog(db)) + + +@router.post("/export/detail/count") +def export_detail_count( + body: schemas.ExportDetailBody, + db: Session = Depends(get_db), + user: CurrentUser = Depends(DETAIL), +) -> dict: + """按当前筛选估行数(分流程报),导出前先知道这次有多大。""" + filters, _specs = _detail_plan(body, db, user) + counts = detail_export.counts_by_process(db, user, filters) + names = _process_names(db, filters.processes) + limit = detail_export.max_rows() + total = sum(counts.values()) + return ok({ + "total": total, + "limit": limit, + "exceeded": total > limit, + "byProcess": [ + {"process": process_id, "name": names.get(process_id, process_id), "count": counts.get(process_id, 0)} + for process_id in filters.processes + ], + }) + + +@router.post("/export/detail/preview") +def export_detail_preview( + body: schemas.ExportDetailBody, + db: Session = Depends(get_db), + user: CurrentUser = Depends(DETAIL), +) -> dict: + """按最终那份列取一页回来看看:字段勾完就地刷新,不用先导一个文件。""" + filters, specs = _detail_plan(body, db, user) + size = max(1, min(int(body.page_size or 20), 100)) + offset = max(0, (int(body.page or 1) - 1) * size) + rows, total = detail_export.query_page(db, user, filters, limit=size, offset=offset) + sheets = detail_export.build_sheets( + db, user, filters, specs, rows, layout=body.layout, summary=body.summary) + return ok({ + "total": total, + "page": body.page, + "pageSize": size, + "sheets": [{"name": sheet.name, "headers": sheet.headers, "lines": sheet.lines} for sheet in sheets], + }) + + +@router.post("/export/detail/download") +def export_detail_download( + body: schemas.ExportDetailBody, + db: Session = Depends(get_db), + user: CurrentUser = Depends(DETAIL), + request: Request = None, # type: ignore[assignment] +) -> Response: + """出文件:默认一条流程一个 sheet,也可以合并成一张表;CSV 只有合并那一种表头。""" + filters, specs = _detail_plan(body, db, user) + limit = detail_export.max_rows() + rows, total = detail_export.query_page(db, user, filters, limit=limit + 1) + if total > limit: + raise bad_request( + f"这次命中 {total} 行,超过单次上限 {limit} 行:请收窄日期或减少流程条数" + "(上限在「系统设置」里可调)") + sheets = detail_export.build_sheets( + db, user, filters, specs, rows, layout=body.layout, summary=body.summary) + names = _process_names(db, filters.processes) + filename = detail_export.file_name(body.fmt) + _log_operation( + db, user, "export_detail", "、".join(names.get(item, item) for item in filters.processes)[:255], + f"导出 {sum(len(sheet.lines) for sheet in sheets)} 行 / {len(body.columns)} 列 / " + f"{body.layout} / {body.fmt};筛选:状态={','.join(filters.statuses) or '全部'} " + f"创建={filters.create_start or '不限'}~{filters.create_end or '不限'} " + f"归档={filters.archive_start or '不限'}~{filters.archive_end or '不限'} " + f"未操作者={len(filters.unoperator.persons)} 人", + request, + ) + db.commit() + if body.fmt == detail_export.FORMAT_CSV: + return _attachment(detail_export.to_csv(sheets), filename, "text/csv; charset=utf-8") + return _attachment(detail_export.to_xlsx(sheets), filename, detail_export.XLSX_TYPE) diff --git a/backend/app/api/notify_channels.py b/backend/app/api/notify_channels.py index cefc457..b8afe53 100644 --- a/backend/app/api/notify_channels.py +++ b/backend/app/api/notify_channels.py @@ -16,12 +16,14 @@ from fastapi import APIRouter, Depends, Query, Request from sqlalchemy import func, select from sqlalchemy.orm import Session -from .. import models, schemas +from .. import hubconfig, models, schemas, serializers from ..db import get_db from ..deps import CurrentUser, client_ip, current_user, require_permission from ..envelope import bad_request, not_found, ok from .. import dbconfig +from ..query import count_of from ..service import channels +from ..service import hub as hub_api router = APIRouter(tags=["notify"]) @@ -34,8 +36,31 @@ KIND_LABELS = { models.NotifyChannel.KIND_FEISHU: "飞书群机器人", models.NotifyChannel.KIND_WECOM: "企业微信群机器人", models.NotifyChannel.KIND_WEBHOOK: "自定义 HTTP 回调", + models.NotifyChannel.KIND_HUB_WECOM: "企业微信(经统一身份 Hub 推送)", } +#: Hub 这一路的两种消息形态,界面上是个分段选择 +HUB_MSGTYPE_LABELS = { + channels.HUB_MSGTYPE_CARD: "卡片(可点开直达待办)", + channels.HUB_MSGTYPE_MARKDOWN: "纯文本提醒(不带链接)", +} + +#: 测试发送没有真实单据可指,深链指到待办列表:点开那一跳(Hub 认人 + redirect) +#: 才能一起验掉,否则只验到"消息发出去了"这一半 +HUB_TEST_PATH = "/todo" + + +def receiver_labels(pref: list[str] | tuple[str, ...]) -> str: + """把收件人标识的顺序翻成一句人话:``Hub 用户 ID → 登录账号``。""" + return " → ".join(channels.HUB_RECEIVER_LABELS.get(field, field) for field in pref) + + +def hub_no_receiver_hint(pref: tuple[str, ...]) -> str: + """测试发送时点按钮的人自己取不到收件标识:这话要对着"你的账号"说。""" + named = "、".join(channels.HUB_RECEIVER_LABELS.get(field, field) for field in pref) + return (f"你的账号在统一身份里对不上号:按这个渠道配的收件人标识({named})取不到值," + "这一路发不到你手机上。要么给自己补上,要么把渠道的收件人标识换成另一种。") + def _stamp(value: datetime | None) -> str: return value.strftime("%Y-%m-%d %H:%M:%S") if value else "" @@ -49,6 +74,8 @@ def _view(db: Session, row: models.NotifyChannel) -> dict: .where(models.NotifyDelivery.channel == row.code, models.NotifyDelivery.create_time >= since) .group_by(models.NotifyDelivery.status) ).all()) + is_hub = row.kind in models.NotifyChannel.HUB_KINDS + receiver_pref = channels.hub_receiver_pref(row.config or {}) return { "id": row.id, "code": row.code, @@ -58,6 +85,10 @@ def _view(db: Session, row: models.NotifyChannel) -> dict: "enabled": row.enabled, "events": list(row.events or []), "config": channels.scrub_config(row.config or {}), + # 这一路按哪一列认人(只有 Hub 渠道有意义):收件人标识现在是渠道上可配的一项, + # 列表里就得说清当前用的是哪种、按什么顺序退回,不然出问题时连"该看哪一列"都对不上 + "receiverPref": list(receiver_pref) if is_hub else [], + "receiverLabel": receiver_labels(receiver_pref) if is_hub else "", "textTemplate": row.text_template, "timeoutSeconds": row.timeout_seconds, "retries": row.retries, @@ -124,6 +155,32 @@ def _clean(body: schemas.NotifyChannelBody, *, kind: str) -> dict: config["port"] = int(config.get("port") or 465) if config["security"] not in ("ssl", "starttls", "none"): config["security"] = "ssl" + elif kind == models.NotifyChannel.KIND_HUB_WECOM: + # 这一路没有地址也没有密钥要填:站点和应用密钥都跟着「系统设置 → 统一身份」 + msgtype = str(config.get("msgtype") or channels.HUB_MSGTYPE_CARD).strip().lower() + if msgtype not in channels.HUB_MSGTYPES: + raise bad_request("消息形态只认 textcard(卡片)或 markdown(纯文本提醒)") + config["msgtype"] = msgtype + config["with_link"] = bool(config.get("with_link", True)) + try: + title_limit = int(config.get("title_limit") or channels.HUB_TITLE_DEFAULT) + except (TypeError, ValueError): + raise bad_request("标题字数上限要填个数字") + if not channels.HUB_TITLE_FLOOR <= title_limit <= 120: + raise bad_request(f"标题字数上限需要在 {channels.HUB_TITLE_FLOOR}-120 之间") + config["title_limit"] = title_limit + # 收件人标识:Hub 只认那两种(``user_id`` / ``account``),顺序就是认人的优先级。 + # 存成规范化后的列表,界面上提交 ""/"account"/["account","user_id"] 都收, + # 但库里只留一种写法,免得同一个配置有三种长相。 + receiver = channels.parse_hub_receiver_pref(config.get("receiver")) + if receiver is None: + raise bad_request("收件人标识只认 " + + " / ".join(f"{key}({channels.HUB_RECEIVER_LABELS[key]})" + for key in channels.HUB_RECEIVER_VALUES)) + config["receiver"] = list(receiver) + # 密钥不在渠道上,但别的渠道传来的 url/secret 也不该跟着种类切换还留在库里 + config = {key: value for key, value in config.items() + if key in ("msgtype", "with_link", "title_limit", "receiver")} else: url = str(config.get("url") or "").strip() if not url: @@ -133,6 +190,9 @@ def _clean(body: schemas.NotifyChannelBody, *, kind: str) -> dict: config["url"] = url config["secret"] = str(config.get("secret") or "").strip() or None config = {key: value for key, value in config.items() if value is not None} + # 只收这一档种类认得的键:界面上多传的东西(密钥回显的 xxxSet 之类)不进库 + owned = channels.owned_config_keys(kind) + config = {key: value for key, value in config.items() if not owned or key in owned} return values | {"config": config} @@ -147,9 +207,31 @@ def _log(db: Session, user: CurrentUser, action: str, target: str, detail: str, @router.get("/notify/meta") def notify_meta(_: CurrentUser = Depends(current_user)) -> dict: """界面上要摊开成勾选框的下拉清单:渠道类型、事件、模板占位符、SMTP 常用端口。""" + hub = hubconfig.get() return ok({ "kinds": [{"value": key, "label": label} for key, label in KIND_LABELS.items()], "events": [{"value": key, "label": label} for key, label in channels.EVENTS], + # Hub 代发这一路的"底"配在哪、还缺什么:配渠道的人最常撞的是密钥没领、 + # 以及 Hub 侧那两道推送开关没开,先在界面上看得见,别等投递记录里报错 + "hub": { + "ready": hub.notify_on, + "missing": hub.notify_missing, + "baseUrl": hub.hub_base_url, + "appCode": hub.hub_app_code, + "keySet": bool(hub.hub_integration_key.strip()), + "pushPath": hub.hub_path_notify_wecom, + "forcedOff": hub.forced_off, + "timeoutSeconds": hub.hub_timeout_seconds, + }, + "hubMsgtypes": [{"value": key, "label": label} for key, label in HUB_MSGTYPE_LABELS.items()], + # 收件人标识:Hub 只认这几种(渠道 config.receiver 的取值),界面照这张表摊开成 + # 优先级选项;``hubReceiverPresets`` 是常用的几种组合,每一档都带一句"什么时候用它" + "hubReceivers": [{"value": key, "label": label, "column": column} + for key, label, column in channels.HUB_RECEIVER_FIELDS + if key in channels.HUB_RECEIVER_VALUES], + "hubReceiverPresets": [{"value": list(pref), "label": label, "hint": hint} + for pref, label, hint in channels.HUB_RECEIVER_PRESETS], + "hubReceiverDefault": list(channels.HUB_RECEIVER_DEFAULT), "textVars": [{"value": "{" + name + "}", "label": label} for name, label in ( ("title", "消息标题"), ("body", "消息正文"), ("url", "单据链接"), ("person", "收件人姓名"), ("time", "发生时间"), ("type", "消息类型"), @@ -167,10 +249,14 @@ def list_channels(db: Session = Depends(get_db), _: CurrentUser = Depends(curren rows = list(db.execute( select(models.NotifyChannel).order_by(models.NotifyChannel.code) ).scalars().all()) + hub_rows = [row for row in rows if row.kind in models.NotifyChannel.HUB_KINDS] return ok({ "items": [_view(db, row) for row in rows], "enabled": any(row.enabled for row in rows), "masterSwitch": bool(dbconfig.value("notify_channels_enabled", True)), + # 换收件人标识之前得先看见代价:每一种各能覆盖多少在职账号、怎么配都发不到的是几个。 + # 只在真有 Hub 渠道时问这一条聚合,邮件/机器人那一档用不上 + "hubCoverage": channels.hub_receiver_coverage(db) if hub_rows else None, }) @@ -208,12 +294,17 @@ def update_channel( row = get_channel(db, code) if row is None: raise not_found("渠道不存在") - values = _clean(body, kind=str(body.kind or row.kind)) + kind = str(body.kind or row.kind) + values = _clean(body, kind=kind) # 密钥字段留空 = 不改:界面上永远看不到明文,也就不可能"看一眼再原样提交" incoming = dict(body.config or {}) merged = channels.merge_config(row.config or {}, incoming) merged.update(values.pop("config")) - values["config"] = merged + # 种类换过一档,库里那一档留下的参数就得清掉,不然旧的推送地址会一直躺在 + # 新渠道的配置里,看着像它还生效 + owned = channels.owned_config_keys(kind) + values["config"] = {key: value for key, value in merged.items() + if not owned or key in owned} for key, value in values.items(): setattr(row, key, value) _log(db, user, "notify_channel_update", code, f"修改消息渠道:{row.name}", request) @@ -251,19 +342,32 @@ def test_channel( problems = channels.problems(row) if problems: raise bad_request("还缺:" + ";".join(problems)) + hub_kind = row.kind in models.NotifyChannel.HUB_KINDS + if row.kind in models.NotifyChannel.SMTP_KINDS: + target = channels.email_of(row, user.person) + elif hub_kind: + receiver_pref = channels.hub_receiver_pref(row.config) + receiver, target = channels.hub_receiver(user.person, receiver_pref) + else: + target = str((row.config or {}).get("url") or "") delivery = models.NotifyDelivery( channel=row.code, kind=row.kind, type=list(row.events or ["task"])[0], identity=user.ref, person=user.person_id, person_name=user.display_name, - target=(channels.email_of(row, user.person) - if row.kind in models.NotifyChannel.SMTP_KINDS else str((row.config or {}).get("url") or "")), + target=target, + target_field=channels.hub_receiver_field(receiver) if hub_kind else "", title="[测试] 这是一条来自 OA 的测试消息", - body="看到这条说明渠道配置是对的。测试期间如果没收到,先确认这个人有没有邮箱。", + body="看到这条说明渠道配置是对的。测试期间如果没收到,先确认这个人有没有邮箱。" + if not hub_kind else "收到这条说明 OA → Hub → 企业微信这一段是通的。" + "点开应该落到本系统的待办列表;落在首页说明 Hub 上没登记首页地址(home_url)。", ) if not delivery.target: - raise bad_request("你的账号上没有邮箱,先到自己资料里补一个再测") + raise bad_request( + hub_no_receiver_hint(receiver_pref) if hub_kind + else "你的账号上没有邮箱,先到自己资料里补一个再测" + ) db.add(delivery) db.commit() - result = channels.deliver(db, delivery, channel=row) + result = channels.deliver(db, delivery, channel=row, hub_link=HUB_TEST_PATH if hub_kind else "") if result.status == models.NotifyDelivery.STATUS_SUCCESS: return ok({"status": result.status, "detail": result.response, "delivery": _delivery_view(result)}) raise bad_request(f"没发出去:{result.last_error}", reason="NOTIFY_TEST_FAILED") @@ -275,29 +379,47 @@ def list_deliveries( status_filter: str = Query("", alias="status"), type_filter: str = Query("", alias="type"), keyword: str = Query(""), - limit: int = Query(80, ge=1, le=LIST_LIMIT), + page: int = Query(1, ge=1), + page_size: int = Query(20, ge=1, le=LIST_LIMIT), db: Session = Depends(get_db), _: CurrentUser = Depends(require_permission("system:notify")), ) -> dict: - stmt = select(models.NotifyDelivery).order_by(models.NotifyDelivery.id.desc()).limit(limit) + """投递记录:按页翻,不再只给"最近 80 条"那一刀。 + + 跳过和失败的都是几百上千行堆在这儿,只截最近 80 条等于把"上周那批为什么没发出去" + 直接翻不到,所以这里和待办、操作日志一个口径:``page`` / ``page_size`` 分页, + 回 ``total`` / ``pages`` 给分页器。 + + ``counts`` 跟着渠道 / 消息类型 / 关键词走,但不跟着状态走——状态就是那排徽标本身, + 跟着走会让当前选中的那一档永远等于"全部"。``''`` 那一项是这些筛选下的总数, + 界面上「全部」那一格读它(以前它压根没值,永远显示 0)。 + """ + filters = [] if channel: - stmt = stmt.where(models.NotifyDelivery.channel == channel) - if status_filter: - stmt = stmt.where(models.NotifyDelivery.status == status_filter) + filters.append(models.NotifyDelivery.channel == channel) if type_filter: - stmt = stmt.where(models.NotifyDelivery.type == type_filter) + filters.append(models.NotifyDelivery.type == type_filter) if keyword: like = f"%{keyword}%" - stmt = stmt.where(models.NotifyDelivery.title.like(like) | models.NotifyDelivery.person_name.like(like)) - rows = list(db.execute(stmt).scalars().all()) + filters.append(models.NotifyDelivery.title.like(like) | models.NotifyDelivery.person_name.like(like)) + + stmt = select(models.NotifyDelivery).where(*filters) + if status_filter: + stmt = stmt.where(models.NotifyDelivery.status == status_filter) + total = count_of(db, stmt) + rows = list(db.execute( + stmt.order_by(models.NotifyDelivery.id.desc()).offset((page - 1) * page_size).limit(page_size) + ).scalars().all()) counts = dict(db.execute( - select(models.NotifyDelivery.status, func.count(models.NotifyDelivery.id)).group_by(models.NotifyDelivery.status) + select(models.NotifyDelivery.status, func.count(models.NotifyDelivery.id)) + .where(*filters) + .group_by(models.NotifyDelivery.status) ).all()) - return ok({ - "items": [_delivery_view(row) for row in rows], - "counts": {key: int(counts.get(key, 0)) for key in models.NotifyDelivery.STATUSES}, - "events": [{"value": key, "label": label} for key, label in channels.EVENTS], - }) + payload = serializers.page([_delivery_view(row) for row in rows], total, page, page_size) + payload["counts"] = {key: int(counts.get(key, 0)) for key in models.NotifyDelivery.STATUSES} + payload["counts"][""] = sum(payload["counts"].values()) + payload["events"] = [{"value": key, "label": label} for key, label in channels.EVENTS] + return ok(payload) def _delivery_view(row: models.NotifyDelivery) -> dict: @@ -311,6 +433,10 @@ def _delivery_view(row: models.NotifyDelivery) -> dict: "personName": row.person_name, # 机器人地址里有 access_token,记录里只回打码后的地址 "target": channels.mask_target(row.target) if "://" in (row.target or "") else row.target, + # 走 Hub 的那一路要看得清"这串是 Hub 主键还是登录账号"——10086 与 zhangsan + # 在收件人排查上是两回事:前者跟着同步走,后者会被企微字段改写 + "targetField": row.target_field, + "targetFieldLabel": channels.HUB_RECEIVER_LABELS.get(row.target_field, ""), "title": row.title, "body": row.body, "job": row.job, @@ -338,6 +464,32 @@ def resend_delivery( return ok(_delivery_view(row)) +@router.post("/notify/deliveries/{delivery_id}/recheck") +def recheck_delivery( + delivery_id: str, + db: Session = Depends(get_db), + _: CurrentUser = Depends(require_permission("system:notify")), +) -> dict: + """问 Hub 回查这一条的逐人投递结果(文档 9.6.7),按对方口径改写本地状态。 + + 只读、可反复点:回查不改 Hub 上任何东西,也就不存在"多点一次多发一条"。 + 超时之后不确定到底投没投出去、或者想看看某个人的失败原因变了没有,用它。 + """ + row = db.get(models.NotifyDelivery, delivery_id) + if row is None: + raise not_found("投递记录不存在") + try: + detail = channels.hub_recheck(db, row) + except ValueError as exc: + raise bad_request(str(exc)) + except hub_api.HubError as exc: + # 404 = 这条记录已经出了 Hub 的保留期(或压根没投出去过),话要说成这样 + raise bad_request(f"问不到 Hub 的投递明细:{exc.message}") + db.commit() + db.refresh(row) + return ok(_delivery_view(row) | {"detail": detail}) + + @router.post("/notify/deliveries/{delivery_id}/send-now") def send_delivery_now( delivery_id: str, diff --git a/backend/app/api/org.py b/backend/app/api/org.py index 2a94092..c42e63f 100644 --- a/backend/app/api/org.py +++ b/backend/app/api/org.py @@ -5,17 +5,17 @@ from __future__ import annotations from datetime import datetime from typing import Iterable -from fastapi import APIRouter, Depends, Query +from fastapi import APIRouter, Depends, Query, Request from sqlalchemy import delete, func, or_, select from sqlalchemy.orm import Session, selectinload from .. import models, permissions, schemas, serializers from ..db import get_db -from ..deps import CurrentUser, current_user, require_permission +from ..deps import CurrentUser, client_ip, current_user, require_permission from ..envelope import bad_request, not_found, ok from ..query import count_of from ..security import hash_password -from ..service import hub, hub_refs, org, personref +from ..service import hub, hub_refs, hub_sync, org, personref router = APIRouter(prefix="/org", tags=["organization"]) @@ -350,6 +350,112 @@ def delete_unit(unit_id: int, db: Session = Depends(get_db)) -> dict: return ok({"success": True}) +def _hub_units(db: Session) -> list[models.Unit]: + """所有绑过统一身份的部门。空壳检查只看这批:本地自建部门轮不到同步去处置。""" + return list(db.execute(select(models.Unit).where(models.Unit.hub_org_id.is_not(None))).scalars().all()) + + +def _shell_rows(db: Session) -> list[dict]: + """当前库里的空壳部门 + 每一具"删不掉的原因"。 + + 壳子通常只有个位数(Hub 每挪一次主键留一具),所以这里逐条查人数、下级和角色引用, + 不为了省几次查询把判据拆成三份互相抄不准的 SQL。 + """ + rows: list[dict] = [] + for unit in hub_sync.find_shell_units(_hub_units(db)): + rows.append( + { + "id": str(unit.id), + "name": unit.name, + "code": unit.code, + "hub_org_id": str(unit.hub_org_id), + "status": int(unit.status), + "blockers": hub_sync.shell_unit_blockers(db, unit), + } + ) + return rows + + +@router.get("/units/shells", dependencies=[Depends(require_permission("org:unit"))]) +def list_shell_units(db: Session = Depends(get_db)) -> dict: + """列出 Hub 换主键之后留下的空壳部门(停用的旧身子,身份已被同名同码的在职部门接走)。 + + 判据与「同步前体检」共用 :func:`hub_sync.find_shell_units`,界面上报几具就是几具; + ``blockers`` 非空的那几具删不掉,得先把人挪走、下级删掉或改角色的数据范围。 + """ + rows = _shell_rows(db) + return ok( + { + "total": len(rows), + "deletable": len([row for row in rows if not row["blockers"]]), + "items": rows, + } + ) + + +@router.post("/units/shells/cleanup", dependencies=[Depends(require_permission("org:unit"))]) +def cleanup_shell_units( + body: schemas.UnitShellCleanupBody, + request: Request, + db: Session = Depends(get_db), + user: CurrentUser = Depends(current_user), +) -> dict: + """一键清理空壳部门:把 Hub 换主键留下的死壳子删掉。 + + 为什么这些能删、别的不行:本地对同步部门只停用不删除,是因为 ``hub_org_id`` 一丢就 + 再也对不回 Hub 那个组织。壳子不一样——它的编码与名称已经被一个在职部门顶着,同步 + 认回的是那个在职部门,这一具永远不会再接上任何组织,留在树上只是重名干扰。 + + 删之前逐条重算判据(不认前端传来的旧名单):已经不再是壳子的跳过,还有人、有下级、 + 被权限角色当数据范围的也跳过并把原因报回去。``dry_run`` 一行都不动。 + """ + candidates = {str(unit.id): unit for unit in hub_sync.find_shell_units(_hub_units(db))} + wanted = [str(models.as_id(value) or "") for value in body.ids] if body.ids else list(candidates) + deleted: list[dict] = [] + skipped: list[dict] = [] + for unit_id in wanted: + unit = candidates.get(unit_id) + if unit is None: + skipped.append({"id": unit_id, "name": "", "blockers": ["已经不是空壳部门(已被删除或 Hub 重新认回了)"]}) + continue + blockers = hub_sync.shell_unit_blockers(db, unit) + if blockers: + skipped.append({"id": unit_id, "name": unit.name, "blockers": blockers}) + continue + snapshot = { + "id": unit_id, + "name": unit.name, + "code": unit.code, + "hub_org_id": str(unit.hub_org_id), + } + if not body.dry_run: + db.delete(unit) + db.flush() + deleted.append(snapshot) + if deleted and not body.dry_run: + db.add( + models.OperationLog( + action="org_unit_shell_cleanup", + target=f"units:{len(deleted)}", + detail=";".join( + f"{row['name']}(编码 {row['code']},原 Hub 组织 {row['hub_org_id']})" for row in deleted + )[:2000], + person=str(user.person.id), + person_name=user.display_name, + identity=user.ref, + ip=client_ip(request), + ) + ) + db.commit() + return ok( + {"dry_run": bool(body.dry_run), "deleted": deleted, "skipped": skipped}, + ( + (f"预演:将删除 {len(deleted)} 个空壳部门" if body.dry_run else f"已删除 {len(deleted)} 个空壳部门") + + (f",{len(skipped)} 个删不掉" if skipped else "") + ), + ) + + @router.post("/units/{unit_id}/hub-binding", dependencies=[Depends(require_permission("org:unit"))]) def bind_unit_hub(unit_id: int, body: schemas.UnitHubBindBody, db: Session = Depends(get_db)) -> dict: """把本地自建部门手工认成 Hub 的某个组织。 diff --git a/backend/app/api/runtime.py b/backend/app/api/runtime.py index 15a7e29..efbaf46 100644 --- a/backend/app/api/runtime.py +++ b/backend/app/api/runtime.py @@ -2267,12 +2267,29 @@ def _work_search_clause(model, like: str): def _monitor_work_part( - user, values, table: str, model, keyword, process, statuses, start_date, end_date, expired, paused: str = "" + user, values, table: str, model, keyword, process, statuses, start_date, end_date, expired, paused: str = "", + *, processes: list[str] | None = None, creator_refs: list[str] | None = None, + archive_start: datetime | None = None, archive_end: datetime | None = None, extra=None, ): """一张流程表在监控列表上的取数,只取「主键 + 排序时间 + 来源表」三列。 只 SELECT 三列是有意为之:监控范围最大的能盖住全公司,归档表攒上一年就是几十万行, 连 ``data`` 那坨表单 JSON 一起拉进 Python 再切片,等于每翻一页搬一次全表。 + + 最后那几个关键字参数是给**流程明细导出**开的一档(``service/detail_export.py``), + 默认值下行为与原来一字不差。开在这儿、而不是让导出另写一份查询,理由与 + :func:`_created_clause` 摆出来给两个消费者共用是同一条:同一套条件写两遍迟早漂开, + 漂开的结果是监控页上看得见的单导不出来。 + + - ``processes``:流程多选; + - ``creator_refs``:创建人账号白名单;空列表是谁都不命中,与 :func:`permissions.scoped` + 对空清单的处理同口径; + - ``archive_start`` / ``archive_end``:归档日期。本平台办结 / 终止 / 作废那一刻整行搬进 + 归档表(``engine._finish_work``),所以归档日期说的就是归档表的 ``finish_time``。在途表 + 上这一列压根没写值,按列去比只会得到一片 ``NULL`` 假空集,报错方向还指着日期格式; + 直接把「在途单没有归档日期可筛」写进 SQL,与下面 ``paused`` 处理缺列那一句同构; + - ``extra``:调用方算好的附加条件,条件对象或 ``model -> 条件`` 的可调用者。待办 / 待阅 + 那类要按 ``job`` 关联到本行的 ``EXISTS``,两张表得各关联一遍,所以留了可调用者这一档。 """ stmt = select( model.id.label("work_id"), @@ -2310,6 +2327,20 @@ def _monitor_work_part( stmt = stmt.where(literal(False)) else: stmt = stmt.where(model.paused.is_(paused_flag)) + if processes: + stmt = stmt.where(model.process.in_(processes)) + if creator_refs is not None: + stmt = stmt.where(model.creator_identity.in_(creator_refs or ["__none__"])) + if archive_start or archive_end: + if table == "running": + stmt = stmt.where(literal(False)) + else: + if archive_start: + stmt = stmt.where(model.finish_time >= archive_start) + if archive_end: + stmt = stmt.where(model.finish_time < archive_end) + if extra is not None: + stmt = stmt.where(extra(model) if callable(extra) else extra) return stmt @@ -2345,16 +2376,24 @@ def _admin_work_page( offset: int = 0, limit: int = 20, with_data: bool = True, + processes: list[str] | None = None, + creator_refs: list[str] | None = None, + archive_start: datetime | None = None, + archive_end: datetime | None = None, + extra=None, ) -> tuple[list, int]: """监控范围内所有流程的一页数据 + 总条数(在途与归档并起来按发起时间倒序)。 ``with_data=False`` 只给列表行,不回表单正文;导出走的是默认值,照旧是完整行。 + 最后那五个参数是给流程明细导出开的一档,口径见 :func:`_monitor_work_part`。 """ values = permissions.scope_person_refs(db, user) statuses = _status_filter(status) parts = [ _monitor_work_part( - user, values, table, model, keyword, process, statuses, start_date, end_date, expired, paused + user, values, table, model, keyword, process, statuses, start_date, end_date, expired, paused, + processes=processes, creator_refs=creator_refs, + archive_start=archive_start, archive_end=archive_end, extra=extra, ) for table, model in _MONITOR_WORK_TABLES ] diff --git a/backend/app/dbconfig.py b/backend/app/dbconfig.py index 1414d84..82c4a4a 100644 --- a/backend/app/dbconfig.py +++ b/backend/app/dbconfig.py @@ -158,6 +158,9 @@ GROUPS: tuple[Group, ...] = ( Group("outbound", "对外发送", "审批结果往外送时用到的总闸:消息渠道(邮件 / 群机器人)、" "开放平台事件推送、调用留痕保留多久。开关在这里,具体发到哪个邮箱、" "推给哪个地址,在「消息通知」和「开放平台」两个页面里配。", 55), + Group("export", "流程明细导出", "「流程明细导出」那一页一次能导多大一份表。上限是给" + "「整月整年台账」留的,不是给「把全库拉平」留的:超限直接报错要求收窄," + "不会静默截断一半数据。", 57), Group("server", "跨域与接口", "允许跨域调用接口的前端来源。", 60), ) @@ -252,6 +255,12 @@ ITEMS: tuple[Item, ...] = ( "/api/v1/auth/apps/{code}/launch", "接口路径:发起免登跳转", "文档第 3.2 节的 POST /api/v1/auth/apps/{code}/launch;{code} 会换成本系统的应用编码。", normalizer="api_path"), + Item("hub_path_notify_wecom", "hub", ("hub", "api", "notify_wecom"), "OA_HUB_PATH_NOTIFY_WECOM", + KIND_STR, "/api/v1/auth/notify/wecom/messages", "接口路径:企业微信消息推送", + "对接文档 9.6.2 的 POST /api/v1/auth/notify/wecom/messages,「消息通知」里的" + "Hub 企业微信渠道用它发消息;逐人投递结果回查(9.6.7)打同一路径 + /{msg_key}。" + "用的是免登那把应用密钥,不需要另外领凭据。", + normalizer="api_path"), Item("hub_login_mode", "hub", ("hub", "login_mode"), "OA_HUB_LOGIN_MODE", KIND_ENUM, "hybrid", "登录校验模式", "hub = 只认统一身份;hybrid = 统一身份优先、它连不上时回退本地口令;" "sso = 只允许统一门户免登(本系统不再收账号密码);local = 只用品口令。", @@ -326,7 +335,9 @@ ITEMS: tuple[Item, ...] = ( KIND_BOOL, False, "免登必须校验 state", "地址栏带回了 state 就一定与本机 Cookie 里那条对上," "票据校验响应回传的 state 也对上,才放行(防会话固定与票据注入)。打开之后," "从 Hub 门户直接点进来、门户压根没把 state 带回来的那一路会被拒;" - "对接指南 1.4 说门户前端不解析跳转参数,所以先确认门户真会把 state 原样带回再打开。"), + "对接指南 1.4 说门户前端不解析跳转参数,所以先确认门户真会把 state 原样带回再打开。" + "特别注意:企业微信卡片点开那一路的票据按对接文档 9.6.5 天生不带 state," + "开这一档等于把点开卡片的人挡在门外(「消息通知」的渠道页会挂着这句提醒)。"), Item("hub_disabled", "hub", ("hub", "disabled"), "OA_HUB_DISABLED", KIND_BOOL, False, "应急总闸", "打开时无视上面所有 Hub 配置,登录与同步一律回本地。" "Hub 地址写错导致谁都登不进来时,把这个打开保存就能先进门,不用重启。"), @@ -372,6 +383,43 @@ ITEMS: tuple[Item, ...] = ( "对应 include_disabled=true;关掉时 Hub 里整棵停用的子树都拿不到。"), Item("hub_sync_offboard", "hub_sync", ("hub", "sync", "offboard"), "OA_HUB_SYNC_OFFBOARD", KIND_BOOL, True, "离职停用", "Hub 里已经消失的同步账号置为「已停用」。只停用不删除,本地账号永不受影响。"), + _i("hub_sync_offboard_guard_percent", "hub_sync", ("hub", "sync", "offboard_guard_percent"), + "OA_HUB_SYNC_OFFBOARD_GUARD_PERCENT", 40, "离职停用熔断(%)", + "一趟同步里等着停用的同步账号超过本地同步账号总数的这个百分比(并且超过下面那条" + "「离职停用熔断的人数底线」)时,这一趟一个人都不停用,只在同步记录里报数、并把该趟标成" + "「部分完成」。Hub 换环境、重导数据或清单出问题时最容易撞上:它会把几百个人一次性判成" + "离职,权限与待办当场全没。核对过清单确实没错,就把这一项调大或设 0(关掉熔断)再同步" + "一次。同一个百分比也管部门:一趟要停用的同步部门超过「部门停用熔断的个数底线」与" + "「同步部门总数 × 百分比」里的较大者时一个都不停。取值 0-95。", + minimum=0, maximum=95), + _i("hub_sync_offboard_guard_min_people", "hub_sync", ("hub", "sync", "offboard_guard_min_people"), + "OA_HUB_SYNC_OFFBOARD_GUARD_MIN_PEOPLE", 20, "离职停用熔断的人数底线", + "熔断线取「同步账号总数 × 百分比」与这个数里的较大者,所以小部署裁掉几个人不会被比例挡下来。" + "几十人的团队想让它更早触发就调小(比如 5),上千人的部署嫌 20 太松可以调大。" + "取值 0-5000,0 = 只看百分比。百分比本身设 0 时这一项不起作用(熔断整体关掉)。", + minimum=0, maximum=5000), + _i("hub_sync_unit_offboard_guard_min", "hub_sync", ("hub", "sync", "unit_offboard_guard_min"), + "OA_HUB_SYNC_UNIT_OFFBOARD_GUARD_MIN", 5, "部门停用熔断的个数底线", + "部门侧熔断线取「同步部门总数 × 离职停用熔断百分比」与这个数里的较大者。部门比人少得多," + "沿用人员那侧的 20 这条线的话永远不会触发,等于没有熔断;组织本来就只有几个的部署可以调小。" + "取值 0-5000,0 = 只看百分比。", + minimum=0, maximum=5000), + Item("hub_sync_reclaim_lost_accounts", "hub_sync", ("hub", "sync", "reclaim_lost_accounts"), + "OA_HUB_SYNC_RECLAIM_LOST_ACCOUNTS", KIND_BOOL, True, "让已查无此人的账号腾出登录名", + "Hub 合并或重导人员之后,账号名会挪到另一个 user_id 上,而占着这个名字的本地行绑的是" + "已被删掉的 user_id(Hub 的变更流水不记删除),同步又不许抢别人的账号,于是活着的人" + "永远拿不回 Hub 给他的登录名,每一趟都原样撞一次车。打开这一项后,那些**已经被停用、" + "且这一趟完整清单里查无此人**的同步账号会把登录名让出来(改名成 hub-lost--<原名>):" + "本地行、待办、审批轨迹、按主键挂的权限都不动,按账号存的引用跟着这行一起搬。" + "清单被截断的那一趟不让位,增量同步也不让位——一次补丁证明不了这个人已经不在了。"), + _i("hub_sync_roster_floor_percent", "hub_sync", ("hub", "sync", "roster_floor_percent"), + "OA_HUB_SYNC_ROSTER_FLOOR_PERCENT", 50, "让位名单的清单人数下限(%)", + "Hub 这次回的人员数不足「可参照基准 × 这个百分比」时,认定目录正在被清空或重导," + "这一趟一个登录名都不让位(撞车照旧只报数)。基准取「上次同步记下来的人数」与" + "「本地带 Hub 主键的账号数」里较小但仍然可信的那个。实测 2026-11-05 测试站一天之内" + "从 100 人掉到 1 人,靠这一条挡住了把上百个登录名一次性刷成 hub-lost-*。" + "取值 0-100,0 = 不设下限。", + minimum=0, maximum=100), Item("hub_sync_skip_unchanged", "hub_sync", ("hub", "sync", "skip_unchanged"), "OA_HUB_SYNC_SKIP_UNCHANGED", KIND_BOOL, True, "版本没变就跳过", "permission_version 与上次一致时不再写库。只作用于夜间定时," "界面上的「立即同步」永远强拉。"), @@ -591,6 +639,16 @@ ITEMS: tuple[Item, ...] = ( "环节开了外部审批、确认模式是「处理人点头」时,第三方那句表态停多久:到期没人确认就自动作废," "不催不补——催办有它自己的路。单据办结 / 终止 / 作废的那一刻,还停着的表态当场作废,不用等这里。", minimum=300, maximum=604800), + # ------------------------------------------------------------ 流程明细导出 + _i("export_detail_max_rows", "export", ("export", "detail_max_rows"), "OA_EXPORT_DETAIL_MAX_ROWS", 50000, + "单次导出行数上限", "「流程明细导出」一次最多落多少行(几条流程合起来数)。" + "比列表导出那 5000 行大,是因为这一页天生要跨月跨流程做台账;超了报错要求收窄," + "不静默截断。行数太大时最慢的一段是把整列表单正文搬回内存,别指望调到百万。", + minimum=500, maximum=500000), + _i("export_detail_max_columns", "export", ("export", "detail_max_columns"), + "OA_EXPORT_DETAIL_MAX_COLUMNS", 120, + "单张表最多多少列", "勾的列(含环节动态列摊出来的那几列)超过这个数就要求收窄。" + "列太宽的表在 Excel 里没人横向滚得动,报错比给一张看不清的表好。", minimum=10, maximum=400), Item("cors_origins", "server", ("server", "cors_origins"), "OA_CORS_ORIGINS", KIND_LIST, ("http://localhost:3000", "http://127.0.0.1:3000"), "允许跨域的前端来源", diff --git a/backend/app/hubconfig.py b/backend/app/hubconfig.py index 8562334..72e7f2a 100644 --- a/backend/app/hubconfig.py +++ b/backend/app/hubconfig.py @@ -70,6 +70,8 @@ API_PATHS = ( "hub_path_ticket_verify", "hub_path_apps", "hub_path_launch", + # 企业微信推送(Hub 代发):POST 发消息,GET 按 msg_key 回查逐人明细 + "hub_path_notify_wecom", ) API_PATH_DEFAULTS = { "hub_path_captcha": "/auth/captcha", @@ -82,6 +84,8 @@ API_PATH_DEFAULTS = { "hub_path_apps": "/api/v1/auth/apps", # {code} 在调用时换成本系统的应用编码(hub_app_code) "hub_path_launch": "/api/v1/auth/apps/{code}/launch", + # 对接文档 9.6.2 / 9.6.7:回查是同一个路径加上 /{msg_key},不单独配一项 + "hub_path_notify_wecom": "/api/v1/auth/notify/wecom/messages", } #: 《Hub 权限接口交互文档》那一层的接口路径(第 5~8、11 节) @@ -143,6 +147,11 @@ MANAGED = tuple( "hub_sync_bind_local_by_code", "hub_sync_include_disabled_units", "hub_sync_offboard", + "hub_sync_offboard_guard_percent", + "hub_sync_offboard_guard_min_people", + "hub_sync_unit_offboard_guard_min", + "hub_sync_reclaim_lost_accounts", + "hub_sync_roster_floor_percent", "hub_sync_skip_unchanged", "hub_sync_member_limit", "hub_sync_email_domain", @@ -199,6 +208,8 @@ class HubConfig: hub_path_ticket_verify: str hub_path_apps: str hub_path_launch: str + # 企业微信推送(Hub 代发)的消息接口,回查走同一路径 + /{msg_key} + hub_path_notify_wecom: str hub_sso_enabled: bool hub_app_code: str hub_integration_key: str @@ -229,6 +240,16 @@ class HubConfig: hub_sync_bind_local_by_code: bool hub_sync_include_disabled_units: bool hub_sync_offboard: bool + #: 离职停用熔断线(%):等着停用的人数超过本地同步账号总数的这个比例就先不停,0 = 关掉 + hub_sync_offboard_guard_percent: int + #: 熔断线的人数底线:熔断线取「总数 × 百分比」与这个数的较大者,见 hub_sync.OFFBOARD_GUARD_MIN_PEOPLE + hub_sync_offboard_guard_min_people: int + #: 部门侧熔断线的个数底线:部门比人少得多,不能沿用人员那侧的数 + hub_sync_unit_offboard_guard_min: int + #: 已停用、且这一趟完整清单里查无此人的同步账号,要不要把登录名让给 Hub 的现任主人 + hub_sync_reclaim_lost_accounts: bool + #: 让位名单的清单人数下限(%):Hub 回的人数不足基准的这个比例就不动任何登录名 + hub_sync_roster_floor_percent: int hub_sync_skip_unchanged: bool hub_sync_member_limit: int hub_sync_email_domain: str @@ -315,6 +336,32 @@ class HubConfig: return False return self.hub_enabled and self.hub_login_mode == "sso" + @property + def notify_on(self) -> bool: + """企业微信推送(Hub 代发)这一路现在能不能打出去。 + + 只看本系统这一半:Hub 开着、站点知道、应用密钥在。Hub 那边还有两道闸 + (全局推送开关 + 本应用 ``notify_enabled``),任一关着这里仍然是 ``True``, + 调用时会拿到 ``403 / 403001``,那是运维配置问题,不是这里能预判的(文档 9.6.1)。 + """ + if self.forced_off: + return False + return bool(self.hub_enabled and self.hub_base_url and self.hub_integration_key.strip()) + + @property + def notify_missing(self) -> list[str]: + """推送缺了哪几项,界面照着念(口径与 :attr:`notify_on` 一致)。""" + if self.forced_off: + return ["统一身份应急总闸(hub_disabled)"] + out: list[str] = [] + if not self.hub_enabled: + out.append("统一身份总开关(hub_enabled)") + if not self.hub_base_url: + out.append("Hub 站点地址") + if not self.hub_integration_key.strip(): + out.append("免登应用密钥") + return out + @property def portal_url(self) -> str: """统一门户首页:没登录时把用户送回哪里,没单独配就用 Hub 站点地址。""" @@ -379,8 +426,19 @@ class HubConfig: "ticket_verify": self.hub_path_ticket_verify, "apps": self.hub_path_apps, "launch": self.hub_path_launch, + "notify_wecom": self.hub_path_notify_wecom, } + def notify_status_path(self, msg_key: str) -> str: + """回查逐人投递明细的地址(文档 9.6.7):推送路径后面接 ``/{msg_key}``。 + + ``msg_key`` 是系统内可打印 ASCII(渠道编码 + 投递 id),转义只是防一手库里 + 存进过怪东西,别让一个坏键把整条回查变成打错地址。 + """ + from urllib.parse import quote + + return f"{self.hub_path_notify_wecom}/{quote(str(msg_key or '').strip(), safe='')}" + def launch_path(self, code: str = "") -> str: """免登跳转接口的完整路径:``{code}`` 占位符换成本系统(或指定)的应用编码。""" code = (code or self.hub_app_code).strip().lower() @@ -488,6 +546,7 @@ def build() -> HubConfig: hub_path_ticket_verify=_api_path(values.get("hub_path_ticket_verify"), "hub_path_ticket_verify"), hub_path_apps=_api_path(values.get("hub_path_apps"), "hub_path_apps"), hub_path_launch=_launch_path_value(values.get("hub_path_launch")), + hub_path_notify_wecom=_api_path(values.get("hub_path_notify_wecom"), "hub_path_notify_wecom"), hub_sso_enabled=bool(values.get("hub_sso_enabled", True)), hub_app_code=str(values.get("hub_app_code") or "").strip().lower(), hub_integration_key=str(values.get("hub_integration_key") or "").strip(), @@ -514,6 +573,11 @@ def build() -> HubConfig: hub_sync_bind_local_by_code=bool(values.get("hub_sync_bind_local_by_code", True)), hub_sync_include_disabled_units=bool(values.get("hub_sync_include_disabled_units", True)), hub_sync_offboard=bool(values.get("hub_sync_offboard", True)), + hub_sync_offboard_guard_percent=_clamp(values.get("hub_sync_offboard_guard_percent"), 0, 95, 40), + hub_sync_offboard_guard_min_people=_clamp(values.get("hub_sync_offboard_guard_min_people"), 0, 5000, 20), + hub_sync_unit_offboard_guard_min=_clamp(values.get("hub_sync_unit_offboard_guard_min"), 0, 5000, 5), + hub_sync_reclaim_lost_accounts=bool(values.get("hub_sync_reclaim_lost_accounts", True)), + hub_sync_roster_floor_percent=_clamp(values.get("hub_sync_roster_floor_percent"), 0, 100, 50), hub_sync_skip_unchanged=bool(values.get("hub_sync_skip_unchanged", True)), hub_sync_member_limit=_clamp(values.get("hub_sync_member_limit"), 1, 5000, 5000), hub_sync_email_domain=str(values.get("hub_sync_email_domain") or "").strip().lstrip("@").strip(), diff --git a/backend/app/main.py b/backend/app/main.py index d688e02..5019a26 100644 --- a/backend/app/main.py +++ b/backend/app/main.py @@ -28,7 +28,7 @@ from .db import (SchemaCreationRefused, SessionLocal, advisory_lock, connection_ from .envelope import install_exception_handlers, ok from . import storage as storage_module from .engine import engine as engine_module -from .service import channels, embed, embed_session, events, external_check, hub_sync, leader, openauth, outbox +from .service import channels, embed, embed_session, events, external_check, hub_sync, leader, openauth, outbox, wake from .seed import run as run_seed logging.basicConfig( @@ -161,7 +161,8 @@ _scheduler_stir = threading.Event() def _wake_scheduler() -> None: - """告诉调度线程"现在就有活":写回报文入队的那一刻用它,别等下一个轮询周期。""" + """告诉调度线程"现在就有活":任何一条外发任务(写回报文 / 渠道提醒 / 订阅事件)入队 + 并随事务提交的那一刻用它,别等下一个轮询周期。""" _scheduler_stir.set() @@ -360,8 +361,9 @@ def _scheduler_loop() -> None: db.rollback() finally: db.close() - # 跑完这一轮睡回去。这一觉能被"刚入队了报文"提前叫醒:写完回不再等下一个周期, - # 实测同一次提交入队的报文从"最多等 60 秒"变成当场就发(轮询退回兜底)。 + # 跑完这一轮睡回去。这一觉能被"刚排上了一条外发任务"提前叫醒:写回、渠道提醒、 + # 订阅事件都不再等下一个周期——企微推送实测从"最多等 60 秒"变成当场就发 + # (``service/wake.py``,轮询退回兜底)。 if _scheduler_sleep(tick): return @@ -382,9 +384,10 @@ def start_scheduler() -> None: logger.warning("后台调度线程已关闭(OA_SCHEDULER=%s):延时任务、到期标记、组织同步与写回投递都不会自动跑", os.environ.get("OA_SCHEDULER")) return - # 报文一入队就把这一条线程叫起来(同进程直接置事件,跨副本走 TOPIC_OUTBOUND 广播): - # 写回的即时性靠这个,15/60 秒那一档轮询退回"叫不醒也要发出去"的兜底。 - outbox.wake(_wake_scheduler) + # 外发任务一入队就把这一条线程叫起来(同进程直接置事件,跨副本走 TOPIC_OUTBOUND + # 广播):写回、消息渠道、事件订阅三条路共用这一个通路(``service/wake.py``), + # 即时性靠它,15/60 秒那一档轮询退回"叫不醒也要发出去"的兜底。 + wake.hook(_wake_scheduler) thread = threading.Thread(target=_scheduler_loop, name="unisoa-scheduler", daemon=True) thread.start() diff --git a/backend/app/models.py b/backend/app/models.py index a08c3eb..6fa5eca 100644 --- a/backend/app/models.py +++ b/backend/app/models.py @@ -2285,6 +2285,17 @@ class HubSyncRun(Base): cursor_seq: Mapped[int] = mapped_column(u_bigint(), default=0, nullable=False) changes_applied: Mapped[int] = mapped_column(Integer, default=0, nullable=False) message: Mapped[str] = mapped_column(Text, default="", nullable=False) + # 下面三项以前只出现在 message 的文本里,而 message 只留 2000 字:改名、僵尸账号让位 + # 这类「必须有人去核对」的动作一旦排在提示末尾就被截掉,同步历史里只剩一个笼统的 + # 「更新 N 人」,看完不知道该核对什么。计数单独成列,明细另存一份有界 JSON。 + #: 这一趟真正换掉登录名的人数(Hub 改了账号名,见 ``_plan_account_renames``) + renamed: Mapped[int] = mapped_column(Integer, default=0, nullable=False) + #: 已停用、且这一趟完整清单里查无此人的同步账号让出登录名的个数(``_retire_lost_accounts``) + reclaimed: Mapped[int] = mapped_column(Integer, default=0, nullable=False) + #: Hub 换了 ``organization_id`` 之后按「编码 + 名称」认回原部门的个数(``_sync_units``) + units_rebound: Mapped[int] = mapped_column(Integer, default=0, nullable=False) + #: 有界明细:改名前后对照、让位的账号、认回的部门、熔断与号码计数、提示原文(见 ``run_details``) + details: Mapped[JsonDict] = mapped_column(JsonDict, default=dict, nullable=False) class RefreshToken(Base, TimestampMixin): @@ -2889,11 +2900,16 @@ class NotifyChannel(Base, TimestampMixin): KIND_WECOM = "wecom" #: 自定义 HTTP:自己接企业微信自建应用、钉钉工作通知、内部短信网关都走这一条 KIND_WEBHOOK = "webhook" - KINDS = (KIND_EMAIL, KIND_DINGTALK, KIND_FEISHU, KIND_WECOM, KIND_WEBHOOK) + #: 统一身份 Hub 代发企业微信应用消息(对接文档 9.6):本系统不持有企微密钥, + #: 收件人按 Hub 账号解析,点开的免登也回到现成的 ``/api/v1/auth/sso/callback`` + KIND_HUB_WECOM = "hub_wecom" + KINDS = (KIND_EMAIL, KIND_DINGTALK, KIND_FEISHU, KIND_WECOM, KIND_WEBHOOK, KIND_HUB_WECOM) #: 需要 SMTP 参数的种类 SMTP_KINDS = (KIND_EMAIL,) #: 需要回调地址的种类 URL_KINDS = (KIND_DINGTALK, KIND_FEISHU, KIND_WECOM, KIND_WEBHOOK) + #: 地址与密钥都不在渠道上、跟着统一身份配置走的种类 + HUB_KINDS = (KIND_HUB_WECOM,) id: Mapped[str] = mapped_column(String(32), primary_key=True, default=new_id) code: Mapped[str] = mapped_column(String(64), nullable=False) @@ -2902,7 +2918,9 @@ class NotifyChannel(Base, TimestampMixin): enabled: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False) #: 订阅的通知事件(与 ``oa_notification.type`` 同一套取值:task / press / read / completed / expire …) events: Mapped[list] = mapped_column(JsonList, default=list, nullable=False) - #: 渠道参数:SMTP(host/port/user/password/from) 或 URL/secret;密钥只进不出 + #: 渠道参数:SMTP(host/port/user/password/from) / 机器人 URL/secret / + #: Hub 代发(msgtype/with_link/title_limit/**receiver**:收件人按哪一列认,见 + #: ``service/channels.py`` 的 ``HUB_RECEIVER_FIELDS``);密钥只进不出 config: Mapped[JsonDict] = mapped_column(JsonDict, default=dict, nullable=False) #: 正文模板(可选):留空用系统默认文案;支持 {title} {body} {url} {person} text_template: Mapped[str] = mapped_column(String(512), default="", nullable=False) @@ -2949,6 +2967,11 @@ class NotifyDelivery(Base, TimestampMixin): person_name: Mapped[str] = mapped_column(String(255), default="", nullable=False) #: 投递目标(邮箱地址 / 群机器人 URL);机器人地址带 access_token,界面上一律打码 target: Mapped[str] = mapped_column(String(512), default="", nullable=False) + #: ``target`` 这一串是按哪一列取来的(``user_id`` / ``account``),只有走统一身份 + #: Hub 的渠道才写。收件人标识现在是渠道上可配的一项,光看一串数字分不清是 + #: Hub 主键还是账号;人删了要重发、界面要说清"这条发给了谁的哪个号",都靠这一列。 + #: 升级前的老记录留空,读的一路按值猜(纯数字只可能是主键)。 + target_field: Mapped[str] = mapped_column(String(16), default="", nullable=False) title: Mapped[str] = mapped_column(String(512), default="", nullable=False) body: Mapped[str] = mapped_column(Text, default="", nullable=False) job: Mapped[str] = mapped_column(String(32), default="", nullable=False) diff --git a/backend/app/permissions.py b/backend/app/permissions.py index f3734bf..3311a59 100644 --- a/backend/app/permissions.py +++ b/backend/app/permissions.py @@ -77,7 +77,13 @@ CATALOG: tuple[Permission, ...] = ( ), ), *_group("org", ("org:unit", "org:person", "org:role", "org:authrole")), - *_group("system", ("monitor:work", "statistics:view", "log:view", "system:setting", + *_group("system", ("monitor:work", + # 流程明细导出:单独一码。监控那一档管的是"看着单子并伸手干预", + # 这一档管的是"把一批单据连金额一起拽出系统",要的人常常不是同一批。 + # 与 monitor:work 互不为前置,内置角色一个都不给(见 + # docs/process-detail-export-design.md §2)。 + "monitor:export", + "statistics:view", "log:view", "system:setting", # 消息渠道:配 SMTP / 群机器人,看投递记录(里面有收件人邮箱) "system:notify")), ) diff --git a/backend/app/schemas.py b/backend/app/schemas.py index a9de1c3..ec5573a 100644 --- a/backend/app/schemas.py +++ b/backend/app/schemas.py @@ -297,6 +297,17 @@ class UnitHubBindBody(CamelModel): hub_org_id: str +class UnitShellCleanupBody(CamelModel): + """清理「Hub 换过主键之后留下的空壳部门」。 + + ``ids`` 留空 = 清掉所有符合条件的壳子;填了就只动填的那几个(界面上逐条勾选用)。 + ``dry_run`` 只报"将要删哪些、哪些删不掉",一行都不动。 + """ + + ids: list[str] = [] + dry_run: bool = False + + class PersonBody(CamelModel): """新建/编辑人员;字段名与 ``users`` 列名一致。""" @@ -1004,6 +1015,56 @@ class MoveBody(CamelModel): opinion: str = "" +class ExportDetailUnoperatorBody(CamelModel): + """「未操作者」这一条筛选的完整口径,五类来源见 ``service/detail_export``。""" + + mode: str = "any" # any=包含任一 / all=包含全部 / not=不包含 + persons: list[str] = Field(default_factory=list) + #: 留空 = 用出厂四类(``addPending`` 那条默认不算);显式给 ``[]`` 也是同一档 + kinds: list[str] | None = None + include_principal: bool = False # 转办 / 代理的委托方也算 + exclude_locked: bool = False # 按钮锁在第三方的环节不算在这个人头上 + + +class ExportDetailFiltersBody(CamelModel): + """流程明细导出的筛选条件:截图红框那七项,外加关键字与超时。""" + + keyword: str = "" + processes: list[str] = Field(default_factory=list) + creator_mode: str = "" # "" / person / unit / keyword + creators: list[str] = Field(default_factory=list) + creator_unit_ids: list[str] = Field(default_factory=list) + creator_unit_sub: bool = True + creator_keyword: str = "" + create_start: str = "" + create_end: str = "" + archive_start: str = "" + archive_end: str = "" + statuses: list[str] = Field(default_factory=list) + paused: str = "" + expired: str = "" + unoperator: ExportDetailUnoperatorBody = Field(default_factory=ExportDetailUnoperatorBody) + project_name: str = "" + project_code: str = "" + project_op: str = "eq" # eq / contains + + +class ExportDetailBody(CamelModel): + """导什么(流程 + 列)与怎么分表(按流程分 sheet / 合并成一张表)。""" + + filters: ExportDetailFiltersBody = Field(default_factory=ExportDetailFiltersBody) + columns: list[str] = Field(default_factory=list) + #: 某几列只想给指定流程填值:``{"form.checkTotal": ["流程 id"]}`` + columns_only: dict[str, list[str]] = Field(default_factory=dict) + #: 勾选的环节动态列(每环摊「处理人 / 完成时间 / 意见」三列) + activities: list[str] = Field(default_factory=list) + layout: str = "perProcess" + summary: bool = False + fmt: str = "xlsx" + page: int = 1 + page_size: int = 20 + + class JobDataBody(CamelModel): """流程干预「修正表单数据」:只交改动的那几项,系统留痕由服务端自己写。""" diff --git a/backend/app/service/channels.py b/backend/app/service/channels.py index 49c2d14..e4e56cc 100644 --- a/backend/app/service/channels.py +++ b/backend/app/service/channels.py @@ -8,6 +8,11 @@ 入队与站内信同一事务(业务定了消息就一定在),投递交给后台调度线程,失败按退避重试, 重试用满进死信——和写回发件箱是同一套底线(``docs/notification-channels-design.md``)。 +``hub_wecom`` 是这一套里唯一的"转发型"渠道:消息不出到 SMTP,而是交给统一身份 Hub +代发企业微信应用消息(对接文档 9.6)。本系统不持有企微密钥、不碰 ``access_token``, +收件人按 Hub 账号解析,点开那张卡片回到的是**已经跑通的**免登回调,只是多带一个 +``redirect``。所以这一路的配置比 SMTP 还薄——连地址都没有,只有"发什么形态的消息"。 + 配置尽量薄:一个渠道只有"发到哪 + 发什么事 + 用什么身份发"三格。收件人不做配置项, **站内信发给谁这一路就发给谁**,邮箱从账号上取;账号没邮箱就在投递记录里留一条 ``skipped`` 并写明原因,不静默丢。 @@ -19,6 +24,7 @@ import base64 import hashlib import hmac import json +import logging import re import smtplib import time @@ -26,13 +32,16 @@ import urllib.parse import urllib.request from datetime import datetime, timedelta from email.message import EmailMessage -from typing import Any +from typing import Any, Iterable -from sqlalchemy import select, update +from sqlalchemy import case, func, or_, select, update from sqlalchemy.orm import Session -from .. import models, presence, readcache -from . import fetch, org, signing +from .. import hubconfig, models, presence, readcache +from . import fetch, hub as hub_api, org, signing +from . import wake as wake_signal + +logger = logging.getLogger("unisoa.channels") #: 可订阅的通知事件:取值与 ``oa_notification.type`` 完全一致,界面上就是几个勾选框 EVENTS: tuple[tuple[str, str], ...] = ( @@ -49,12 +58,107 @@ EVENT_KEYS = tuple(key for key, _ in EVENTS) BACKOFF_SECONDS = (60, 300, 1800) BATCH_LIMIT = 40 +#: 一轮最多发多久。刚入队那一条已被叫醒机制当场送到这一轮,可它排在谁的后面没有准: +#: 一个慢 SMTP 网关能把 40 条各顶满超时(渠道默认 10 秒),新消息就得陪着等完。 +#: 到点收工,剩下没认领的行状态一动没动,下一轮(或被新消息叫醒的那一轮)照样取得到。 +ROUND_BUDGET_SECONDS = 20.0 #: 正文进邮件/机器人时截这么长:机器人有长度墙,而且消息不该变成第二份表单 BODY_LIMIT = 1000 EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$") #: 密钥类配置键:接口回显时只说"已设置",不回明文 SECRET_KEYS = ("password", "secret", "token") +# --------------------------------------------------------------------------- +# Hub 企业微信推送(对接文档 9.6)的预算与语义 +# --------------------------------------------------------------------------- + +#: 两种消息形态:卡片(可点,跳转场景)与纯 markdown 提醒 +HUB_MSGTYPES = ("textcard", "markdown") +HUB_MSGTYPE_CARD = "textcard" +HUB_MSGTYPE_MARKDOWN = "markdown" +#: Hub 在标题前强制加 ``【应用名称】``,两边合计 ≤128 字符。本系统不知道自己 +#: 在 Hub 上叫什么(那是 Hub 侧登记的),所以默认只敢用一半,剩下留给应用名。 +HUB_TITLE_DEFAULT = 64 +HUB_TITLE_FLOOR = 8 +#: ``description`` 上限(文档 9.6.2) +HUB_DESC_BYTES = 512 +#: ``markdown`` 正文上限,单位是**字节**,且含 Hub 追加的 ``[查看详情](链接)`` 那一行 +HUB_CONTENT_BYTES = 2048 +#: 带深链时先给 Hub 那句追加留出的字节数:链接本身约 60~70 字节,留到 192 是 +#: 给长域名与 ``auth/go/<24 位>`` 之外的写法兜底——超了是 Hub 直接 400,整批没人收到 +HUB_LINK_RESERVE_BYTES = 192 +#: 一次调用 200 人是 Hub 的上限;本系统一条投递记录只有一个人,用不到切批 +HUB_RECEIVER_MAX = 200 +#: 这几类消息点开是要**办事**的,深链落待办页(有同意/退回那一套), +#: 而不是只能看的单据页;办结与抄送落单据页,会议提醒压根没单据 +HUB_TASK_EVENTS = ("task", "press", "expire") +#: 退成"不带链接的纯提醒"的两种来路,会记进 ``response.hub.degraded`` 给界面念: +#: 没有单据可指(会议提醒那类)/ Hub 上没登记本系统首页地址,深链拼不出来 +HUB_DEGRADED_NO_LINK = "no_link" +HUB_DEGRADED_NO_HOME = "hub_no_home" +#: Hub 用 Go 写时间,没赋值时回的是零值 ``0001-01-01T00:00:00Z`` 而不是缺字段 +HUB_ZERO_TIME = "0001-01-01" + +#: 逐人失败原因 -> 本系统怎么办。三档:稍后同键重发(retry)/ 不算故障,等人补 +#: 东西(skip)/ 再试也不会成,直接进死信喊人(dead)。表外的原因按 retry 处理, +#: 宁可多试三轮也别把一条本该送到的消息悄悄判死。 +HUB_RETRY_REASONS = frozenset({"rate_limited", "api_error", "sending"}) +HUB_SKIP_REASONS = frozenset({ + "user_not_found", "user_disabled", "wecom_not_bound", "wecom_rejected", "unlicensed", +}) +HUB_DEAD_REASONS = frozenset({"invalid_message", "quota_exceeded", "daily_limit_exceeded"}) + +#: 逐人原因翻成人话。这一列会直接进投递记录的 ``last_error``,运维不用翻文档 +HUB_REASON_LABELS = { + "user_not_found": "统一身份里没有这个账号,等下一轮组织人员同步或核对账号", + "user_disabled": "这个账号在统一身份里已停用", + "wecom_not_bound": "这个账号还没绑定企业微信成员,请在企业微信里补上「Hub账号」等资料后重发", + "wecom_rejected": "企业微信判定成员无效,通常是这个人不在应用的可见范围", + "unlicensed": "这个成员缺企业微信基础接口许可,请联系企微管理员购买", + "rate_limited": "同一个成员收消息太频繁,稍后自动重发", + "quota_exceeded": "本应用当日的推送人次数配额已用尽,明天再重发或请 Hub 调高配额", + "daily_limit_exceeded": "这个人今天收到的推送已达上限(跨所有来源应用),明天再重发", + "invalid_message": "消息组装失败(通常是链接或正文太长),改短之后再发", + "api_error": "企业微信接口报错,按 Hub 返回的错误码排查(最常见是可信 IP 未放行)", +} + + +# --------------------------------------------------------------------------- +# 收件人标识:Hub 认哪几种、渠道上怎么选 +# --------------------------------------------------------------------------- + +#: 对接文档 9.6.2 的 ``receivers`` 一项只认两种标识,多写一种会被 Hub 按参数不合法整条拒掉: +#: +#: * ``user_id`` —— Hub 的人员主键(本地 ``users.hub_user_id``)。账号能被别人注册走、 +#: 姓名会改、登录名也会在 Hub 侧改,只有它从头到尾指向同一个人,所以默认押它。 +#: * ``account`` —— 登录账号(本地 ``users.account``)。区分大小写的精确匹配,2026-10-20 起 +#: 还会随企业微信「Hub账号」扩展属性被同步改写(9.5),押它迟早对不上;但主键没同步过来的 +#: 环境(老库、手工建的本地账号)只有这一条路可走。 +#: +#: 每一项是 ``(标识名, 界面上的叫法, 本地列)``。**要加一种标识只需在这里加一行**, +#: 渠道配置、入队、发送、回查、界面清单都跟着认它(取法见 :data:`HUB_RECEIVER_VALUES`)。 +HUB_RECEIVER_FIELDS: tuple[tuple[str, str, str], ...] = ( + ("user_id", "Hub 用户 ID", "users.hub_user_id"), + ("account", "登录账号", "users.account"), +) +HUB_RECEIVER_LABELS: dict[str, str] = {key: label for key, label, _column in HUB_RECEIVER_FIELDS} +HUB_RECEIVER_COLUMNS: dict[str, str] = {key: column for key, _label, column in HUB_RECEIVER_FIELDS} +#: 没配过这一项的渠道照这个顺序认人:主键优先、退回账号。存量渠道一字不差地沿用。 +HUB_RECEIVER_DEFAULT: tuple[str, ...] = ("user_id", "account") + +#: 界面上摊开成几档。顺序就是优先级;只有一项时**不退回**另一种——那是管理员明确说过 +#: "只按这一列发",宁可跳过这个人,也别悄悄换成另一列把消息送到别人手机上。 +HUB_RECEIVER_PRESETS: tuple[tuple[tuple[str, ...], str, str], ...] = ( + (("user_id", "account"), "Hub 用户 ID 优先", + "先按 Hub 主键认人,主键没同步过来才退回登录账号,让 Hub 自己判一次 user_not_found。改名不丢消息。"), + (("account", "user_id"), "登录账号优先", + "主键不可信(比如同步回来的 id 与目录对不上)时按账号认,账号取不到再退主键。"), + (("user_id",), "只认 Hub 用户 ID", + "最严格:主键为空的人(本地自建号、还没同步的)直接跳过,绝不按账号猜。"), + (("account",), "只认登录账号", + "账号区分大小写、还会被企微「Hub账号」字段改写,一改账号这个人就收不到,直到主键补上。"), +) + # --------------------------------------------------------------------------- # 配置校验与视图辅助 @@ -81,6 +185,23 @@ def problems(row: models.NotifyChannel) -> list[str]: out.append("推送地址要以 http:// 或 https:// 开头") if kind == models.NotifyChannel.KIND_DINGTALK and not str(config.get("secret") or "").strip(): out.append("钉钉机器人建议填加签密钥(安全设置选「加签」),否则只能靠 IP 白名单") + if kind in models.NotifyChannel.HUB_KINDS: + cfg = hubconfig.get() + if not cfg.notify_on: + out.append("统一身份这边还发不出企业微信,缺:" + "、".join(cfg.notify_missing)) + if str(config.get("msgtype") or "").strip().lower() not in ("", *HUB_MSGTYPES): + out.append(f"消息形态只认 {' / '.join(HUB_MSGTYPES)},现在填的是 {config.get('msgtype')}") + # 收件人标识写错一个字母,后果是"这个人静默收不到"而界面上一切正常; + # 认不出的值当场挂在这条渠道上,比让它长成一条 skipped 投递记录好查得多 + if parse_hub_receiver_pref(config.get("receiver")) is None: + out.append("收件人标识只认 " + " / ".join(HUB_RECEIVER_LABELS.values()) + + f",现在填的是 {config.get('receiver')}") + # 点开那张卡片的那一趟不带 state(对接文档 9.6.5:推送链路签发的票据没有 state)。 + # 「免登必须校验 state」开成强制档时会当场拒掉,而点卡片的人只会看到一句「免登 + # 校验未通过」,不会回来说原因——这话得挂在这一页上。关掉深链的渠道不受影响。 + if getattr(cfg, "hub_sso_state_required", False) and hub_wants_link(row): + out.append("「免登必须校验 state」开着:卡片点开那一路不带 state,会被拒在门外;" + "要么关掉这一项,要么确认 Hub 门户真会把 state 原样带回") if not list(row.events or []): out.append("还没勾选要推送哪些消息") if str(row.text_template or "").strip(): @@ -94,6 +215,25 @@ def problems(row: models.NotifyChannel) -> list[str]: TEXT_VARS = ("title", "body", "url", "person", "time", "type") +#: 每一档种类**真正拥有**的配置键。换种类时靠它把上一档的参数筛掉: +#: 钉钉渠道改成 Hub 渠道之后,库里再拖着一个没人读的 url 只会让人以为还在发钉钉。 +#: 也是渠道保存时唯一认收的键——界面上多传的东西(比如把回显的 xxxSet 又提交回来) +#: 不会跟着进库。 +CONFIG_KEYS: dict[str, tuple[str, ...]] = { + models.NotifyChannel.KIND_EMAIL: ("host", "port", "security", "mail_from", "username", "password"), + models.NotifyChannel.KIND_DINGTALK: ("url", "secret"), + models.NotifyChannel.KIND_FEISHU: ("url", "secret"), + models.NotifyChannel.KIND_WECOM: ("url", "secret"), + models.NotifyChannel.KIND_WEBHOOK: ("url", "secret"), + models.NotifyChannel.KIND_HUB_WECOM: ("msgtype", "with_link", "title_limit", "receiver"), +} + + +def owned_config_keys(kind: str) -> tuple[str, ...]: + """这一档种类认收的配置键;认不出的种类回空元组(一个键都不留)。""" + return CONFIG_KEYS.get(str(kind or "").strip(), ()) + + def scrub_config(config: dict) -> dict: """回显给界面的渠道参数:密钥换成"是否已设置",绝不出明文。""" out = dict(config or {}) @@ -211,6 +351,25 @@ def enqueue_for( return 0 added = 0 for channel in wanted: + if channel.kind in models.NotifyChannel.HUB_KINDS: + # **Hub 代发是一人一条**:卡片要点开就是"我的那条待办",收件人必须在 + # 这条消息里唯一确定;合并成一条会让逐人失败原因(谁没绑企微、谁不在 + # 可见范围)无处可记,也就没法自动补发。 + links = hub_task_links(db, task, [identity for identity, _person in people]) + pref = hub_receiver_pref(channel.config) + for identity, person in people: + receiver, target = hub_receiver(person, pref) + row = _pending(channel, event, identity=identity, person=person, target=target, + target_field=hub_receiver_field(receiver), + title=title, body=body, job=job, work=work, + task=links.get(identity, ""), + process=process, notification=notification) + if not target: + row.status = models.NotifyDelivery.STATUS_SKIPPED + row.last_error = hub_no_receiver_reason(pref) + db.add(row) + added += 1 + continue if channel.kind in models.NotifyChannel.SMTP_KINDS: for identity, person in people: target = email_of(channel, person) @@ -240,6 +399,10 @@ def enqueue_for( added += 1 if added: db.flush() + # 站内信落库那一刻就把投递线程叫起来。渠道提醒晚 30 秒到人,人的读法不是 + # "渠道有点慢"而是"OA 根本不通知我"——这一句把等待从"最多一个轮询周期 + # (实测 28~60 秒)"压到当下,通路本身见 :mod:`service.wake`。 + wake_signal.mark(db) return added @@ -250,6 +413,7 @@ def _pending( identity: str, person, target: str, + target_field: str = "", title: str, body: str, job: str, @@ -268,6 +432,7 @@ def _pending( person=str(person.id), person_name=person_name or str(person.display_name), target=target, + target_field=target_field, title=title[:500], body=body or "", job=job, @@ -283,14 +448,379 @@ def email_of(channel: models.NotifyChannel, person) -> str: return value if EMAIL_RE.match(value) else "" +def _hub_user_id_of(person) -> str: + """Hub 人员主键:只认纯数字(``users.hub_user_id`` 那一列本来就是整数)。""" + text = str(getattr(person, "hub_user_id", None) or "").strip() + return text if text.isdigit() else "" + + +def _hub_account_of(person) -> str: + return str(getattr(person, "account", "") or "").strip() + + +#: 每种收件标识从本地哪一列取值。:data:`HUB_RECEIVER_FIELDS` 加一种,这里就得配一个取法。 +HUB_RECEIVER_VALUES: dict[str, Any] = { + "user_id": _hub_user_id_of, + "account": _hub_account_of, +} + + +def parse_hub_receiver_pref(value: object) -> tuple[str, ...] | None: + """把渠道上配的 ``receiver`` 解析成认人的顺序;出现认不出的标识回 ``None``。 + + 认列表也认逗号串(``"account,user_id"``),顺序即优先级,重复去掉。没配或配了个空 + → 默认那一档。保存渠道时靠 ``None`` 这一支把错别字当场挡下来,别让它在投递记录里 + 长成一句"取不到收件标识"。 + """ + if value is None: + return HUB_RECEIVER_DEFAULT + if isinstance(value, str): + items: list[object] = value.replace(",", " ").split() + elif isinstance(value, (list, tuple, set)): + items = list(value) + else: + return None + out: list[str] = [] + for item in items: + key = str(item or "").strip().lower() + if not key: + continue + if key not in HUB_RECEIVER_VALUES: + return None + if key not in out: + out.append(key) + return tuple(out) or HUB_RECEIVER_DEFAULT + + +def hub_receiver_pref(config: dict | None) -> tuple[str, ...]: + """渠道上配的收件人标识顺序。取配置的一路不炸:配歪了就按默认走。""" + return parse_hub_receiver_pref((config or {}).get("receiver")) or HUB_RECEIVER_DEFAULT + + +def hub_receiver_field(receiver: dict) -> str: + """Hub 那一项用的是哪种标识(``receivers`` 的一项只有一个键)。""" + return str(next(iter(receiver or {}), "")) + + +def hub_receiver_value(field: str, text: object) -> dict[str, object]: + """把记在投递记录里的标识还原成 Hub 要的那一项;``user_id`` 必须是整数。""" + value = str(text or "").strip() + if not value or field not in HUB_RECEIVER_VALUES: + return {} + return {field: int(value)} if field == "user_id" and value.isdigit() else {field: value} + + +def hub_receiver(person, pref: Iterable[str] | None = None) -> tuple[dict[str, object], str]: + """这个人在 Hub 上是谁:``(receivers 里那一项, 记到投递记录里的收件标识)``。 + + 按 ``pref`` 给的顺序逐个认,取到第一个非空就收工。不传就是默认的 + **"主键优先、退回账号"**(:data:`HUB_RECEIVER_DEFAULT`)——押主键是因为改名、改登录名 + 都不动它,而 ``account`` 是区分大小写的精确匹配、2026-10-20 起还会随企业微信 + 「Hub账号」扩展属性被同步改写;主键为空(本地账号还没被统一身份认领)时才退回账号, + 让 Hub 自己判一次 ``user_not_found``,它比我们猜得准,也比"本地直接不发"多一条 + 能被管理员看懂的理由。 + + 渠道把某一种单独勾出来时**不退回**另一种:那是管理员明确说过"只按这一列发", + 宁可跳过这个人并写明原因,也别悄悄换成另一列把人送错。 + """ + for field in tuple(pref) if pref else HUB_RECEIVER_DEFAULT: + take = HUB_RECEIVER_VALUES.get(str(field or "").strip().lower()) + if take is None: + continue + text = str(take(person) or "").strip() + if not text: + continue + return hub_receiver_value(str(field).strip().lower(), text), text + return {}, "" + + +def hub_no_receiver_reason(pref: Iterable[str] | None = None) -> str: + """取不到收件标识时写给管理员的那句话:点名按哪几列找过、该去哪儿补。""" + fields = tuple(pref) if pref else HUB_RECEIVER_DEFAULT + named = "、".join(HUB_RECEIVER_LABELS.get(field, field) for field in fields) + columns = "、".join(HUB_RECEIVER_COLUMNS.get(field, field) for field in fields) + return (f"这个账号在统一身份里对不上号:按渠道配的收件人标识({named},取自 {columns})" + "在这个人身上取不到值,这条没发出去。要么到「组织人员」里给这个人补上," + "要么把渠道的收件人标识换成另一种。") + + +#: 每种收件标识"这个人到底有没有"的库内判据,口径与 :data:`HUB_RECEIVER_VALUES` 一致 +HUB_RECEIVER_SQL: dict[str, Any] = { + "user_id": lambda: models.User.hub_user_id.is_not(None), + "account": lambda: models.User.account != "", +} + + +def hub_receiver_coverage(db: Session) -> dict[str, Any]: + """在职账号里各收件标识能覆盖多少人:换标识之前先看这一眼。 + + 换成"只认登录账号"而库里三成是本地自建号,界面上怎么选都对,要等投出一堆 + ``skipped`` 才知道坏事。这一条聚合把话提到保存之前说:``fields`` 是每一种**各自** + 能发到多少人,``any`` 是几种都试一遍(默认那一档)能发到的人数, + ``none`` 是怎么配都发不到的那批人——最后这一档才是运维该盯着补的数。 + """ + fields = [field for field in HUB_RECEIVER_SQL if field in HUB_RECEIVER_VALUES] + if not fields: + return {"active": 0, "fields": {}, "any": 0, "none": 0} + row = db.execute( + select( + func.count(models.User.id), + *[func.sum(case((HUB_RECEIVER_SQL[field](), 1), else_=0)) for field in fields], + func.sum(case((or_(*[HUB_RECEIVER_SQL[field]() for field in fields]), 1), else_=0)), + ).where(models.User.status == models.UserStatus.ACTIVE) + ).one() + active = int(row[0] or 0) + return { + "active": active, + "fields": {field: int(row[index + 1] or 0) for index, field in enumerate(fields)}, + "any": int(row[len(fields) + 1] or 0), + "none": active - int(row[len(fields) + 1] or 0), + } + + +def hub_task_links(db: Session, task: str, identities: list[str]) -> dict[str, str]: + """这批人各自能拿到哪条待办深链:只有这条待办的持有人拿得到。 + + ``engine.notify()`` 对**整批**收件人只传一个 ``task=``,而 ``/todo/`` 是个人 + 页面。眼下多收件人还带 task 的只有"外部审批那一环超时"(待办持有人 + 兜底管理员 + 一起收,见 ``engine.py`` 里那处 ``[task.identity, _fallback_admin_ref(db)]``), + 照原样发给管理员,他点开的是"不是我的那条待办"——审批页只读、按钮全灰。所以一人 + 一条在这里按人分一次:不是持有人就把 task 抹掉,深链退回 ``/work/``, + 那一页管理员本来就看得懂也动得了。 + + 单收件人批次不查库(待办到达是热路径,每单都要走一遍,多一次 ``SELECT`` 不值); + 查不到待办行也一并抹掉——那条待办多半已经被办掉了,``/todo/`` 点开会是一句 + "待办不存在或已被处理",不如去看单据。 + """ + if not task: + return {} + if len(identities) < 2: + return {identity: task for identity in identities} + row = db.get(models.Task, task) + holder = str(getattr(row, "identity", "") or "").strip() + return {identity: task for identity in identities if holder and identity == holder} + + +def hub_target_for( + db: Session, row: models.NotifyDelivery, channel: models.NotifyChannel | None = None, +) -> dict[str, object]: + """发送这一刻的收件人标识,按渠道配的 :func:`hub_receiver_pref` 顺序认。 + + 取的值以人为准、不以 :attr:`NotifyDelivery.target` 为准:入队之后可能又跑了一趟 + 组织人员同步(``hub_user_id`` 补上了),管理员也可能刚把这一路的收件人标识换成 + 登录账号,这条排队里的记录就该按**发送这一刻的口径**发。 + + 人查不到(账号被删)才回落到记录里那一对 ``(target_field, target)``;升级之前的 + 老记录没写过是哪一列,只能按值猜——纯数字只可能是 Hub 主键,口径与改造前一字不差。 + """ + pref = hub_receiver_pref(getattr(channel, "config", None)) + person_id = str(row.person or "").strip() + if person_id.isdigit(): + person = db.get(models.User, int(person_id)) + if person is not None: + receiver, _target = hub_receiver(person, pref) + if receiver: + return receiver + value = str(row.target or "").strip() + if not value: + return {} + field = str(row.target_field or "").strip().lower() + if field: + return hub_receiver_value(field, value) + return {"user_id": int(value)} if value.isdigit() else {"account": value} + + +def _clip_chars(text: str, limit: int) -> str: + """按**字符**截断(Hub 的标题与 description 限的是字符数)。""" + value = str(text or "") + if len(value) <= limit: + return value + return value[:max(0, limit - 1)].rstrip() + "…" + + +def _clip_bytes(text: str, limit: int) -> str: + """按 **UTF-8 字节**截断:``markdown`` 的 2048 是字节数,中文一个字占三个字节。 + + ``errors="ignore"`` 吃掉切一半的那个多字节字符,末尾再补一个省略号(省略号自己 + 也是 3 字节,所以先让出 3 字节的位置)。 + """ + raw = str(text or "").encode("utf-8") + if len(raw) <= limit: + return str(text or "") + keep = raw[:max(0, limit - 3)].decode("utf-8", "ignore").rstrip() + return keep + "…" + + +def hub_msgtype(channel: models.NotifyChannel) -> str: + value = str((channel.config or {}).get("msgtype") or HUB_MSGTYPE_CARD).strip().lower() + return value if value in HUB_MSGTYPES else HUB_MSGTYPE_CARD + + +def hub_wants_link(channel: models.NotifyChannel) -> bool: + """这条渠道要不要带单据深链。关掉之后发出的是纯提醒,不占用 Hub 的深链。""" + value = (channel.config or {}).get("with_link", True) + if isinstance(value, str): + return value.strip().lower() not in ("", "0", "false", "no", "off") + return bool(value) + + +def hub_title_limit(channel: models.NotifyChannel) -> int: + try: + value = int((channel.config or {}).get("title_limit") or HUB_TITLE_DEFAULT) + except (TypeError, ValueError): + value = HUB_TITLE_DEFAULT + return max(HUB_TITLE_FLOOR, min(120, value)) + + +def hub_msg_key(row: models.NotifyDelivery, *, variant: str = "") -> str: + """这一条业务通知的幂等键:**跨重试保持不变**,只有人工补发时才换世代。 + + 文档 9.6.4 把重试姿势压成一句话——超时之后用同一个 ``msg_key`` 原样重发。投递记录 + 的 ``id`` 天生满足这件事:同一条记录退避重发、进程重启重发,键都不变,Hub 会把 + "已经投过"的那次回成 ``duplicate``。反过来,``partial`` / ``sent`` 之后人工点重发, + 同键只会命中缓存拿到旧明细(人不会重复收到,但运维会以为没发出去),所以那种 + 重发要换世代号 ``-r2``、``-r3``,让它变成一条真的新消息。 + """ + base = f"oa-{row.channel}-{row.id}" + try: + seq = int((row.response or {}).get("msgKeySeq") or 0) + except (TypeError, ValueError): + seq = 0 + if seq > 0: + base = f"{base}-r{seq}" + #: ``variant`` 是"同一条通知换了内容还得再发一次"留的口子(Hub 拼不出深链时摘掉 + #: 链接改发纯提醒,见 :func:`_hub_send`)。那是一条**内容不同**的消息,同键只会 + #: 命中 Hub 的缓存拿回旧明细;后缀先给 128 留出位置,免得截断把后缀截掉。 + tail = f"-{variant}" if variant else "" + return f"{base[:128 - len(tail)]}{tail}" + + +def hub_payload( + db: Session, channel: models.NotifyChannel, row: models.NotifyDelivery, *, + link: str = "", force_no_link: bool = False, +) -> tuple[dict, str]: + """照文档 9.6.2 组一次请求体,回 ``(请求体, 降级说明)``。 + + 截断全在这里:Hub 那边是 400 硬拒(不是替你截断),超了就是整批没人收到。 + 降级说明现在是 ``no_link`` 一种:卡片配了但没有单据可指,改发纯文本提醒。 + ``force_no_link`` 是同一条退路的另一半——Hub 认得出深链但拼不出(没登记 + ``home_url``)时由 :func:`_hub_send` 传 True:文档 9.6.2 说 ``target_path`` 留空 + 就是纯文字提醒,宁可朴素也别让整条消息判死、一个人收不到。 + """ + receiver = hub_target_for(db, row, channel) + # 渠道把深链关掉时,测试发送也不该擅自带一条出去 + if force_no_link: + path = "" + else: + path = link if (link and hub_wants_link(channel)) else hub_target_path(channel, row) + # 卡片没有链接就是一张点不动的卡片:没有单据可指(meeting 这类)就退成纯文本提醒, + # 与"群里那条不带链接的机器人消息"同一立场——宁可朴素,别给一个点开白屏的东西。 + msgtype = hub_msgtype(channel) + degraded = "" + if msgtype == HUB_MSGTYPE_CARD and not path: + msgtype = HUB_MSGTYPE_MARKDOWN + degraded = HUB_DEGRADED_NO_LINK + # 深链照旧喂给模板里的 {url}(有人就想在正文里写"详情见 xxx"),但默认模板 + # 把它当第三行拼出来的那一句要抹掉:卡片上它是那颗按钮,markdown 里 Hub 自己 + # 追加 "[查看详情](链接)",正文里再抄一遍路径只是占字数 + text = _strip_link_line(render_text(channel, row, link=path), path) + payload: dict[str, object] = { + "msg_key": hub_msg_key(row), + "msgtype": msgtype, + "receivers": [receiver] if receiver else [], + } + if path: + payload["target_path"] = path + if msgtype == HUB_MSGTYPE_CARD: + # 标题与正文都得有东西:Hub 对 textcard 的 title/description 是必填, + # 空一个是 400 整条被拒,而"正文被模板清空"这种事只有发的时候才发现 + description = _strip_title(text, row.title) or str(row.body or "").strip() or str(row.title or "") + payload["title"] = _clip_chars(row.title, hub_title_limit(channel)) + payload["description"] = _clip_chars(description, HUB_DESC_BYTES) + else: + budget = HUB_CONTENT_BYTES - (HUB_LINK_RESERVE_BYTES if path else 0) + content = str(text or "").strip() or str(row.title or "") + payload["content"] = _clip_bytes(content, budget) + return payload, degraded + + +def _strip_link_line(text: str, path: str) -> str: + """抹掉默认模板拼在最后一行的那条深链路径(自定义模板写在中间的 ``{url}`` 不动)。""" + value = str(text or "").strip() + tail = str(path or "").strip() + if not tail: + return value + if value == tail: + return "" + if value.endswith("\n" + tail): + return value[: -len(tail) - 1].rstrip() + return value + + +def _strip_title(text: str, title: str) -> str: + """默认模板渲染出来的第一行就是标题,卡片上标题会单独显示,正文里别再来一遍。""" + value = str(text or "").strip() + head = str(title or "").strip() + if head and value.startswith(head): + value = value[len(head):].strip() + return value + + +def hub_outcome(recipient_status: str, reason: str) -> tuple[str, str]: + """逐人结果 -> ``(本系统状态, 给人看的一句话)``。 + + 返回的状态取 :data:`models.NotifyDelivery` 那几个常量。分档表在 + :data:`HUB_RETRY_REASONS` / :data:`HUB_SKIP_REASONS` / :data:`HUB_DEAD_REASONS`。 + """ + slug = str(reason or "").strip() + if str(recipient_status or "").strip().lower() == "sent": + return models.NotifyDelivery.STATUS_SUCCESS, "" + label = HUB_REASON_LABELS.get(slug, "") + if slug in HUB_RETRY_REASONS or slug not in (HUB_SKIP_REASONS | HUB_DEAD_REASONS): + return models.NotifyDelivery.STATUS_FAILED, f"Hub 暂未投出({slug or '未知原因'}):{label or '稍后自动重试'}" + if slug in HUB_SKIP_REASONS: + return models.NotifyDelivery.STATUS_SKIPPED, label or f"这个人收不到({slug})" + return models.NotifyDelivery.STATUS_DEAD, label or f"投递失败({slug})" + + +def work_path(job: str) -> str: + """单据在站内的相对路径(``/work/``),没有单据就回空串。 + + Hub 推送要的是 ``target_path``:**站内相对路径**,绝对地址由 Hub 按本系统登记的 + ``home_url`` 在点击时刻现拼(文档 9.6.6)。所以这一路绝不能把 ``site_front_url`` + 拼进去——那等于把域名写死进一条永久有效的链接里,以后换域名历史消息全成死链。 + """ + return f"/work/{str(job).strip()}" if str(job or "").strip() else "" + + +def hub_target_path(channel: models.NotifyChannel, row: models.NotifyDelivery) -> str: + """这条消息的深链(``target_path``):站内相对路径,不带域名。 + + 待办 / 催办 / 超时落 ``/todo/``——那是审批人自己的页面,"点开即批"就靠它; + 其余(办结、抄送、评论)落 ``/work/``。没有单据可指就回空串, + Hub 那边发出的是不带链接的纯提醒。 + + ``row.task`` 已经是"这个人的那条待办":入队时由 :func:`hub_task_links` 按人分过, + 同批里不是持有人的那几条根本不带 task,所以这里不必再问库。 + + 落点对不对、这个人有没有权限看,本系统自己判(Hub 只负责把路径原样带到 + ``redirect``,见文档 9.6.5 与 9.6.8)。 + """ + if not hub_wants_link(channel): + return "" + if str(row.type or "") in HUB_TASK_EVENTS and str(row.task or "").strip(): + return f"/todo/{str(row.task).strip()}" + return work_path(row.job) + + def work_link(job: str, *, base: str = "") -> str: """消息里带的单据链接。站点地址取「系统设置 → 站点信息 → 系统访问地址」,没配就只留相对路径。""" from .. import dbconfig site = str(dbconfig.value("site_front_url", "") or "").strip().rstrip("/") - if not job: + path = work_path(job) + if not path: return site - path = f"/work/{job}" if base: return f"{base.rstrip('/')}{path}" return f"{site}{path}" if site else path @@ -355,6 +885,220 @@ class _Fatal(Exception): """再重试也不会成功的失败(口令错、收件人被拒),直接进死信喊人。""" +class _Skipped(Exception): + """**这个人现在收不到,但不是故障**:没有邮箱、没绑企业微信、账号没认领。 + + 与 :class:`_Fatal` 分开记,是为了让"投递交付失败"和"收件人缺一块资料"在 + 投递记录的统计里各归各的——后者混进失败里,运维就永远看不出到底谁在掉队。 + """ + + +def hub_key_seq(row: models.NotifyDelivery) -> int: + """当前这个 ``msg_key`` 是第几世(0 = 首次那一版)。存在 ``response`` 里, + 人工补发已投出去的消息时由 :func:`resend` 加一。""" + try: + return int((row.response or {}).get("msgKeySeq") or 0) + except (TypeError, ValueError): + return 0 + + +def _hub_client(timeout: int): + """发送用的 Hub 客户端:站点、熔断、在飞闸门都跟统一身份共用一套。 + + 超时用**渠道自己那一格**:推送是后台调度里跑的,和登录那条在线链路不同一条命, + 配渠道的人知道自家 Hub 有多慢。熔断照旧共享——Hub 真的不理人时,这一路也不该 + 把调度线程一条条排上去干等。 + """ + cfg = hubconfig.get() + return hub_api.HubClient(cfg.hub_base_url, timeout=max(1, int(timeout))) + + +def _hub_request_error(exc: hub_api.HubError) -> Exception: + """请求级失败翻成本系统的处置。分类只看 HTTP 状态码与 ``code``(文档 9.6.4 明确 + 说了别拿 ``message`` 的中文文案做判断),文案只作为给人看的那半句。 + """ + code = str(exc.code or "").strip() + status = int(getattr(exc, "status", 0) or 0) + message = str(exc.message or "").strip() + if status == 409: + # 同一个 msg_key 上一次还在发送中:并发保护,不是失败,稍后同键再来 + return SendError(f"Hub 上这一条还在发送中,稍后自动重试:{message}") + if status == 401 or code == hub_api.CODE_UNAUTHORIZED: + if not code.isdigit(): + # 网关式的裸 ``{"error":"unauthorized"}``:这台 Hub 对"这条路径压根没注册" + # 也回同一种 401,光说密钥会让人白换一把。两种可能都得报出去(真环境两种都遇到过)。 + return _Fatal( + "企业微信推送这一步 Hub 没认这次请求(401 unauthorized),两种可能都要查:" + "①这把免登应用密钥不被本 Hub 认(系统设置 → 统一身份 里换一把有效的);" + f"②这台 Hub 上还没有推送这个接口、或它前面的网关没放行这条路径" + f"({hubconfig.get().hub_path_notify_wecom})。对方原话:{message}" + ) + return _Fatal(f"统一身份不认这把应用密钥(或本系统已停用),发不出企业微信:{message or code}") + if status == 403 or code == hub_api.CODE_FORBIDDEN: + return _Fatal( + "企业微信推送开关没开:全局开关与本应用的推送开关都在 Hub 侧," + f"要找 Hub 管理员开闸。对方原话:{message}" + ) + if status == 400 or code == hub_api.CODE_BAD_REQUEST: + hint = ";Hub 上没登记本系统的首页地址(home_url),深链拼不出来,请 Hub 管理员补填" \ + if "首页" in message else "" + return _Fatal(f"Hub 认为这条消息不合法,重发也一样:{message}{hint}") + if status == 503: + return SendError(f"Hub 那边企业微信还没配好,修好就能发:{message}") + return SendError(f"统一身份这一步没走通,稍后自动重试:{message or exc}") + + +def hub_home_url_missing(exc: hub_api.HubError) -> bool: + """这次 400 是不是"Hub 上没登记本系统的首页地址"(深链拼不出来)。 + + 文档 9.6.4 把参数类错误全塞进同一个 ``400001``,能分辨的只有文案,所以这里 + **只决定要不要摘掉深链再试一次**:认不出就照旧判死,认错也只是多发一条纯提醒, + 两种失败方向都比"整条丢掉、一个人收不到"轻。 + """ + if int(getattr(exc, "status", 0) or 0) != 400: + return False + message = str(exc.message or "") + return "首页" in message or "home_url" in message + + +def hub_time(value: object) -> str: + """Hub 的 ``sent_at``:零值当没填。Hub 那边这个字段常常没赋值, + 直接抄进界面就会出现"发送于 0001-01-01"这种鬼话。""" + text = str(value or "").strip() + return "" if not text or text.startswith(HUB_ZERO_TIME) else text + + +def hub_enterprise_hint(data: dict) -> str: + """企业微信自己回的那句(``wecom_errcode`` / ``wecom_errmsg``),只挂在失败上。 + + 逐人 ``reason`` 说的是"哪一类问题",企微那句才是"具体哪一处": + ``81013 user & party & tag all invalid`` 就是这个人不在应用可见范围(或成员已离职), + 运维照着那个码去企微的 devtool 一查就到底,比在我们这句"通常是可见范围问题"里猜快。 + """ + code = str(data.get("wecom_errcode") or "").strip() + message = _brief(str(data.get("wecom_errmsg") or ""), 160) + if not (code or message): + return "" + return f"(企业微信:{code} {message})" + + +def _match_recipient(recipients: list[dict], receiver: dict) -> dict | None: + """从逐人明细里找出**这条记录对应的那个人**。 + + 文档 9.6.3 说得很清楚:别按数组下标对应请求,按 ``receiver`` 回显值对应。 + 本系统一次只发一个人,所以回显对不上时(Hub 换了写法)退化成"就一条,是它"。 + """ + want = str(next(iter(receiver.values()), "")).strip() + for item in recipients: + if str(item.get("receiver") or "").strip() == want: + return item + return recipients[0] if len(recipients) == 1 else None + + +def _hub_send( + db: Session, row: models.NotifyDelivery, channel: models.NotifyChannel, timeout: int, + *, link: str = "", +) -> tuple[str, int, dict[str, Any]]: + """发一条给 Hub 代发。返回 ``(给人看的一句话, HTTP 状态, 要并进 response 的东西)``。 + + 三条来自文档 9.6 的硬规矩: + + * **不自己重试**:幂等靠 ``msg_key``,超时之后由调度退避、原样同键重发, + Hub 会三选一(已投过回缓存 / 整批没投过重发 / 还在发回 409); + * **逐人结果才算数**:HTTP 200 且 ``code=="200"`` 只说明 Hub 听懂了, + 这个人到底收到没有看 ``recipients[].status``; + * **原因要留住**:``reason`` 原样存进 ``response.hub``,界面上直接看得见, + 补发时不用回来翻 Hub 的日志。 + """ + cfg = hubconfig.get() + if not cfg.notify_on: + raise SendError("统一身份现在发不出企业微信,缺:" + "、".join(cfg.notify_missing)) + payload, degraded = hub_payload(db, channel, row, link=link) + receivers = payload.get("receivers") or [] + if not receivers: + raise _Skipped(hub_no_receiver_reason(hub_receiver_pref(channel.config))) + receiver = receivers[0] + # 记录里那一对标识要跟**真正发出去**的那一对一致:入队之后人可能被同步改了主键、 + # 渠道也可能被换成按账号发,「回查送达」是拿记录里的标识去对 Hub 的回显的, + # 对不上就找不到人(本系统一次只发一个人,靠"就一条"兜得住,但界面会念错是谁)。 + used_field = hub_receiver_field(receiver) + used_value = str(receiver.get(used_field, "")) if used_field else "" + if used_field and (row.target_field != used_field or row.target != used_value): + row.target_field = used_field + row.target = used_value + seq = hub_key_seq(row) + client = _hub_client(timeout) + try: + data = client.notify_wecom(payload) + except hub_api.HubError as exc: + if not payload.get("target_path") or not hub_home_url_missing(exc): + raise _hub_request_error(exc) from exc + # Hub 应用没登记 home_url:带深链的那一条整批被 400 拒掉,谁都没收到。 + # 摘掉深链换纯提醒重发一次(内容变了,所以换个键,同键只会命中缓存), + # 人至少知道有单子要处理;至于点开那一跳,等管理员补上 home_url 之后 + # 新消息自动就带回链接了(文档 9.6.6:深链基址是点击时刻现拼的)。 + payload, _ignored = hub_payload(db, channel, row, link=link, force_no_link=True) + payload["msg_key"] = hub_msg_key(row, variant="nolink") + degraded = HUB_DEGRADED_NO_HOME + try: + data = client.notify_wecom(payload) + except hub_api.HubError as retry_exc: + raise _hub_request_error(retry_exc) from retry_exc + + recipients = [item for item in (data.get("recipients") or []) if isinstance(item, dict)] + mine = _match_recipient(recipients, receiver) + status = str(data.get("status") or "").strip().lower() + summary: dict[str, Any] = { + "msgKey": str(payload.get("msg_key") or ""), + "msgKeySeq": seq, + "status": status, + "attempt": data.get("attempt"), + "sentAt": hub_time(data.get("sent_at")), + "duplicate": bool(data.get("duplicate")), + "link": str(data.get("link") or ""), + "grant": str(data.get("grant") or ""), + "reason": str((mine or {}).get("reason") or ""), + "wecomUserId": str((mine or {}).get("wecom_userid") or ""), + "recipients": recipients[:HUB_RECEIVER_MAX], + } + if degraded: + summary["degraded"] = degraded + if data.get("wecom_errcode") is not None: + summary["wecomErrcode"] = data.get("wecom_errcode") + if data.get("wecom_errmsg"): + summary["wecomErrmsg"] = str(data.get("wecom_errmsg")) + detail = _brief(json.dumps({k: v for k, v in summary.items() if k != "recipients"}, + ensure_ascii=False), 380) + # 先落一份带 hub 明细的 response:下面无论走成功还是抛异常,界面上都看得见 + # 对方到底说了什么(失败路径上 deliver() 不会再动 response) + row.response = {"httpStatus": 200, "detail": detail, "hub": summary} + + if mine is None: + # 没有逐人明细 = 整批就没投出去(文档 9.6.3:请求级原因看 wecom_errmsg) + if status in ("sent", "partial"): + return detail, 200, {"hub": summary} + why = str(data.get("wecom_errmsg") or data.get("wecom_errcode") or "没回逐人结果") + raise SendError(f"Hub 说这一条没投出去:{_brief(why, 300)}") + + outcome, message = hub_outcome(str(mine.get("status") or ""), str(mine.get("reason") or "")) + if outcome != models.NotifyDelivery.STATUS_SUCCESS: + message = f"{message}{hub_enterprise_hint(data)}" + if outcome == models.NotifyDelivery.STATUS_SUCCESS: + notes = [] + if summary["duplicate"]: + # 同键命中缓存:这个人之前收到过,没重复收到。当作成功,但要说清楚 + notes.append("Hub 命中幂等缓存,这条此前已投出") + if summary.get("degraded") == HUB_DEGRADED_NO_HOME: + notes.append("Hub 上没登记本系统首页地址(home_url),这条退成了不带链接的" + "纯提醒;请 Hub 管理员补填,补好之后新消息自动带回深链") + return (f"{detail}({';'.join(notes)})" if notes else detail), 200, {"hub": summary} + if outcome == models.NotifyDelivery.STATUS_SKIPPED: + raise _Skipped(message) + if outcome == models.NotifyDelivery.STATUS_DEAD: + raise _Fatal(message) + raise SendError(message) + + def _robot_body(kind: str, text: str, delivery: models.NotifyDelivery) -> tuple[bytes, dict[str, str]]: """按平台要求的 JSON 结构组包。三家机器人的文本消息结构不一样,这里一次对齐。""" headers = {"Content-Type": "application/json"} @@ -397,8 +1141,18 @@ def _signed_url(kind: str, config: dict, url: str, body: bytes) -> str: return url -def deliver(db: Session, row: models.NotifyDelivery, *, channel: models.NotifyChannel | None = None) -> models.NotifyDelivery: - """发一条。成功记 ``success``,可重试的失败按退避重排,判死的直接进 ``dead``。""" +def deliver( + db: Session, + row: models.NotifyDelivery, + *, + channel: models.NotifyChannel | None = None, + hub_link: str = "", +) -> models.NotifyDelivery: + """发一条。成功记 ``success``,可重试的失败按退避重排,判死的直接进 ``dead``。 + + ``hub_link`` 只给"测试发送"用:那一条没有真实单据可指,指到待办列表才能把点开 + 那一跳(Hub 认人 + ``redirect``)一起验掉;正常投递一律留空,深链按记录自己算。 + """ channel = channel or db.execute( select(models.NotifyChannel).where(models.NotifyChannel.code == row.channel) ).scalar_one_or_none() @@ -411,9 +1165,12 @@ def deliver(db: Session, row: models.NotifyDelivery, *, channel: models.NotifyCh text = render_text(channel, row, link=link) config = dict(channel.config or {}) timeout = max(1, int(channel.timeout_seconds or 10)) + extra: dict[str, Any] = {} started = time.perf_counter() try: - if row.kind in models.NotifyChannel.SMTP_KINDS: + if row.kind in models.NotifyChannel.HUB_KINDS: + detail, status_code, extra = _hub_send(db, row, channel, timeout, link=hub_link) + elif row.kind in models.NotifyChannel.SMTP_KINDS: detail = _smtp_send(config, row.target, row.title, text, timeout) status_code = 200 else: @@ -430,10 +1187,14 @@ def deliver(db: Session, row: models.NotifyDelivery, *, channel: models.NotifyCh row.ms = int((time.perf_counter() - started) * 1000) row.status = models.NotifyDelivery.STATUS_SUCCESS row.sent_at = datetime.now() - row.response = {"httpStatus": status_code, "detail": detail} + row.response = {"httpStatus": status_code, "detail": detail, **extra} row.last_error = "" channel.last_sent_at = datetime.now() channel.last_error = "" + except _Skipped as exc: + row.ms = int((time.perf_counter() - started) * 1000) + row.status = models.NotifyDelivery.STATUS_SKIPPED + row.last_error = str(exc)[:500] except _Fatal as exc: row.ms = int((time.perf_counter() - started) * 1000) row.status = models.NotifyDelivery.STATUS_DEAD @@ -479,7 +1240,98 @@ def _fail(db: Session, row: models.NotifyDelivery, message: str, *, retries: int return delay = BACKOFF_SECONDS[min(len(BACKOFF_SECONDS) - 1, max(0, row.attempts - 1))] row.status = models.NotifyDelivery.STATUS_FAILED - row.next_attempt_at = datetime.now() + timedelta(seconds=delay) + # 抹掉微秒再写库:DATETIME 列的秒级四舍五入会把"现在能发"抬成"一秒后才能发" + row.next_attempt_at = datetime.now().replace(microsecond=0) + timedelta(seconds=delay) + + +def hub_recheck(db: Session, row: models.NotifyDelivery) -> str: + """找 Hub 回查这一条的逐人投递结果,按对方口径改写本地状态,回一句给人看的话。 + + 这是文档 9.6 的第 3 件事。用得上的两个时刻:一是 ``rate_limited`` / 超时之后 + 不确定到底投没投出去,二是管理员想知道"这条卡片现在是什么下场"。回查只读、 + 可反复调(文档明说无副作用),所以界面上给一条记录配一个按钮不心疼。 + """ + if row.kind not in models.NotifyChannel.HUB_KINDS: + raise ValueError("只有走统一身份 Hub 的渠道才有投递明细可回查") + # 认记录里那个键,不重算:摘掉深链重发的那一条用的是 ``-nolink`` 变体, + # 重算出来的键在 Hub 那边根本没有推送记录 + hub = dict((row.response or {}).get("hub") or {}) + key = str(hub.get("msgKey") or "").strip() or hub_msg_key(row) + if not key: + raise ValueError("这条记录没有幂等键,回不了查(大概是换世代之前发出去的)") + data = hub_api.client().notify_wecom_status(key) + recipients = [item for item in (data.get("recipients") or []) if isinstance(item, dict)] + status = str(data.get("status") or "").strip().lower() + mine = None + want = str(row.target or "").strip() + for item in recipients: + if str(item.get("receiver") or "").strip() == want: + mine = item + break + if mine is None and len(recipients) == 1: + mine = recipients[0] + + hub.update({ + "msgKey": key, + "status": status or str(hub.get("status") or ""), + "attempt": data.get("attempt", hub.get("attempt")), + "sentAt": hub_time(data.get("sent_at")) or str(hub.get("sentAt") or ""), + "duplicate": bool(data.get("duplicate")), + "link": str(data.get("link") or hub.get("link") or ""), + "grant": str(data.get("grant") or hub.get("grant") or ""), + "recipients": recipients[:HUB_RECEIVER_MAX], + "recheckedAt": datetime.now().strftime("%Y-%m-%d %H:%M:%S"), + }) + if data.get("wecom_errmsg"): + hub["wecomErrmsg"] = str(data.get("wecom_errmsg")) + if data.get("wecom_errcode") is not None: + hub["wecomErrcode"] = data.get("wecom_errcode") + + if mine is not None: + outcome, message = hub_outcome(str(mine.get("status") or ""), str(mine.get("reason") or "")) + if outcome != models.NotifyDelivery.STATUS_SUCCESS: + message = f"{message}{hub_enterprise_hint(data)}" + hub["reason"] = str(mine.get("reason") or "") + hub["wecomUserId"] = str(mine.get("wecom_userid") or hub.get("wecomUserId") or "") + elif status in ("sent", "partial"): + outcome, message = models.NotifyDelivery.STATUS_SUCCESS, "" + else: + outcome, message = models.NotifyDelivery.STATUS_FAILED, \ + f"Hub 那边这一条还是没投出去:{_brief(str(data.get('wecom_errmsg') or '没回逐人结果'), 300)}" + + row.response = {"httpStatus": 200, "detail": _brief(json.dumps( + {k: v for k, v in hub.items() if k != "recipients"}, ensure_ascii=False), 380), "hub": hub} + if outcome == models.NotifyDelivery.STATUS_SUCCESS: + row.status = outcome + row.last_error = "" + if not row.sent_at: + row.sent_at = _parse_hub_time(str(hub.get("sentAt") or "")) or datetime.now() + return "Hub 确认这个人已经收到了" + if outcome == models.NotifyDelivery.STATUS_SKIPPED: + row.status = outcome + row.last_error = message + return message or "这个人收不到" + if outcome == models.NotifyDelivery.STATUS_DEAD: + row.status = outcome + row.last_error = message + return message + # 还是没投出去:留原状态,让调度按退避继续试 + row.last_error = message + return message or "Hub 那边还没投出去,稍后按退避继续重试" + + +def _parse_hub_time(value: str) -> datetime | None: + """Hub 回传的 ``sent_at`` 是 UTC 的 RFC3339,本地那几列存的是不带时区的本地时间。""" + text = hub_time(value) + if not text: + return None + try: + stamp = datetime.fromisoformat(text.replace("Z", "+00:00")) + except ValueError: + return None + if stamp.tzinfo is not None: + stamp = stamp.astimezone().replace(tzinfo=None) + return stamp def claim(db: Session, delivery_id: str) -> bool: @@ -551,8 +1403,14 @@ def run_due(db: Session, *, limit: int = BATCH_LIMIT) -> dict: """后台调度每轮调一次:先收尸,再认领,一条发一条;单条失败不带崩整轮。""" recover_stuck(db) sent = ok = dead = 0 + started = time.perf_counter() # 先抄下 id 再进循环:认领与投递各自 commit,过期对象摸一次属性就回读一次库 - for delivery_id in [row.id for row in due(db, limit=limit)]: + queued = [row.id for row in due(db, limit=limit)] + for index, delivery_id in enumerate(queued): + if index and time.perf_counter() - started > ROUND_BUDGET_SECONDS: + logger.info("消息渠道这一轮发满 %.0f 秒先收工,剩下 %d 条下一轮接着发", + ROUND_BUDGET_SECONDS, len(queued) - index) + break if not claim(db, delivery_id): continue # 别的进程已经认领了这条 fresh = db.get(models.NotifyDelivery, delivery_id) @@ -568,7 +1426,7 @@ def run_due(db: Session, *, limit: int = BATCH_LIMIT) -> dict: def resend(db: Session, delivery_id: str) -> models.NotifyDelivery | None: - """人工重发一条(补完邮箱之后点这个)。""" + """人工重发一条(补完邮箱、补完企微绑定之后点这个)。""" row = db.get(models.NotifyDelivery, delivery_id) if row is None: return None @@ -576,6 +1434,22 @@ def resend(db: Session, delivery_id: str) -> models.NotifyDelivery | None: row.attempts = 0 row.next_attempt_at = datetime.now() row.last_error = "" + if row.kind in models.NotifyChannel.HUB_KINDS: + # 收件人重认一次:这一次重发多半就是"同步之后 hub_user_id 补上了 / 停用被取消", + # 拿着旧的收件标识重发等于把同一个错误再犯一遍。 + person = db.get(models.User, int(row.person or 0) or 0) + if person is not None: + _receiver, target = hub_receiver(person) + if target: + row.target = target + # 已经投出去过的那一条(sent / partial)同键重发只会命中 Hub 的幂等缓存, + # 对方原样回一份旧明细、一个人也不会再收到——换个世代号才是真补发(文档 9.6.4)。 + hub = dict(row.response or {}).get("hub") or {} + if str(hub.get("status") or "").lower() in ("sent", "partial"): + response = dict(row.response or {}) + response["msgKeySeq"] = hub_key_seq(row) + 1 + response["hub"] = {**hub, "msgKey": "", "status": "queued"} + row.response = response if row.kind == models.NotifyChannel.KIND_EMAIL: person = db.get(models.User, int(row.person or 0) or 0) if person is not None: @@ -583,5 +1457,7 @@ def resend(db: Session, delivery_id: str) -> models.NotifyDelivery | None: if not row.target: row.status = models.NotifyDelivery.STATUS_SKIPPED row.last_error = "这个账号还是没有邮箱" + # 人点「重发」就是现在想看结果:别让他再等一个轮询周期(写回那边同此口径) + wake_signal.mark(db) db.commit() return row diff --git a/backend/app/service/detail_export.py b/backend/app/service/detail_export.py new file mode 100644 index 0000000..780d93a --- /dev/null +++ b/backend/app/service/detail_export.py @@ -0,0 +1,1202 @@ +"""流程明细导出:筛选口径、未操作者、按流程分表的表头与文件组装。 + +设计稿见 ``docs/process-detail-export-design.md``,这一层是它的落地。三件事值得先看一眼: + +1. **取数不自己写查询**。走 ``api/runtime.py`` 里流程监控那一份 ``_admin_work_page`` + (延迟导入:service 层在运行时才回来取 api 层那份共用条件)。同一套条件写两遍迟早 + 漂开,漂开的结果是监控页上看得见的单导不出来。 +2. **未操作者有五类来源**(设计稿 §4):待办没办、待阅没打开、抄送需处理没回复、 + 终止时被强行收尾、前置加签还没激活。只盯着 ``oa_task`` 会漏掉「单子办完了但有人 + 压根没看过」这一整类审计现场——单据归档时没打开过的待阅**不搬进已阅档**,行留在 + ``oa_read`` 只打个 ``completed`` 标记(见 ``engine._finish_work``)。 +3. **值渲染与列表导出同源**:都走 :func:`app.service.exportfmt.cell_text`,同一个字段 + 在两张导出表里必须长一个样。 +""" + +from __future__ import annotations + +import csv +import io +import re +from dataclasses import dataclass, field, replace +from dataclasses import field as dc_field # 列定义里那一格就叫 ``field``,类体内会遮住同名函数 +from datetime import datetime +from typing import Any, Callable, Iterable + +from sqlalchemy import String, and_, func, literal, or_, select +from sqlalchemy.orm import Session + +from .. import dbconfig, models +from ..envelope import bad_request +from . import dicts as dicts_service +from . import exportfmt +from . import formruntime +from . import node_approve +from . import org +from . import personref + +# --------------------------------------------------------------------------- +# 上限与目录常量 +# --------------------------------------------------------------------------- + +#: 一次最多勾几条流程。每条流程一个 sheet、一次 count,勾得没边是把导出当列表页逛。 +MAX_PROCESSES = 30 +#: 「附一张汇总表」的默认关法(界面上是个勾,默认不给) +SUMMARY_SHEET_NAME = "汇总" +SUMMARY_COLUMNS = ( + "base.process_name", "base.serial", "base.title", "base.status", "base.creator_person", + "base.creator_unit_name", "base.start_time", "base.finish_time", "base.unoperators", +) +#: 勾选环节的动态列最多摊几环,超出在表尾留一句人话 +MAX_ACTIVITY_COLUMNS = 12 +#: 环节动态列的三段 +ACTIVITY_PARTS = (("handler", "处理人"), ("time", "完成时间"), ("opinion", "意见")) + +LAYOUT_PER_PROCESS = "perProcess" +LAYOUT_MERGED = "merged" +LAYOUTS = (LAYOUT_PER_PROCESS, LAYOUT_MERGED) + +FORMAT_XLSX = "xlsx" +FORMAT_CSV = "csv" + + +def max_columns() -> int: + """单张表最多多少列(运行配置)。""" + try: + return max(1, int(dbconfig.value("export_detail_max_columns", 120) or 120)) + except (TypeError, ValueError): + return 120 + + +def max_rows() -> int: + """一次导出的行数上限(运行配置,改完即生效)。""" + try: + return max(1, int(dbconfig.value("export_detail_max_rows", 50000) or 50000)) + except (TypeError, ValueError): + return 50000 + + +# --------------------------------------------------------------------------- +# 固有列 / 未操作者列 +# --------------------------------------------------------------------------- + +#: 单据固有列。``id`` 前缀 ``base.``,与表单字段(``form.``)分开,撞不了名。 +BASE_COLUMNS: tuple[tuple[str, str], ...] = ( + ("base.serial", "单号"), + ("base.title", "标题"), + ("base.process_name", "流程"), + ("base.category_name", "分类"), + ("base.status", "状态"), + ("base.creator_person", "发起人"), + ("base.creator_unit_name", "发起部门"), + ("base.start_time", "创建日期"), + ("base.finish_time", "归档日期"), + ("base.duration", "耗时"), + ("base.current_activity_names", "当前环节"), + ("base.manual_identity_text", "当前处理人"), + ("base.result", "结果"), + ("base.result_opinion", "结论意见"), + ("base.parent_job", "父单号"), +) + +#: 未操作者那一组(口径见 :func:`unoperators`)。 +UNOPERATOR_COLUMNS: tuple[tuple[str, str], ...] = ( + ("base.unoperators", "未操作者"), + ("base.unoperator_count", "未操作条数"), + ("base.unoperator_kinds", "未操作类型"), + ("base.unoperator_wait", "最长等待"), + ("base.unoperator_expired", "超时候办数"), + ("base.halt_type", "停等类型"), +) + +COLUMN_LABELS: dict[str, str] = {**dict(BASE_COLUMNS), **dict(UNOPERATOR_COLUMNS)} + +#: 进页面就带上的常用列:一张能直接导的表,不用从空表开始。 +DEFAULT_COLUMNS: tuple[str, ...] = ( + "base.serial", "base.title", "base.process_name", "base.status", "base.creator_person", + "base.creator_unit_name", "base.start_time", "base.finish_time", + "base.current_activity_names", "base.unoperators", "base.unoperator_kinds", + "base.unoperator_wait", +) + +#: 归档之后的 ``result`` 取值念成一句人话(``engine._finish_work`` 写的就是这三个词)。 +RESULT_LABELS = {"agree": "办结同意", "terminated": "已终止", "canceled": "已作废"} + + +# --------------------------------------------------------------------------- +# 未操作者:五类来源 +# --------------------------------------------------------------------------- + +KIND_TASK = "task" # 待办未处理 +KIND_READ_PLAIN = "readPlain" # 待阅未打开 +KIND_READ_ACTION = "readAction" # 抄送需处理,未回复处理意见 +KIND_TERMINATE = "terminate" # 终止那一刻被强行收尾,本人没表过态 +KIND_ADD_PENDING = "addPending" # 前置加签还没激活(默认不算) + +#: 默认四类。``addPending`` 与本人待办列表、监控待办的口径一致:还没真正到人手上。 +DEFAULT_KINDS: tuple[str, ...] = (KIND_TASK, KIND_READ_PLAIN, KIND_READ_ACTION, KIND_TERMINATE) +ALL_KINDS: tuple[str, ...] = DEFAULT_KINDS + (KIND_ADD_PENDING,) + +KIND_LABELS = { + KIND_TASK: "待办未处理", + KIND_READ_PLAIN: "待阅未打开", + KIND_READ_ACTION: "抄送需处理未回复", + KIND_TERMINATE: "终止时未表态", + KIND_ADD_PENDING: "加签未激活", +} + +#: 转办 / 管理员改派留下的待办 ``label``(见 ``engine.transfer``),用来把两种 +#: ``empower_from_identity`` 分开:加签与代理派下去的行 ``label`` 不是这两个词。 +TRANSFER_LABELS = {"转办", "管理员改派"} + +# 停等类型:把「没结果」的三种含义分开,别让人把空格读成"都办完了" +HALT_ACTIVE = "有人未操作" +HALT_AUTO = "无人待处理(自动/汇聚/延时)" +HALT_PAUSED = "挂起中" +HALT_DONE = "已归档" +HALT_WAIT = "暂无待办" + + +@dataclass +class Unop: + """一张单据的未操作者明细。""" + + rows: list[dict] = field(default_factory=list) + + @property + def persons(self) -> list[str]: + seen: list[str] = [] + for row in self.rows: + name = str(row.get("name") or row.get("person") or "") + if name and name not in seen: + seen.append(name) + return seen + + @property + def kinds(self) -> list[str]: + seen: list[str] = [] + for row in self.rows: + label = KIND_LABELS.get(str(row.get("kind") or ""), "") + if label and label not in seen: + seen.append(label) + return seen + + @property + def wait_seconds(self) -> int: + starts = [row.get("since") for row in self.rows if isinstance(row.get("since"), datetime)] + if not starts: + return 0 + return max(0, int((datetime.now() - min(starts)).total_seconds())) + + @property + def expired(self) -> int: + return sum(1 for row in self.rows if row.get("expired")) + + def text(self, column_id: str, halt: str) -> str: + if column_id == "base.unoperators": + return "、".join(self.persons) + if column_id == "base.unoperator_count": + return str(len(self.rows)) + if column_id == "base.unoperator_kinds": + return "、".join(self.kinds) + if column_id == "base.unoperator_wait": + return exportfmt.duration_text(self.wait_seconds) + if column_id == "base.unoperator_expired": + return str(self.expired) + if column_id == "base.halt_type": + return halt + return "" + + +def _task_kind(row: models.Task) -> str: + return KIND_ADD_PENDING if str(row.add_task_from or "") == "before_pending" else KIND_TASK + + +def _task_source(row: models.Task, names: dict[str, str]) -> str: + """这条待办是怎么到这位手上的:本人 / 转办自 X / 代理自 X。 + + ``empower_from_identity`` 同时装转办与委托代理两种来路,分开靠 ``label``—— + ``engine.transfer`` 写的就是「转办」/「管理员改派」,代理派单(``org.apply_agents``) + 不换 label。认不出来就报「他人委托」,不硬猜。姓名由调用方一次批量翻好传进来 + (:func:`org.display_names`):库里存的是账号,逐行去问库会在五万行上问五万次。 + """ + from_ref = str(getattr(row, "empower_from_identity", "") or "") + if not from_ref: + return "本人" + name = names.get(from_ref) or from_ref + if str(getattr(row, "label", "") or "") in TRANSFER_LABELS: + return f"转办自 {name}" + return f"代理自 {name}" + + +def unoperators( + db: Session, jobs: list[str], kinds: Iterable[str] = DEFAULT_KINDS, + locked_pairs: Iterable[tuple[str, str]] = (), +) -> dict[str, Unop]: + """一批单据的未操作者。三张表各一次查询,按 ``job`` 分组,不逐行问库。""" + wanted = {str(kind) for kind in kinds} & set(ALL_KINDS) + out: dict[str, Unop] = {str(job): Unop() for job in jobs} + if not jobs or not wanted: + return out + locked = {tuple(pair) for pair in locked_pairs} + + if {KIND_TASK, KIND_ADD_PENDING} & wanted: + tasks = list(db.execute(select(models.Task).where(models.Task.job.in_(jobs))).scalars().all()) + names = org.display_names( + db, [str(row.empower_from_identity or "") for row in tasks if row.empower_from_identity]) + for row in tasks: + kind = _task_kind(row) + if kind not in wanted: + continue + if kind == KIND_TASK and (str(row.process or ""), str(row.activity or "")) in locked: + # 这一环的按钮锁在第三方系统里(openApprove + oaLock),不是这位不办 + continue + out.setdefault(str(row.job), Unop()).rows.append({ + "person": str(row.identity or ""), + "name": str(row.identity_name or ""), + "kind": kind, + "activity": str(row.activity_name or ""), + "since": row.start_time, + "expired": bool(row.expired), + "source": _task_source(row, names), + }) + + if {KIND_READ_PLAIN, KIND_READ_ACTION} & wanted: + for row in db.execute(select(models.Read).where(models.Read.job.in_(jobs))).scalars().all(): + requires = bool(row.requires_action) + kind = KIND_READ_ACTION if requires else KIND_READ_PLAIN + if kind not in wanted: + continue + if requires: + if row.handle_time: + continue # 填了处理意见才算完,光打开过不算 + elif row.view_time: + continue # 普通抄送:打开过就算看过(打开单据页会顺带登记,见 mark_reads_for_work) + out.setdefault(str(row.job), Unop()).rows.append({ + "person": str(row.identity or ""), + "name": str(row.identity_name or ""), + "kind": kind, + "activity": str(row.activity_name or row.current_activity_name or ""), + "since": row.start_time, + "expired": False, + "source": "抄送", + }) + + if KIND_TERMINATE in wanted: + rows = db.execute( + select(models.TaskCompleted).where( + models.TaskCompleted.job.in_(jobs), + models.TaskCompleted.processing_type == "terminate", + ) + ).scalars().all() + for row in rows: + out.setdefault(str(row.job), Unop()).rows.append({ + "person": str(row.identity or ""), + "name": str(row.identity_name or ""), + "kind": KIND_TERMINATE, + "activity": str(row.activity_name or ""), + "since": row.start_time or row.completed_time, + "expired": bool(row.expired), + "source": f"终止人 {row.operator_name}" if row.operator_name else "终止收尾", + }) + + for item in out.values(): + item.rows.sort(key=lambda row: (str(row.get("person") or ""), row.get("since") or datetime.min)) + return out + + +def halt_type(row, unop: Unop) -> str: + """这张单现在到底在等谁。空白的三种含义必须分开摆(设计稿 §4)。""" + if str(getattr(row, "status", "") or "") != "running": + return HALT_DONE + if bool(getattr(row, "paused", False)): + reason = str(getattr(row, "pause_reason", "") or "").strip() + return f"{HALT_PAUSED}({reason})" if reason else HALT_PAUSED + if unop.rows: + return HALT_ACTIVE + # 人工环节之外的停留:自动 / 脚本 / 汇聚 / 延时,压根没发待办 + if str(getattr(row, "activity_type", "") or "") in ("", "manual"): + return HALT_WAIT + return HALT_AUTO + + +# --------------------------------------------------------------------------- +# 筛选条件 +# --------------------------------------------------------------------------- + + +@dataclass +class UnoperatorFilter: + mode: str = "any" # any=包含任一 / all=包含全部 / not=不包含 + persons: list[str] = field(default_factory=list) + kinds: list[str] = field(default_factory=lambda: list(DEFAULT_KINDS)) + include_principal: bool = False # 也算委托方(转办/代理的来路那一头) + exclude_locked: bool = False # 排除按钮锁在第三方的环节 + + +@dataclass +class Filters: + """界面上那七个筛选项(外加关键字、超时)。""" + + keyword: str = "" + processes: list[str] = field(default_factory=list) + creator_mode: str = "" # "" / person / unit / keyword + creators: list[str] = field(default_factory=list) + creator_unit_ids: list[str] = field(default_factory=list) + creator_unit_sub: bool = True + creator_keyword: str = "" + create_start: str = "" + create_end: str = "" + archive_start: str = "" + archive_end: str = "" + statuses: list[str] = field(default_factory=list) + paused: str = "" + expired: str = "" + unoperator: UnoperatorFilter = field(default_factory=UnoperatorFilter) + project_name: str = "" + project_code: str = "" + project_op: str = "eq" # eq / contains + + @classmethod + def from_body(cls, payload: dict | None) -> "Filters": + data = dict(payload or {}) + nested = data.pop("unoperator", None) + filters = cls(**{key: value for key, value in data.items() if key in cls.__dataclass_fields__}) + if isinstance(nested, dict): + known = {key: value for key, value in nested.items() + if key in UnoperatorFilter.__dataclass_fields__} + # 界面没勾就是没表态,交给出厂那四类;显式给了清单才按清单来 + if known.get("kinds") is None: + known.pop("kinds", None) + filters.unoperator = UnoperatorFilter(**known) + filters.processes = [str(item) for item in filters.processes if str(item or "").strip()] + filters.statuses = [str(item) for item in filters.statuses if str(item or "").strip()] + filters.unoperator.kinds = [ + str(item) for item in (filters.unoperator.kinds or DEFAULT_KINDS) + if str(item or "").strip() in ALL_KINDS + ] or list(DEFAULT_KINDS) + return filters + + @property + def has_project(self) -> bool: + return bool(self.project_name.strip() or self.project_code.strip()) + + @property + def has_archive(self) -> bool: + return bool(self.archive_start.strip() or self.archive_end.strip()) + + +def _refs(db: Session, values: Iterable[str]) -> list[str]: + """选人框给的值归一成账号;认不出来原样留着(与 ``_admin_task_stmt`` 同口径)。""" + out: list[str] = [] + for value in values or (): + text = str(value or "").strip() + if not text: + continue + account = personref.account_of(db, text) or text + if account not in out: + out.append(account) + return out + + +def creator_whitelist(db: Session, filters: Filters) -> list[str] | None: + """创建人白名单(账号);``None`` = 这一条不限。 + + 「属于部门」先展开部门再换成人员清单,**不用 LIKE 前缀**:部门一改名,历史单据列里 + 还是旧路径,前缀匹配会把人自己的单子筛没——这是 ``permissions.scope_person_refs`` + 从 DN 换成账号时踩过的同一个坑。 + """ + # 什么都没挑就是不限,不是"谁都不要":空清单在 SQL 里是恒假条件, + # 那样一来「不填创建人」会连带整个查询一条都不出,是最难查的一种错。 + mode = filters.creator_mode or ("unit" if filters.creator_unit_ids + else "keyword" if filters.creator_keyword.strip() + else "person") + if mode == "unit": + if not filters.creator_unit_ids: + return None + units: list[int] = [] + for value in filters.creator_unit_ids: + unit_id = models.as_id(value) + if unit_id is None or unit_id in units: + continue + if filters.creator_unit_sub: + units.extend(uid for uid in org.descendant_unit_ids(db, unit_id) if uid not in units) + else: + units.append(unit_id) + # scope 已经展开完了,identities_for_unit 不能再含下级 + return org.identities_for_unit(db, units, contains_sub=False) if units else [] + if mode == "keyword": + return None + refs = _refs(db, filters.creators) + return refs or None + + +def detect_project_field(fields: list[dict]) -> dict | None: + """这条流程的「相关核算项目」是哪一格。 + + 现网实况:费用报销单上这一格是 ``accountProject``,``select``,字典 ``pms_project``, + **库里存编码、界面上念名称**(见 ``docs/expense-thirdparty-field-update.md``)。 + 先按 key 认,认不到再按 label 命中「相关核算项目」——换一张重新设计的表单 key 就变了, + 只认 key 会筛出一张空表还不吭声。 + """ + field = next((item for item in fields if str(item.get("key") or "") == "accountProject"), None) + if field is None: + field = next( + (item for item in fields + if str(item.get("label") or "").strip() == "相关核算项目" + and str(item.get("type") or "") in ("select", "radio", "picker", "relation")), + None, + ) + if field is None: + return None + return { + "key": str(field.get("key") or ""), + "label": str(field.get("label") or ""), + "dictCode": str(field.get("dictCode") or "") + if dicts_service.source_kind_of(field) == dicts_service.SOURCE_DICT else "", + "multiple": bool(field.get("multiple")), + } + + +def project_targets(db: Session, processes: list[str]) -> dict[str, dict]: + return { + process_id: target + for process_id in processes + if (target := detect_project_field(form_fields_of(db, process_id))) is not None + } + + +def project_candidates(db: Session, targets: dict[str, dict], value: str, *, by_label: bool, + op: str) -> list[str]: + """筛选值 → 这格里可能存下来的那些值。 + + 按名称筛时先拿字典把名称翻成编码,**同时把名称本身也留在候选里**:历史上有人直接 + 往这格写过名称,只比编码会漏。按编码筛时反过来把编码对应的名称也带上,同一个道理。 + """ + text = str(value or "").strip() + if not text: + return [] + candidates: list[str] = [text] + codes: dict[str, list[str]] = {} + for target in targets.values(): + code = str(target.get("dictCode") or "") + if not code or code in codes: + continue + try: + codes[code] = dicts_service.items_of(db, code) + except Exception: # noqa: BLE001 - 字典被删/读不动时按"翻不出编码"处理,不拦导出 + codes[code] = [] + for items in codes.values(): + for item in items: + label = str(item.get("label") or "") + item_value = str(item.get("value") or "") + hit = (label == text) if op != "contains" else (text in label) + if by_label and hit and item_value and item_value not in candidates: + candidates.append(item_value) + if not by_label and item_value == text and label and label not in candidates: + candidates.append(label) + return candidates + + +def _json_value(column, key: str): + """``data`` 里那一格的文本形式。写法照 ``service/quota_source.py``,不发明新招式。""" + extracted = func.json_unquote(func.json_extract(column, f"$.{key}")) + return func.cast(extracted, String) + + +def _json_match(model, key: str, candidates: list[str], multiple: bool): + if not candidates: + return literal(False) + one = _json_value(model.data, key).in_(candidates) + if not multiple: + return one + # 多选那类存的是数组:JSON_CONTAINS(target, candidate, path) 逐个候选问一遍 + checks = [func.json_contains(func.coalesce(func.json_extract(model.data, f"$.{key}"), "[]"), + func.json_quote(item)) for item in candidates] + return or_(one, *checks) if checks else one + + +def locked_pairs_for(db: Session, processes: list[str]) -> list[tuple[str, str]]: + """所选流程里被「外部表态 + OA 锁」锁住的那些环节。""" + if not processes: + return [] + pairs = [(str(row[0]), str(row[1])) for row in db.execute( + select(models.Activity.process, models.Activity.id).where(models.Activity.process.in_(processes)) + ).all()] + if not pairs: + return [] + flags = node_approve.lock_flags(db, pairs) + return [pair for pair, view in flags.items() if bool((view or {}).get("locked"))] + + +def extra_factory(db: Session, filters: Filters) -> Callable[[Any], Any] | None: + """把创建人关键字、未操作者、相关核算项目折成一个按表关联的条件构造函数。 + + 返回的是 ``model -> 条件``:未操作者那几路 ``EXISTS`` 要按 ``job`` 关联到本行, + 在途表与归档表得各关联一遍(写成 ``job IN (子查询)`` 再取反会被 SQLAlchemy 铺成 + 笛卡尔积,``_monitor_work_part`` 里「超时」那条已经栽过)。 + """ + refs = _refs(db, filters.unoperator.persons) + kinds = {str(kind) for kind in filters.unoperator.kinds} & set(ALL_KINDS) + mode = filters.unoperator.mode if filters.unoperator.mode in ("any", "all", "not") else "any" + include_principal = filters.unoperator.include_principal + exclude_locked = filters.unoperator.exclude_locked + locked = locked_pairs_for(db, filters.processes) if exclude_locked else [] + creator_keyword = filters.creator_keyword.strip() if filters.creator_mode == "keyword" else "" + targets = project_targets(db, filters.processes) if filters.has_project else {} + + def one_person_exists(model, ref: str): + parts = [] + if {KIND_TASK, KIND_ADD_PENDING} & kinds: + cond = [models.Task.job == model.job, models.Task.identity == ref] + if KIND_ADD_PENDING not in kinds: + cond.append(models.Task.add_task_from != "before_pending") + if KIND_TASK not in kinds: + cond.append(models.Task.add_task_from == "before_pending") + if include_principal: + cond.append(or_(models.Task.identity == ref, models.Task.empower_from_identity == ref)) + if locked: + for pair_process, pair_activity in locked: + cond.append(~and_(models.Task.process == pair_process, models.Task.activity == pair_activity)) + parts.append(select(models.Task.id).where(*cond).exists()) + if {KIND_READ_PLAIN, KIND_READ_ACTION} & kinds: + branch = [] + if KIND_READ_PLAIN in kinds: + branch.append(and_(models.Read.requires_action.is_(False), models.Read.view_time.is_(None))) + if KIND_READ_ACTION in kinds: + branch.append(and_(models.Read.requires_action.is_(True), models.Read.handle_time.is_(None))) + parts.append(select(models.Read.id).where( + models.Read.job == model.job, models.Read.identity == ref, or_(*branch)).exists()) + if KIND_TERMINATE in kinds: + parts.append(select(models.TaskCompleted.id).where( + models.TaskCompleted.job == model.job, + models.TaskCompleted.identity == ref, + models.TaskCompleted.processing_type == "terminate").exists()) + return or_(*parts) if parts else literal(False) + + def unoperator_clause(model): + if not refs: + return None + per_person = [one_person_exists(model, ref) for ref in refs] + if mode == "all": + return and_(*per_person) + if mode == "not": + return ~or_(*per_person) + return or_(*per_person) + + def project_clause(model): + if not targets: + return None + branches = [] + for process_id, target in targets.items(): + if process_id not in filters.processes: + continue + values: list[str] = [] + for value, by_label in ((filters.project_code.strip(), False), (filters.project_name.strip(), True)): + if not value: + continue + candidates = project_candidates( + db, {process_id: target}, value, by_label=by_label, + op="contains" if filters.project_op == "contains" else "eq") + values = [item for item in dict.fromkeys([*values, *candidates])] + branches.append(and_( + model.process == process_id, + _json_match(model, str(target.get("key") or ""), values, bool(target.get("multiple"))))) + return or_(*branches) if branches else literal(False) + + def build(model) -> Any: + clauses = [] + if creator_keyword: + like = f"%{creator_keyword}%" + clauses.append(or_(model.creator_person.like(like), model.creator_identity.like(like))) + for clause in (unoperator_clause(model), project_clause(model)): + if clause is not None: + clauses.append(clause) + return and_(*clauses) if clauses else None + + if filters.has_project and not targets: + raise bad_request("所选流程里没有「相关核算项目」这一格,请去掉这个筛选条件或换流程") + if not (refs or creator_keyword or targets): + return None + return build + + +def status_filter(filters: Filters) -> tuple[str, str]: + """流程状态多选 → 现成的 ``status`` / ``paused`` 两个参数。 + + 界面上「已挂起」与四个状态并列摆着,但挂起不是流程状态、是运行中的冻住标记 + (见 :mod:`app.api.runtime`),所以拆回 ``paused=1``。 + """ + statuses = [item for item in filters.statuses if item != "paused"] + paused = filters.paused + if "paused" in filters.statuses: + paused = "1" + return ",".join(statuses), paused + + +def query_page( + db: Session, user, filters: Filters, *, limit: int, offset: int = 0, with_data: bool = True, + processes: list[str] | None = None, +): + """走流程监控那一份共用条件取一页单据。""" + from ..api.runtime import _admin_work_page, _parse_date # 延迟导入:service 不反向压住 api 层 + + statuses, paused = status_filter(filters) + return _admin_work_page( + db, user, + keyword=filters.keyword, status=statuses, + start_date=filters.create_start, end_date=filters.create_end, + expired=filters.expired, paused=paused, + offset=offset, limit=limit, with_data=with_data, + processes=processes or filters.processes or None, + creator_refs=creator_whitelist(db, filters), + archive_start=_parse_date(filters.archive_start) if filters.archive_start.strip() else None, + archive_end=_parse_date(filters.archive_end, add_day=True) if filters.archive_end.strip() else None, + extra=extra_factory(db, filters), + ) + + +def counts_by_process(db: Session, user, filters: Filters) -> dict[str, int]: + """每条流程各多少行。导出前先知道多大,比导完发现被截断好。""" + out: dict[str, int] = {} + for process_id in filters.processes: + _, total = query_page(db, user, filters, limit=1, processes=[process_id], with_data=False) + out[process_id] = total + return out + + +# --------------------------------------------------------------------------- +# 列目录 +# --------------------------------------------------------------------------- + +_form_cache: dict[str, list[dict]] = {} + + +def _form_fields(db: Session, form_id: str) -> list[dict]: + key = str(form_id or "") + if not key: + return [] + if key not in _form_cache: + row = db.get(models.FormElement, key) + _form_cache[key] = formruntime.fields_of(row.content if row else {}) + return _form_cache[key] + + +def form_fields_of(db: Session, process_id: str) -> list[dict]: + """这条流程用过的所有表单的字段并集。 + + 一条流程常常发起一张表、审批换一张表(``Activity.form``),只读 ``latest_form`` + 会把审批环节改过的那几格漏掉。同 key 只留第一次出现的那份定义。 + """ + _form_cache.clear() # 每次按流程取字段都清一遍:表单被人改过,导出不能拿旧缓存 + process = db.get(models.Process, process_id) + if process is None: + return [] + form_ids: list[str] = [] + for form_id in [process.latest_form, *quick_forms(process)]: + if form_id and form_id not in form_ids: + form_ids.append(form_id) + for form_id in db.execute( + select(models.Activity.form).where(models.Activity.process == process_id).distinct() + ).scalars().all(): + if form_id and form_id not in form_ids: + form_ids.append(form_id) + out: list[dict] = [] + seen: set[str] = set() + for form_id in form_ids: + for item in _form_fields(db, form_id): + key = str(item.get("key") or "") + if not key or key in seen: + continue + seen.add(key) + out.append(item) + return out + + +def quick_forms(process: models.Process) -> list[str]: + """``quick_forms`` 那几张贴在流程上的表单(本平台未启用时是空清单)。""" + rows = getattr(process, "quick_forms", None) or [] + return [str(item) for item in rows if isinstance(item, str) and item.strip()] + + +def field_columns(fields: list[dict]) -> list[dict]: + """表单字段 → 可导出的列。明细表摊成子列,版面格标灰(没值,导出来是空列)。""" + out: list[dict] = [] + for item in fields: + key = str(item.get("key") or "") + if not key: + continue + kind = str(item.get("type") or "") + out.append({ + "id": f"form.{key}", + "label": str(item.get("label") or key), + "type": kind, + "fillable": formruntime.fillable(item), + "layoutOnly": kind in formruntime.NON_INPUT_TYPES, + }) + if kind == "table": + for column in formruntime.columns_of(item): + child = str(column.get("key") or "") + if not child: + continue + out.append({ + "id": f"table.{key}.{child}", + "label": f"{item.get('label') or key}·{column.get('label') or child}", + "type": str(column.get("type") or ""), + "fillable": True, + "layoutOnly": False, + }) + return out + + +@dataclass(frozen=True) +class ColumnSpec: + """一列。``kind`` 决定取值走哪条路。 + + ``field`` 是表单字段的定义:``build_columns`` 只填 key 与 label,真正那份要等 + :func:`filter_specs_for_process` 按流程取到该流程的表单定义才换进来——同名的格子在 + 不同流程里类型未必一样,渲染时拿错定义就会念错话。 + """ + + id: str + label: str + kind: str # base / unoperator / form / table / activity + field: dict = dc_field(default_factory=dict) + activity: dict = dc_field(default_factory=dict) + part: str = "" + only: tuple[str, ...] = () + + def applies_to(self, process_id: str) -> bool: + return not self.only or process_id in self.only + + +def build_columns( + db: Session, processes: list[str], ids: list[str], + only: dict[str, list[str]] | None = None, activity_ids: list[str] | None = None, +) -> list[ColumnSpec]: + """把前端给的列 id 清单落成列定义(按目录顺序,不按勾选顺序)。""" + only_map = {str(key): tuple(value or ()) for key, value in (only or {}).items()} + wanted = [str(item) for item in ids if str(item or "").strip()] + specs: list[ColumnSpec] = [] + for column_id in BASE_COLUMNS: + if column_id[0] in wanted: + specs.append(ColumnSpec(column_id[0], column_id[1], "base")) + for column_id in UNOPERATOR_COLUMNS: + if column_id[0] in wanted: + specs.append(ColumnSpec(column_id[0], column_id[1], "unoperator")) + # 表单列:按"首次出现在任一流程目录里的顺序"排,同一 key 只一列 + order: list[str] = [] + definitions: dict[str, dict] = {} + for process_id in processes: + for item in field_columns(form_fields_of(db, process_id)): + if item["id"] in wanted and item["id"] not in definitions: + order.append(item["id"]) + definitions[item["id"]] = item + for column_id in order: + item = definitions[column_id] + if column_id.startswith("table."): + _, parent_key, child_key = column_id.split(".", 2) + field = {"key": parent_key, "child": child_key, "type": item.get("type")} + specs.append(ColumnSpec(column_id, item["label"], "table", field, + only=only_map.get(column_id, ()))) + else: + key = column_id.split(".", 1)[1] + field = next((row for row in form_fields_of(db, processes[0]) if str(row.get("key") or "") == key), + {"key": key, "label": item["label"]}) + specs.append(ColumnSpec(column_id, item["label"], "form", field, + only=only_map.get(column_id, ()))) + for activity in activity_columns(db, processes, activity_ids or []): + for part, suffix in ACTIVITY_PARTS: + specs.append(ColumnSpec( + f"activity.{activity.get('id')}.{part}", + f"{activity.get('name')}.{suffix}", "activity", activity=activity, part=part)) + # 界面交不出认不出的列 id(清单本来就是目录给的),会交出来的只有手拼报文的人, + # 以及字段被改过之后存下来的老方案。勾了一整批表单字段却一个都没落上,说明这份报文 + # 跟这些流程根本对不上——悄悄出一张只有固有列的表,人只会以为数据丢了。 + requested = [item for item in wanted if item.startswith(("form.", "table."))] + if requested and not any(spec.kind in ("form", "table") for spec in specs): + raise bad_request("这些列在所选流程里都不存在: " + ", ".join(requested[:5])) + return specs + + +def activity_columns(db: Session, processes: list[str], activity_ids: list[str]) -> list[dict]: + """勾选的环节动态列:按环节 ``order_number`` 排,最多 :data:`MAX_ACTIVITY_COLUMNS` 个。""" + if not activity_ids or not processes: + return [] + rows = db.execute( + select(models.Activity).where( + models.Activity.process.in_(processes), models.Activity.id.in_(activity_ids)) + ).scalars().all() + picked = sorted(rows, key=lambda row: (str(row.process or ""), int(row.order_number or 0), str(row.id))) + return [{"id": str(row.id), "name": str(row.name or ""), "process": str(row.process or "")} + for row in picked][:MAX_ACTIVITY_COLUMNS] + + +def filter_specs_for_process(db: Session, specs: list[ColumnSpec], process_id: str) -> list[ColumnSpec]: + """按这条流程实际有的列过滤。 + + 同一 key 在几条流程里都有,界面上是一个勾;分 sheet 时每条流程各留自己那一列, + 没这一格的流程**不出现这一列**——留一列空的会让人以为数据丢了。 + """ + by_key = {str(item.get("key") or ""): item for item in form_fields_of(db, process_id)} + out: list[ColumnSpec] = [] + for spec in specs: + if spec.kind in ("base", "unoperator", "activity"): + out.append(spec) + continue + if not spec.applies_to(process_id): + continue + key = str(spec.field.get("key") or "") + definition = by_key.get(key) + if definition is None: + continue # 这条流程没这一格:它自己那张表里就不出现这一列 + if spec.kind == "table": + children = {str(item.get("key") or "") for item in formruntime.columns_of(definition)} + if str(spec.field.get("child") or "") not in children: + continue + out.append(replace(spec, field=definition)) + return out + + +# --------------------------------------------------------------------------- +# 落表 +# --------------------------------------------------------------------------- + + +@dataclass +class Sheet: + name: str + headers: list[str] + lines: list[list[str]] + + +def _text(row, spec: ColumnSpec, cache: dicts_service.DictCache, jobs: dict[str, str], + unop: Unop, halt: str) -> str: + if spec.kind in ("base", "unoperator"): + if spec.kind == "unoperator": + return unop.text(spec.id, halt) + return _base_text(row, spec.id, halt) + data = dict(getattr(row, "data", None) or {}) + if spec.kind == "form": + return exportfmt.cell_text(spec.field, data.get(str(spec.field.get("key") or "")), cache, jobs) + if spec.kind == "table": + return _table_child_text(spec, data.get(str(spec.field.get("key") or "")), cache, jobs) + return _activity_text(row, spec) + + +def _table_child_text(spec: ColumnSpec, value: object, cache: dicts_service.DictCache, + jobs: dict[str, str]) -> str: + """明细表里某一列摊成一格:把每一行的那一列取出来渲染,再用「、」串起来。 + + 不去解析 :func:`exportfmt.cell_text` 已经压好的那串文本——那格式是给人看的, + 拿 ``;`` 和 ``|`` 去拆,碰上单元格里本来就带这两个符号就散了。 + """ + child = str(spec.field.get("child") or "") + parts: list[str] = [] + for column in formruntime.columns_of(spec.field): + if str(column.get("key") or "") != child: + continue + for row in formruntime.rows_of(value): + text = exportfmt.cell_text(column, row.get(child), cache, jobs) + if text: + parts.append(text) + return "、".join(parts) + + +def _base_text(row, column_id: str, halt: str) -> str: + key = column_id.split(".", 1)[1] + if key == "status": + return exportfmt.status_label(getattr(row, "status", ""), bool(getattr(row, "paused", False))) + if key in ("start_time", "finish_time"): + return exportfmt.dt(getattr(row, key, None)) + if key == "duration": + seconds = int(getattr(row, "duration", 0) or 0) + if not seconds and str(getattr(row, "status", "") or "") == "running": + started = getattr(row, "start_time", None) + seconds = int((datetime.now() - started).total_seconds()) if started else 0 + return exportfmt.duration_text(seconds) + if key == "result": + return RESULT_LABELS.get(str(getattr(row, "result", "") or ""), str(getattr(row, "result", "") or "")) + return str(getattr(row, key, "") or "") + + +def _activity_text(row, spec: ColumnSpec) -> str: + record = (getattr(row, "_activities", None) or {}).get(str(spec.activity.get("id") or "")) + if not record: + return "" + if spec.part == "handler": + return str(record.get("name") or "") + if spec.part == "time": + return exportfmt.dt(record.get("time")) + return str(record.get("opinion") or "") + + +def _load_activities(db: Session, rows: list, specs: list[ColumnSpec]) -> None: + """环节动态列的数据:把这一批单据的表态行一次捞回来,按 (job, activity) 取最近一次。""" + wanted = {str(spec.activity.get("id") or "") for spec in specs if spec.kind == "activity"} + wanted.discard("") + if not wanted: + return + jobs = [str(row.job) for row in rows] + bucket: dict[str, dict[str, dict]] = {job: {} for job in jobs} + for model, pending in ((models.TaskCompleted, False), (models.Task, True)): + cond = [model.job.in_(jobs), model.activity.in_(wanted)] + for item in db.execute(select(model).where(*cond)).scalars().all(): + moment = getattr(item, "completed_time", None) or getattr(item, "start_time", None) + current = bucket.setdefault(str(item.job), {}).get(str(item.activity)) + if current and (current.get("time") or datetime.min) >= (moment or datetime.min): + continue + bucket[str(item.job)][str(item.activity)] = { + "name": str(item.identity_name or item.identity or ""), + "time": moment, + "opinion": str(getattr(item, "opinion", "") or ""), + "pending": pending, + } + for row in rows: + row._activities = bucket.get(str(row.job), {}) + + +def _attach_unoperators(db: Session, rows: list, kinds: Iterable[str], locked: Iterable[tuple[str, str]]) -> None: + unops = unoperators(db, [str(row.job) for row in rows], kinds=kinds, locked_pairs=locked) + for row in rows: + row._unop = unops.get(str(row.job), Unop()) + + +def _summary_sheet(sheets: list[Sheet]) -> Sheet: + headers = [COLUMN_LABELS.get(col, col) for col in SUMMARY_COLUMNS] + names = [COLUMN_LABELS.get(col, col) for col in SUMMARY_COLUMNS] + rows: list[list[str]] = [] + for sheet in sheets: + if sheet.name == SUMMARY_SHEET_NAME: + continue + # 按表头文字对位,不按位置:每条流程那张表的列数本来就不一样 + positions = [sheet.headers.index(name) for name in names if name in sheet.headers] + if len(positions) != len(names): + # 这一张缺了汇总表要的那一列(这条流程压根没这一格),整行按缺列补空 + positions = [sheet.headers.index(name) if name in sheet.headers else -1 for name in names] + for line in sheet.lines: + rows.append([line[position] if position >= 0 else "" for position in positions]) + return Sheet(SUMMARY_SHEET_NAME, headers, rows) + + +def build_sheets( + db: Session, user, filters: Filters, specs: list[ColumnSpec], rows: list, *, + layout: str = LAYOUT_PER_PROCESS, summary: bool = False, limit: int | None = None, +) -> list[Sheet]: + """把一页单据落成若干张表。``perProcess`` 一条流程一张,``merged`` 全部混在一张。""" + cache = dicts_service.DictCache(db) + # 关联审批单那几格要翻成「单号 标题」,一次问完;字段定义按所选流程并集给 + definitions: dict[str, dict] = {} + for process_id in (filters.processes or []): + for item in form_fields_of(db, process_id): + definitions.setdefault(str(item.get("key") or ""), item) + jobs = exportfmt.relation_names( + db, rows, [item for key, item in definitions.items() if f"form.{key}" in + {spec.id for spec in specs}]) + locked = locked_pairs_for(db, filters.processes) if filters.unoperator.exclude_locked else [] + _attach_unoperators(db, rows, filters.unoperator.kinds, locked) + _load_activities(db, rows, specs) + names = {row.id: str(row.name or "") for row in db.execute( + select(models.Process).where(models.Process.id.in_(filters.processes))).scalars().all()} + + def line_for(row, column_specs: list[ColumnSpec]) -> list[str]: + unop = getattr(row, "_unop", Unop()) + halt = halt_type(row, unop) + return [_text(row, spec, cache, jobs, unop, halt) for spec in column_specs] + + if layout == LAYOUT_MERGED: + # 「流程」永远排第一列,勾没勾都一样:混排之后分辨每一行是谁家的全凭这一列 + column_specs = [spec for spec in specs if spec.id != "base.process_name"] + column_specs = [ + next((spec for spec in specs if spec.id == "base.process_name"), + ColumnSpec("base.process_name", "流程", "base")), *column_specs] + headers = [spec.label for spec in column_specs] + lines = [line_for(row, column_specs) for row in rows] + if limit is not None: + lines = lines[:limit] + merged = Sheet("流程明细", headers, lines) + # 合并模式也认「附一张汇总表」:这个勾既然按下了,就不能悄悄当没看见 + return [_summary_sheet([merged]), merged] if summary else [merged] + + grouped: dict[str, list] = {} + for row in rows: + grouped.setdefault(str(getattr(row, "process", "") or ""), []).append(row) + order = filters.processes or list(grouped) + sheets: list[Sheet] = [] + used: set[str] = set() + for process_id in order: + bucket = grouped.get(process_id) or [] + column_specs = filter_specs_for_process(db, specs, process_id) + if not column_specs: + continue + # 一条单子都没命中的流程照样留一张只有表头的表:界面上说了「将出 N 张表」, + # 文件里就该有 N 张,少一张都会被读成「导出漏了这条流程」。流程改过名或被删了才退回旧名。 + title = names.get(process_id) or ( + str(bucket[0].process_name or process_id) if bucket else process_id) + sheets.append(Sheet( + sheet_name(title, used), + [spec.label for spec in column_specs], + [line_for(row, column_specs) for row in bucket], + )) + if limit is not None: + total = 0 + for sheet in sheets: + total += len(sheet.lines) + if total > limit: + keep = len(sheet.lines) - (total - limit) + sheet.lines = sheet.lines[:max(0, keep)] + total = limit + if summary and sheets: + merged = build_sheets(db, user, filters, specs, rows, layout=LAYOUT_MERGED, limit=limit) + sheets.insert(0, _summary_sheet(merged)) + return sheets + + +_BAD_SHEET = re.compile(r"[\[\]:*?/\\]") + + +def sheet_name(name: str, used: set[str]) -> str: + """Excel 的 sheet 名:不许超过 31 字符、不许带 ``[]:*?/\\``、不许重名。 + + 流程被改过名时老单据的 ``process_name`` 还是旧名,两条流程的名字也可能撞车, + 所以重名补 ``-2``,而不是让 openpyxl 在保存那一刻才报错。 + """ + cleaned = _BAD_SHEET.sub("·", str(name or "流程")).strip() or "流程" + cleaned = cleaned[:31] + candidate = cleaned + index = 2 + while candidate in used: + tail = f"-{index}" + candidate = cleaned[:31 - len(tail)] + tail + index += 1 + used.add(candidate) + return candidate + + +def to_xlsx(sheets: list[Sheet]) -> bytes: + """流式写工作簿。五万行别学老写法先在内存里拼一份二维数组。""" + from openpyxl import Workbook # 延迟导入:没装 openpyxl 也能起服务(与 preview 同一套) + from openpyxl.utils import get_column_letter + + book = Workbook(write_only=True) + for sheet in sheets: + page = book.create_sheet(title=sheet.name) + page.freeze_panes = "A2" + page.append(sheet.headers) + for line in sheet.lines: + page.append(line) + if sheet.lines: + page.auto_filter.ref = f"A1:{get_column_letter(max(1, len(sheet.headers)))}{len(sheet.lines) + 1}" + buffer = io.BytesIO() + book.save(buffer) + book.close() + return buffer.getvalue() + + +def to_csv(sheets: list[Sheet]) -> bytes: + """CSV 只有一个表头,所以它只配承载合并那一种形态(多张表在这里是拼不下的)。""" + buffer = io.StringIO() + writer = csv.writer(buffer) + for index, sheet in enumerate(sheets): + if len(sheets) > 1: + writer.writerow([f"# {sheet.name}"]) + writer.writerow(sheet.headers) + writer.writerows(sheet.lines) + if index < len(sheets) - 1: + writer.writerow([]) + return ("\ufeff" + buffer.getvalue()).encode("utf-8") + + +XLSX_TYPE = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" + + +def file_name(fmt: str) -> str: + return f"流程明细导出_{datetime.now():%Y%m%d_%H%M}.{'xlsx' if fmt == FORMAT_XLSX else 'csv'}" + + +def validate(filters: Filters, columns: list[str], layout: str, fmt: str) -> None: + """把界面上不该出现的组合在后端也挡一次:前端置灰只是让人少挨一次错。""" + if not filters.processes: + raise bad_request("请先勾选要导出的流程") + if len(filters.processes) > MAX_PROCESSES: + raise bad_request(f"一次最多勾 {MAX_PROCESSES} 条流程,请分几次导") + if not columns: + raise bad_request("请至少勾选一列") + if layout not in LAYOUTS: + raise bad_request(f"分表方式只认 {' / '.join(LAYOUTS)}") + if fmt not in (FORMAT_XLSX, FORMAT_CSV): + raise bad_request("导出格式只认 xlsx / csv") + if layout == LAYOUT_PER_PROCESS and fmt == FORMAT_CSV: + raise bad_request("CSV 只有一个表头,按流程分表请导 XLSX,或改选「合并成一张表」") + unknown = [column for column in columns + if not column.startswith(("base.", "form.", "table.", "activity."))] + if unknown: + raise bad_request("不认识的列: " + ", ".join(unknown[:5])) + + +__all__ = [ + "ALL_KINDS", "BASE_COLUMNS", "DEFAULT_COLUMNS", "DEFAULT_KINDS", "KIND_LABELS", + "LAYOUT_MERGED", "LAYOUT_PER_PROCESS", "MAX_PROCESSES", "UNOPERATOR_COLUMNS", "ColumnSpec", + "build_columns", "build_sheets", "counts_by_process", "catalog", "field_columns", "file_name", + "filters_from_body", "form_fields_of", "halt_type", "headers_for", "max_rows", + "project_targets", "query_page", "sheet_name", "status_filter", "to_csv", "to_xlsx", + "unoperators", "validate", "XLSX_TYPE", +] + + +def catalog(db: Session) -> dict: + """这一页开场的全部家底:能导哪些流程、每条流程有哪些列、项目那一格在哪。 + + 流程清单不按数据范围筛——范围管的是**能看见谁的单子**,流程定义本身是给所有人看的目录; + 真要限制,导出来的行自然会被 :func:`permissions.scope_person_refs` 滤空。 + """ + rows = db.execute( + select(models.Process) + .where(or_(models.Process.enabled.is_(True), models.Process.published.is_(True))) + .order_by(models.Process.category_name, models.Process.order_number, models.Process.name) + ).scalars().all() + activities: dict[str, list[dict]] = {} + for row in db.execute( + select(models.Activity) + .where(models.Activity.process.in_([item.id for item in rows] or ["__none__"]), + models.Activity.type == "manual") + .order_by(models.Activity.process, models.Activity.order_number, models.Activity.id) + ).scalars().all(): + activities.setdefault(str(row.process), []).append( + {"id": str(row.id), "name": str(row.name or ""), "orderNumber": int(row.order_number or 0)}) + processes = [] + for process in rows: + fields = form_fields_of(db, process.id) + project = detect_project_field(fields) + processes.append({ + "id": str(process.id), + "name": str(process.name or ""), + "alias": str(process.alias or ""), + "category": str(process.category or ""), + "categoryName": str(process.category_name or ""), + "enabled": bool(process.enabled), + "columns": field_columns(fields), + "projectField": project, + "activities": activities.get(str(process.id), [])[:MAX_ACTIVITY_COLUMNS], + }) + return { + "processes": processes, + "baseColumns": [{"id": key, "label": label} for key, label in BASE_COLUMNS], + "unoperatorColumns": [{"id": key, "label": label} for key, label in UNOPERATOR_COLUMNS], + "defaultColumns": list(DEFAULT_COLUMNS), + "unoperatorKinds": [ + {"id": kind, "label": KIND_LABELS[kind], "default": kind in DEFAULT_KINDS} + for kind in ALL_KINDS + ], + "layouts": [LAYOUT_PER_PROCESS, LAYOUT_MERGED], + "formats": [FORMAT_XLSX, FORMAT_CSV], + "maxRows": max_rows(), + "maxColumns": max_columns(), + "maxProcesses": MAX_PROCESSES, + "maxActivityColumns": MAX_ACTIVITY_COLUMNS, + } + + +def filters_from_body(payload: dict | None) -> Filters: + """给 API 层用的入口:报文 → :class:`Filters`。""" + return Filters.from_body(payload) diff --git a/backend/app/service/events.py b/backend/app/service/events.py index f4ed688..579964d 100644 --- a/backend/app/service/events.py +++ b/backend/app/service/events.py @@ -24,6 +24,7 @@ from sqlalchemy.orm import Session from .. import models, presence, readcache from . import channels, fetch, signing +from . import wake as wake_signal #: 事件清单:界面上的勾选框、接口文档里的事件表,都从这一处生成 CATALOG: tuple[tuple[str, str, str], ...] = ( @@ -157,6 +158,8 @@ def emit(db: Session, work, event: str, *, activity_name: str = "", actor_name: added += 1 if added: db.flush() + # 与消息渠道同一条叫醒通路:订阅方等的是"业务已经变了",不是"下个周期再看" + wake_signal.mark(db) return added diff --git a/backend/app/service/exportfmt.py b/backend/app/service/exportfmt.py new file mode 100644 index 0000000..cb9ed53 --- /dev/null +++ b/backend/app/service/exportfmt.py @@ -0,0 +1,218 @@ +"""导出单元格的取值口径:一个字段值该落成什么样的文本。 + +从 ``api/export.py`` 原样搬过来的这一层是**纯值渲染**,两条导出口都用它 +(``api/export.py`` 的列表导出、``service/detail_export.py`` 的流程明细导出), +所以搬成了独立模块——同一个字段在两张导出表里必须长一个样。 +搬过来时把下划线开头的名字放开了,因为它不再是某个模块的私货; +``api/export.py`` 按老名字 re-import 回来,那边的调用与既有文档引用都不动。 + +三条值得一提的口径(原文照抄,别在这儿漂): + +- 字典值一律翻成标签再落地,导出来的是「差旅费」而不是「CL01」。 +- 签名是几十 KB 的 base64,只留「签没签」这个事实;附件只留文件名。 +- 明细表压成一格 ``姓名=张三;金额=500 | 姓名=李四;金额=800``。 +""" + +from __future__ import annotations + +from datetime import datetime +from typing import TYPE_CHECKING + +from sqlalchemy import select + +from .. import models +from . import dicts as dicts_service +from . import formruntime + +if TYPE_CHECKING: + from sqlalchemy.orm import Session + +# --------------------------------------------------------------------------- +# 状态标签 +# --------------------------------------------------------------------------- + +#: 工作状态下拉框里的取值 -> 中文标签,与前端 utils/oa.ts 的口径一致。 +WORK_STATUS_LABELS = { + "running": "在途", + "completed": "办结", + "terminated": "终止", + "canceled": "作废", + "pending": "待处理", +} + +# --------------------------------------------------------------------------- +# 值 -> 单元格文本 +# --------------------------------------------------------------------------- + +# --------------------------------------------------------------------------- +# 值 -> 单元格文本 +# --------------------------------------------------------------------------- + + +def dt(value: datetime | None) -> str: + return "" if value is None else value.replace(microsecond=0).isoformat(sep=" ") + + +def status_label(value: object, paused: bool = False) -> str: + key = str(value or "") + label = WORK_STATUS_LABELS.get(key, key) + # 挂起不改流程状态,导出的 CSV 里就得靠这一眼看出来:筛完「只看挂起」导出去, + # 状态列如果还只写「运行中」,这张表等于把干预动作全抹掉了。 + return f"{label}(已挂起)" if paused and key == "running" else label + + +def duration_text(seconds: object) -> str: + try: + total = int(seconds or 0) # type: ignore[arg-type] + except (TypeError, ValueError): + return "" + if total <= 0: + return "" + days, rest = divmod(total, 86400) + hours, rest = divmod(rest, 3600) + minutes = rest // 60 + parts = [] + if days: + parts.append(f"{days}天") + if hours: + parts.append(f"{hours}小时") + if minutes or not parts: + parts.append(f"{minutes}分") + return "".join(parts) + + +def scalar_text(value: object) -> str: + if value is None: + return "" + if isinstance(value, bool): + return "是" if value else "否" + if isinstance(value, (list, tuple, set)): + return "、".join(str(item) for item in value if str(item or "").strip() != "") + if isinstance(value, dict): + return ";".join(f"{key}={scalar_text(item)}" for key, item in value.items()) + return str(value) + + +def cell_text( + field: dict, value: object, cache: dicts_service.DictCache, jobs: dict[str, str] | None = None +) -> str: + """单个表单字段落地成什么文本:选项翻标签,明细表压一行,附件只留文件名。""" + kind = str(field.get("type") or "") + if value is None or (isinstance(value, str) and not value.strip()): + return "" + if kind == "signature": + # 签名是几十 KB 的 base64,导进表格既打不开也没意义,只留"签没签"这个事实。 + return "已签名" if str(value).strip() else "" + if kind in ("relation", "picker"): + if dicts_service.source_kind_of(field) != dicts_service.SOURCE_PROCESS: + # 这一格关联的是字典项或外部数据源的编码,不是单据 job: + # 拿单据名册去翻只会原样吐回一串看不懂的主键,按候选来源翻才念得人话。 + return dicts_service.option_labels(field, value, cache) + names = jobs or {} + labels = [names.get(str(item), str(item)) for item in relation_ids(value)] + return "、".join(label for label in labels if label) + if kind == "table": + return table_text(field, value, cache, jobs) + if kind in ("select", "radio", "checkbox"): + return dicts_service.option_labels(field, value, cache) + if kind == formruntime.CASCADER_TYPE: + # 级联的值是一条自上而下的路径,用斜杠分开才看得出是"华东 / 上海"而不是两个并列选项。 + return dicts_service.option_labels(field, value, cache, sep=" / ") + if kind == "switch": + return "是" if value in (True, "true", 1, "1") else "否" + if kind in ("attachment", "image"): + names = [str(item.get("name") or "") for item in formruntime.rows_of(value)] + return "、".join(name for name in names if name) or scalar_text(value) + if kind in ("daterange", "timerange"): + # 区间那两项念成"起 ~ 止",直接转字符串会把中括号和引号一起灌进单元格 + text = formruntime.range_text(value) + if text: + return text + if kind == "week": + return formruntime.week_text(value) + if kind == "months": + # 多选月份存的是 YYYY-MM 数组,念成"2026年10-11月"才像一句人话 + return formruntime.months_text(value) + if kind == formruntime.LOCATION_TYPE: + return formruntime.location_text(value) + if kind == "richtext": + # 存的是 Markdown 原文:去掉记号再进表格,否则一格里躺着的是 ## 和 - 而不是话 + return formruntime.markdown_text(value) + if kind == "money" and field.get("uppercase"): + upper = formruntime.chinese_upper(value) + return f"{scalar_text(value)}({upper})" if upper else scalar_text(value) + return scalar_text(value) + + +def relation_ids(value: object) -> list[str]: + """关联审批单的值收成 job 列表:单个字符串、对象数组、字符串数组都认。""" + if isinstance(value, str): + return [value] if value.strip() else [] + if isinstance(value, dict): + return [str(value.get("job") or "")] if value.get("job") else [] + if isinstance(value, (list, tuple)): + out: list[str] = [] + for item in value: + out.extend(relation_ids(item)) + return out + return [] + + +def table_text( + field: dict, value: object, cache: dicts_service.DictCache, jobs: dict[str, str] | None = None +) -> str: + """明细表压成一格:``姓名=张三;金额=500 | 姓名=李四;金额=800``。""" + columns = formruntime.columns_of(field) + lines: list[str] = [] + for row in formruntime.rows_of(value): + pieces: list[str] = [] + if columns: + for column in columns: + key = str(column.get("key") or "") + text = cell_text(column, row.get(key), cache, jobs) + if text: + pieces.append(f"{column.get('label') or key}={text}") + else: + pieces = [f"{key}={scalar_text(item)}" for key, item in row.items()] + if pieces: + lines.append(";".join(pieces)) + return " | ".join(lines) + +# --------------------------------------------------------------------------- +# 表单列 +# --------------------------------------------------------------------------- + +def form_export_fields(db: Session, form_id: str) -> list[dict]: + """这张表单要摊成列的字段:有字段名、且真的参与录入。""" + row = db.get(models.FormElement, form_id) if form_id else None + return [ + item + for item in formruntime.fields_of(row.content if row else {}) + if str(item.get("key") or "") and formruntime.fillable(item) + ] + + +# --------------------------------------------------------------------------- +# 关联审批单:job -> 「单号 标题」 +# --------------------------------------------------------------------------- + +def relation_names(db: Session, rows: list, fields: list[dict]) -> dict[str, str]: + """把关联字段里出现的 job 一次性翻成「单号 标题」,避免逐行查库。""" + wanted: list[str] = [] + for row in rows: + data = dict(row.data or {}) + for field in fields: + # 只有「候选来自流程单据」的那几格存的是 job,别的来源不用去单据表里翻 + if str(field.get("type") or "") not in ("relation", "picker") \ + or dicts_service.source_kind_of(field) != dicts_service.SOURCE_PROCESS: + continue + for job in relation_ids(data.get(str(field.get("key") or ""))): + if job not in wanted: + wanted.append(job) + if not wanted: + return {} + names: dict[str, str] = {} + for model in (models.Work, models.WorkCompleted): + for row in db.execute(select(model).where(model.job.in_(wanted))).scalars().all(): + names.setdefault(row.job, f"{row.serial or ''} {row.title}".strip()) + return {job: names.get(job, job) for job in wanted} diff --git a/backend/app/service/hub.py b/backend/app/service/hub.py index d299a22..22bb38b 100644 --- a/backend/app/service/hub.py +++ b/backend/app/service/hub.py @@ -118,6 +118,7 @@ class HubError(Exception): reason: str = "", retryable: bool = False, needs_captcha: bool = False, + status: int = 0, ) -> None: super().__init__(message) self.message = message @@ -125,13 +126,17 @@ class HubError(Exception): self.reason = reason self.retryable = retryable self.needs_captcha = needs_captcha + #: Hub 答话时的 HTTP 状态码(没答话是 0)。推送那一路要靠它分清 + #: "409 上一次还在发送中"(等会儿重发)与"400 参数不合法"(改了才有用), + #: 两边用的是同一个 ``code``(400001),只看 code 分不开。 + self.status = int(status or 0) class HubUnavailable(HubError): """网络不通、超时、Hub 5xx:不是用户填错了东西。""" - def __init__(self, message: str = "统一身份认证服务暂不可用,请稍后重试") -> None: - super().__init__(message, code=CODE_UNAVAILABLE, retryable=True) + def __init__(self, message: str = "统一身份认证服务暂不可用,请稍后重试", *, status: int = 0) -> None: + super().__init__(message, code=CODE_UNAVAILABLE, retryable=True, status=status) class HubRejected(HubError): @@ -506,7 +511,7 @@ class HubClient: code = str(envelope.get("code", "")).strip() message = str(envelope.get("message") or "").strip() if status >= 500 or code == CODE_UNAVAILABLE: - raise HubUnavailable(message or "统一身份认证服务暂不可用,请稍后重试") + raise HubUnavailable(message or "统一身份认证服务暂不可用,请稍后重试", status=status) if code == OK: return envelope.get("data") # 另一种错误口径:Hub(或它前面的网关)不套统一响应,只回 error 名。 @@ -519,6 +524,7 @@ class HubClient: code=slug, reason=CODE_UNAUTHORIZED, needs_captcha="验证码" in message or slug in CAPTCHA_ERROR_SLUGS, + status=status, ) if code in ("", None): if 200 <= status < 300 and envelope and "error" not in envelope: @@ -532,13 +538,15 @@ class HubClient: hint = "验证码" in message if status == 401 or code == CODE_UNAUTHORIZED: raise HubRejected( - message or "账号或密码错误", code=code, reason=CODE_UNAUTHORIZED, needs_captcha=hint + message or "账号或密码错误", code=code, reason=CODE_UNAUTHORIZED, + needs_captcha=hint, status=status, ) raise HubRejected( message or f"统一身份认证服务拒绝了本次请求({code})", code=code, reason=code, needs_captcha=hint, + status=status, ) # -------------------------------------------------------------------- 接口 @@ -644,6 +652,41 @@ class HubClient: raw=data, ) + def notify_wecom(self, payload: dict[str, Any]) -> dict[str, Any]: + """发一条企业微信消息给 Hub,由 Hub 换成企微应用消息投出去(文档 9.6.2)。 + + 用的是免登那把应用密钥(``X-Integration-Key``),本系统这边不持有企微凭据。 + 信封照 :meth:`_request` 拆好,返回的就是文档里的 ``data``:整体状态 ``status`` + 加逐人明细 ``recipients[]``。**幂等靠调用方传来的 ``msg_key``**——超时之后 + 原样重发是安全的(文档 9.6.4),所以这里一律不自己重试。 + """ + cfg = hubconfig.get() + key = cfg.hub_integration_key.strip() + if not key: + raise HubError( + "未配置免登应用密钥:请在系统设置「统一身份」里填上" + "(配置文件 [hub] integration_key / 环境变量 OA_HUB_INTEGRATION_KEY)", + code=CODE_UNAUTHORIZED, + ) + data = self._request( + "POST", cfg.hub_path_notify_wecom, payload=payload, headers={"X-Integration-Key": key} + ) + return data if isinstance(data, dict) else {} + + def notify_wecom_status(self, msg_key: str) -> dict[str, Any]: + """按 ``msg_key`` 回查这一次推送的逐人明细(文档 9.6.7)。 + + 与推送响应同构,只读、可反复调;回查别人的记录是 404(走 :class:`HubRejected`)。 + """ + cfg = hubconfig.get() + key = cfg.hub_integration_key.strip() + if not key: + raise HubError("未配置免登应用密钥,查不了投递明细", code=CODE_UNAUTHORIZED) + data = self._request( + "GET", cfg.notify_status_path(msg_key), headers={"X-Integration-Key": key} + ) + return data if isinstance(data, dict) else {} + def apps(self, token: str) -> list[dict[str, Any]]: """当前用户在门户里能看到的应用(文档 3.1,要用户登录态)。 diff --git a/backend/app/service/hub_sync.py b/backend/app/service/hub_sync.py index 380965f..79875e7 100644 --- a/backend/app/service/hub_sync.py +++ b/backend/app/service/hub_sync.py @@ -17,7 +17,9 @@ * 企业微信 UserID(``users.wecom_user_id``)比手机号多一种情况:**"带了字段但值是空的" 是一句话,不是一个缺失**。企微 UserID 会被删掉再分配给另一名员工,所以 Hub 明确说 "这个人没有企微号"时本地跟着清空;压根不带这个字段时仍然原样保留(见 6 节与 - :func:`_hub_wecom_user_id`)。 + :func:`_hub_wecom_user_id`)。Hub 把同一个号同时发给几个人(通讯录里真有这样的事) + 时本地**照抄**,几个人都挂着这个号,只在同步记录里报数 —— 这一列是上游的镜像, + 不是本地唯一键。 凭证:全量目录接口(文档第 11 节)现在用长期密钥认服务端调用——配了「目录密钥」 (``hub_directory_key`` / ``OA_HUB_DIRECTORY_KEY``)就以请求头 ``X-Directory-Key`` 带出去, @@ -37,7 +39,7 @@ import logging import re import secrets import threading -from collections.abc import Iterator +from collections.abc import Iterable, Iterator from dataclasses import dataclass, field from datetime import datetime, timedelta from typing import Any @@ -243,6 +245,15 @@ def _hub_wecom_user_id(item: dict[str, Any]) -> tuple[str, str]: return "", (WECOM_DIRTY if dirty else WECOM_BLANK) +#: 同步记录 ``details`` 里每类名单最多留几条。计数不受这个上限影响, +#: 上限只防止一次批量改名往一行的 JSON 里塞进上千个名字。 +DETAIL_ITEM_LIMIT = 20 + +#: ``details.notes`` 里每条提示的字数上限:``message`` 整列只留 2000 字, +#: 提示一多就被裁掉后半句,这里按条存原文(各自截断),界面上能看全。 +DETAIL_NOTE_CHARS = 400 + + @dataclass class SyncStats: #: 这一趟的开始时间:终止信号比它新才算数(见 :func:`cancel_requested`) @@ -268,6 +279,10 @@ class SyncStats: # 同步记录里出现就说明 Hub 那边数据有问题,值得点进详情看一眼。 no_hub_id: int = 0 renamed: int = 0 + #: 这一趟真的换掉过登录名的人的本地主键。改名落在 ``_plan_account_renames``(主循环之前), + #: 主循环靠这份名单把这些人算进 ``updated``——否则"只做了一次改名的同步"在同步历史里 + #: 会被显示成「无变更」,见 serialize_run 的 unchanged 口径 + renamed_ids: set[int] = field(default_factory=set) conflicts: int = 0 unbound: int = 0 # 手机号分三个数才说得清:"Hub 没下发这个字段"(下面两个都是 0)与"下发了但不是 @@ -288,8 +303,19 @@ class SyncStats: wecom_cleared: int = 0 #: Hub 带了企微字段、但洗不出合法 UserID(中文、带空格、超长)的人数 wecom_invalid: int = 0 - #: UserID 已经挂在别的账号上、本次没敢覆盖的人数(企微号重新分配过,或本地有重复账号) + #: Hub 发的 UserID 和别人是同一个号的人数(本地照抄,共用这个号的人都挂着它) wecom_conflicts: int = 0 + #: 已停用、且这一趟完整清单里查无此人的同步账号,把登录名让出去的人数 + #: (见 :func:`_retire_lost_accounts`;行本身不删,权限与轨迹都还在) + reclaimed: int = 0 + #: Hub 换了 ``organization_id`` 之后按「编码 + 名称」认回原部门的个数(见 :func:`_sync_units`) + units_rebound: int = 0 + #: 撞上部门停用熔断、这一趟没敢停用的部门数(见 :func:`_offboard_missing_units`) + units_offboard_guarded: int = 0 + #: 撞上离职停用熔断、这一趟没敢停用的人数(见 :func:`_offboard_missing`) + offboard_guarded: int = 0 + #: 已停用的僵尸账号腾出来的企业微信 UserID 个数(号还给 Hub 认定的现任主人) + wecom_released: int = 0 # 这次同步改过的名字:老值 -> 新值。审批岗位、岗位组、代理人这些是按字符串 # 存人员的,同步完要照着这几张表把它们一起搬走,见 service/hub_refs.py。 display_name_map: dict[str, str] = field(default_factory=dict) @@ -298,6 +324,17 @@ class SyncStats: account_map: dict[str, str] = field(default_factory=dict) refs_rewritten: int = 0 refs_ambiguous: int = 0 + # 「这一趟到底动了谁」的名字:只留前 DETAIL_ITEM_LIMIT 条,写进同步记录的 details, + # 界面上能逐条展开。计数(renamed / reclaimed / units_rebound)走 SyncStats 上的 + # 同名字段,不受这个上限影响,所以上限只是防止一条 JSON 装下上千个名字。 + #: 登录账号改名前后对照(``旧账号 → 新账号``) + account_renames: list[str] = field(default_factory=list) + #: 姓名(display_name)改名前后对照 + name_renames: list[str] = field(default_factory=list) + #: 让出登录名的僵尸同步账号(``原账号 → hub-lost-…``) + reclaimed_accounts: list[str] = field(default_factory=list) + #: 按「编码 + 名称」认回原部门的部门名(Hub 换过 organization_id) + rebound_units: list[str] = field(default_factory=list) permission_version: int = 0 member_limit: int = 0 truncated: bool = False @@ -308,6 +345,12 @@ class SyncStats: credential: str = "anonymous" messages: list[str] = field(default_factory=list) + def detail(self, bucket: str, text: str) -> None: + """往有界明细里记一条名字级信息(桶名见 :class:`SyncStats` 上那四个列表字段)。""" + rows = getattr(self, bucket) + if text and len(rows) < DETAIL_ITEM_LIMIT: + rows.append(text) + def note(self, text: str) -> None: if text and len(self.messages) < 20: self.messages.append(text) @@ -646,6 +689,75 @@ def sso_status() -> dict[str, Any]: } +def _run_status(stats: SyncStats) -> str: + """这一趟以什么状态收口:清单没拉全、或者熔断把人 / 部门整批挡下来没停的,都不算成功。 + + 单独拎出来是因为"少干了活"必须看得见——标成 success 的话,第二天没人会去翻那几条 note。 + """ + return ( + models.HubSyncRun.STATUS_PARTIAL + if stats.truncated or stats.offboard_guarded or stats.units_offboard_guarded + else models.HubSyncRun.STATUS_SUCCESS + ) + + +def run_details(stats: SyncStats) -> dict[str, Any]: + """把"这一趟到底动了谁"整理成结构化明细,写进 ``oa_hub_sync_run.details``。 + + 为什么不能只靠 ``message``:那是整段 2000 字的纯文本,多条提示拼在一起,超了就 + 裁掉后半句;界面上翻来覆去也只有「更新 N 人」这种数。改名、僵尸账号让位、按编码 + 认回部门这三件事都是**要点开名字去核对**的,光有数字说不出该核对谁。所以这里存 + 有界名单(每类前 :data:`DETAIL_ITEM_LIMIT` 条)+ 完整计数 + 按条原文的提示, + 名单被裁掉时总数照样准。 + + 增量轮询每几十秒就记一行,所以这里刻意只放小字段,不塞清单本身。 + """ + return { + # 可核对的名单(有界) + "account_renames": stats.account_renames, + "name_renames": stats.name_renames, + "reclaimed_accounts": stats.reclaimed_accounts, + "rebound_units": stats.rebound_units, + # 对应的总数:名单被上限裁掉时,界面靠它说"共 N 条,这里只列了前 M 条" + "renamed": stats.renamed, + "reclaimed": stats.reclaimed, + "units_rebound": stats.units_rebound, + "name_renamed": len(stats.display_name_map), + # 只报规模的计数:以前同样只在 message 文本里,读的人得自己从句子中扒数字 + "counts": { + "adopted": stats.adopted, + "protected": stats.protected, + "conflicts": stats.conflicts, + "unbound": stats.unbound, + "no_hub_id": stats.no_hub_id, + "emergency": stats.emergency, + "skipped": stats.skipped, + "units_bound": stats.units_bound, + "refs_rewritten": stats.refs_rewritten, + "refs_ambiguous": stats.refs_ambiguous, + "changes_skipped": stats.changes_skipped, + }, + # 手机号与企业微信两个字段各三个数,来源不同结论完全不同(Hub 没下发 / 下发但是脏值) + "mobile": { + "returned": stats.mobile_returned, + "updated": stats.mobile_updated, + "invalid": stats.mobile_invalid, + }, + "wecom": { + "returned": stats.wecom_returned, + "updated": stats.wecom_updated, + "cleared": stats.wecom_cleared, + "invalid": stats.wecom_invalid, + "conflicts": stats.wecom_conflicts, + "released": stats.wecom_released, + }, + # 熔断挡下来的量:非 0 就意味着这一趟"少干了活",见 _run_status + "guards": {"people": stats.offboard_guarded, "units": stats.units_offboard_guarded}, + # 提示原文按条存,不受 message 那 2000 字的整段截断影响 + "notes": [text[:DETAIL_NOTE_CHARS] for text in stats.messages], + } + + def serialize_run(row: models.HubSyncRun) -> dict[str, Any]: return { "id": row.id, @@ -670,9 +782,14 @@ def serialize_run(row: models.HubSyncRun) -> dict[str, Any]: "credential_label": credential_label(row.credential), "cursor_seq": int(row.cursor_seq or 0), "changes_applied": int(row.changes_applied or 0), + # 改名 / 让位 / 认回部门:这三个数不是"新建还是更新"能表达的动作,单独回显 + "renamed": int(row.renamed or 0), + "reclaimed": int(row.reclaimed or 0), + "units_rebound": int(row.units_rebound or 0), "operator": row.operator, "operator_name": row.operator_name, "message": row.message, + "details": row.details or {}, "unchanged": ( row.created + row.updated @@ -680,6 +797,10 @@ def serialize_run(row: models.HubSyncRun) -> dict[str, Any]: + row.units_created + row.units_updated + row.units_offboarded + # 「只做了一次批量改名的同步」和「让位了 68 个账号的同步」都不是无变更 + + int(row.renamed or 0) + + int(row.reclaimed or 0) + + int(row.units_rebound or 0) ) == 0, } @@ -915,6 +1036,35 @@ def _local_units_by_code(db: Session) -> dict[str, list[models.Unit]]: return out +def _ghost_unit_candidates( + db: Session, run_org_ids: set[int], busy_keys: set[tuple[str, str]] +) -> dict[tuple[str, str], list[models.Unit]]: + """把"Hub 主键已经不在这趟清单里"的本地部门按 ``(编码, 名称)`` 分组,给换主键认领用。 + + Hub 重导一遍数据会把 ``organization_id`` 整体换号(实测测试站 2026-11-04:25~36 变成 + 2~13),而本地只认主键,认不出来就整棵树再建一遍:界面上两个「紫光汇智」、两套部门, + 人挂到新的一套上,按 ``oa_unit.id`` 配的权限与审批规则留在老的一套上,悄悄失效。 + 这里把"主键已经消失、编码和名称都还在"的行挑出来当认领候选,把部门主键留住。 + + ``busy_keys`` 是这一趟已经被别的本地部门对上的 ``(编码, 名称)``。那种同码重复是上一次 + 换号留下的壳子(真库现在有 12 组),再认一次只会多出第三个部门,所以不认。 + """ + if not run_org_ids: + return {} # 清单里一个部门都没有,"不在清单里"证明不了任何事 + out: dict[tuple[str, str], list[models.Unit]] = {} + rows = db.execute( + select(models.Unit).where(models.Unit.hub_org_id.is_not(None)).order_by(models.Unit.id) + ).scalars().all() + for unit in rows: + if int(unit.hub_org_id or 0) in run_org_ids: + continue + key = (str(unit.code or ""), str(unit.name or "")) + if not key[0] or key in busy_keys: + continue + out.setdefault(key, []).append(unit) + return out + + def _report_local_units(db: Session, seen: set[int], stats: SyncStats) -> None: """本地自建部门同步一律不碰,这里只把规模与风险数出来给界面、日志看。 @@ -952,7 +1102,11 @@ def _sync_units(db: Session, organizations: list[dict[str, Any]], stats: SyncSta ``parent_id``(层级挪动会连带刷子树路径),本地决定 ``alias`` / ``description`` / ``order_number`` / ``manager_person_id``,以及挂在任何部门下面的自建部门。 ``hub_org_id`` 写上一律不清空(界面上改不动,Hub 里消失也只是停用不删除),组织架构、 - 部门负责人、按部门配的权限与审批规则全靠它长期对上号。 + 部门负责人、按部门配的权限与审批规则全靠它长期对上号。唯一的例外是 Hub 自己把 + ``organization_id`` 整体换了号(重导数据、合并组织):那时清单里的主键本地一个都找不到, + 照旧逻辑会整棵树复制一遍,人搬去新行、按 ``oa_unit.id`` 配的规则留在老行上悄悄失效。 + 所以开了「按编码认领本地部门」时,编码与名称都对得上、且原主键已经不在这趟清单里的 + 老部门会被认回来(换新主键,本地主键不动),见 :func:`_ghost_unit_candidates`。 字段按文档第 11 节的组织节点落库:``organization_id`` -> ``hub_org_id``、 ``code`` -> ``code``、``name`` -> ``name``、``status`` -> ``status``(``1`` 之外一律停用); @@ -965,11 +1119,21 @@ def _sync_units(db: Session, organizations: list[dict[str, Any]], stats: SyncSta mapped = _hub_units(db, stats) local_by_code = _local_units_by_code(db) + # 先物化整棵树:认领"换了主键的老部门"要先知道这趟清单里到底有哪些组织 + nodes = list(_iter_org_nodes(_org_tree(organizations, stats))) + run_org_ids = {int(models.as_id(node.get("organization_id")) or 0) for node, _ in nodes} + run_org_ids.discard(0) + busy_keys = { + (str(unit.code or ""), str(unit.name or "")) + for hub_id, unit in mapped.items() + if unit.code and hub_id in run_org_ids + } + ghosts = _ghost_unit_candidates(db, run_org_ids, busy_keys) if cfg.hub_sync_bind_local_by_code else {} + rebinds: list[tuple[str, int, int]] = [] + seen: set[int] = set() order: list[tuple[models.Unit, models.Unit | None]] = [] - for index, (node, parent_hub_id) in enumerate( - _iter_org_nodes(_org_tree(organizations, stats)) - ): + for index, (node, parent_hub_id) in enumerate(nodes): if index and index % CANCEL_CHECK_EVERY == 0: _raise_if_cancelled(stats) hub_id = models.as_id(node.get("organization_id")) @@ -983,6 +1147,7 @@ def _sync_units(db: Session, organizations: list[dict[str, Any]], stats: SyncSta unit = mapped.get(hub_id) claimed = False + rebound_from = 0 if unit is None: # 本系统自己加的部门:组织编码跟 Hub 这个部门一模一样、而且这个编码本地只有一处, # 就认定是同一个部门,认下来(补写 hub_org_id),而不是再建一个重名部门。 @@ -994,6 +1159,30 @@ def _sync_units(db: Session, organizations: list[dict[str, Any]], stats: SyncSta unit = candidates[0] claimed = True local_by_code.pop(code, None) + if unit is None and ghosts: + # Hub 把 organization_id 整体换了号(重导、合并):编码和名称都对得上的老部门 + # 认回来,别新建。新建等于整棵树复制一份,人跟着搬到新行上,而按 oa_unit.id + # 配的权限与审批规则还留在老行上,悄悄就失效了。 + candidates = ghosts.get((code, name)) or [] + if len(candidates) > 1: + # 同码同名有好几具壳子(上一次换号留下的):只有一支底下真住着人就认那一支, + # 口径同 _hub_units 的"留人多的那支";都住着人或都不住人就不猜 + with_people = [u for u in candidates if _unit_weight(db, u)[0] > 0] + candidates = with_people if len(with_people) == 1 else [] + if len(candidates) == 1: + old_unit = candidates[0] + rebound_from = int(old_unit.hub_org_id or 0) + old_unit.hub_org_id = hub_id # 旧主键当场让开:这一行此后代表 Hub 的新组织 + unit = old_unit + claimed = True + ghosts.pop((code, name), None) + elif candidates: + # 同名同编码的僵尸不止一个:不猜谁是谁,按新部门建,交人工合并 + stats.note( + f"本地有 {len(candidates)} 个已停用的部门都叫 {name}(编码 {code})," + f"分不清 Hub 组织 {hub_id} 是哪一个,本次按新部门建" + ) + ghosts.pop((code, name), None) if unit is None: unit = models.Unit( @@ -1018,7 +1207,7 @@ def _sync_units(db: Session, organizations: list[dict[str, Any]], stats: SyncSta or unit.hub_org_id != hub_id or bool(code and unit.code != code) ) - if changed: + if changed or rebound_from: _record_pair(stats.unit_name_map, unit.name, name) unit.name = name unit.parent_id = parent_id @@ -1028,10 +1217,15 @@ def _sync_units(db: Session, organizations: list[dict[str, Any]], stats: SyncSta unit.code = code if claimed: stats.units_bound += 1 - stats.note( - f"本地部门 {name}(编码 {code})已按编码认成 Hub 组织 {hub_id}," - "此后名称与层级由 Hub 接管" - ) + if rebound_from: + stats.units_rebound += 1 + rebinds.append((name, rebound_from, hub_id)) + stats.detail("rebound_units", f"{name}(Hub {rebound_from} → {hub_id})") + else: + stats.note( + f"本地部门 {name}(编码 {code})已按编码认成 Hub 组织 {hub_id}," + "此后名称与层级由 Hub 接管" + ) else: stats.units_updated += 1 mapped[hub_id] = unit @@ -1040,6 +1234,13 @@ def _sync_units(db: Session, organizations: list[dict[str, Any]], stats: SyncSta # 第二轮再算路径:此时父级已经全部落库,改名/挪动会连带刷子树与部门 DN。 for unit, parent in order: _refresh_paths(db, unit, parent, stats) + if rebinds: + stats.note( + f"Hub 换了 {len(rebinds)} 个部门的主键,本地按「编码 + 名称」把它们认回了原部门" + f"(例如 {rebinds[0][0]}:Hub {rebinds[0][1]} → {rebinds[0][2]}):" + "部门主键没变,挂在它上面的权限、审批规则与部门负责人都留在原地," + "也没有另建一套重名部门;这一趟不会把它们判成已消失" + ) _offboard_missing_units(db, seen, stats) _report_local_units(db, seen, stats) @@ -1052,6 +1253,12 @@ def _offboard_missing_units(db: Session, seen: set[int], stats: SyncStats) -> No 这里是"停用"而不是"删除":``hub_org_id`` 一丢就再也对不回 Hub 的那个组织,下趟同步 只会新建一个空部门,负责人、按部门配的权限与审批规则全丢。宁可留着停用的壳子, 等对方把组织加回来就自动接上。 + + 也带一道熔断,口径同人员侧(共用 ``hub_sync_offboard_guard_percent``):一趟要停用的 + 部门超过 ``max(5, 同步部门总数 × 百分比)`` 时一个都不停,只报数并把这趟标成「部分完成」。 + 部门比人少得多,所以下限用 :data:`UNIT_OFFBOARD_GUARD_MIN`,不能用人员那侧的 20。 + 停用一个部门等于把它下面所有人的数据范围、按部门配的审批规则一起摘掉, + 错一批比少停几个代价大得多。 """ cfg = hubconfig.get() if not cfg.hub_sync_offboard: @@ -1065,9 +1272,32 @@ def _offboard_missing_units(db: Session, seen: set[int], stats: SyncStats) -> No models.Unit.status != models.UnitStatus.DISABLED, ) ).scalars().all() - for row in rows: - if row.hub_org_id in seen: - continue + pending = [row for row in rows if row.hub_org_id not in seen] + guard = int(cfg.hub_sync_offboard_guard_percent or 0) + if guard and pending: + total = int( + db.execute( + select(func.count()) + .select_from(models.Unit) + .where(models.Unit.hub_org_id.is_not(None)) + ).scalar() + or 0 + ) + ceiling = max( + _floor_value(cfg, "hub_sync_unit_offboard_guard_min", UNIT_OFFBOARD_GUARD_MIN), + total * guard // 100, + ) + if len(pending) > ceiling: + stats.units_offboard_guarded = len(pending) + stats.note( + f"{len(pending)} 个同步部门没出现在 Hub 清单里,超过部门停用熔断线" + f"({guard}%,本次上限 {ceiling} 个),这一趟一个部门都没停用。" + "停一个部门会连带摘掉它下面所有人的数据范围与按部门配的审批规则," + "先核对 Hub 拉到的是不是这套环境该有的组织(换站点、换目录密钥、" + "对方正在重导都会撞上),确认没问题再把 OA_HUB_SYNC_OFFBOARD_GUARD_PERCENT 调大或设 0" + ) + return + for row in pending: row.status = models.UnitStatus.DISABLED stats.units_offboarded += 1 if stats.units_offboarded: @@ -1077,6 +1307,81 @@ def _offboard_missing_units(db: Session, seen: set[int], stats: SyncStats) -> No ) +def find_shell_units( + units: Iterable[models.Unit], *, roster_org_ids: set[int] | None = None +) -> list[models.Unit]: + """Hub 换过 ``organization_id`` 之后留在树上的「重名壳子」部门。 + + 成因:Hub 那边把部门挪了主键(重建、合并、换环境重导),本地这一支靠「编码 + 名称」 + 认回了原部门(见 :func:`_sync_units`),旧的那一具就脱开了:``hub_org_id`` 指向一个 + 清单里已经不存在、且永远不会再出现的组织,状态停在停用,编码和名称都已被在职的孪生 + 部门占用。同步既不认它(主键对不上)也不会合并它(本地从不自动并部门),于是组织树 + 上常年挂着几具和在职部门同名的死壳子,部门下拉框里一排重复名字。 + + 四条判据缺一不可:绑过 Hub、**已停用**、编码与名称和某个**在职**的 Hub 部门完全一样、 + (给了 ``roster_org_ids`` 时)这一趟 Hub 清单里确实没有它。最后一条只在体检时加: + 本地判据本身已经说明"这个身份有人接着",清理接口不为了再确认一遍去拉一次 Hub。 + + 只删得掉"没人在用"的那几具,见 :func:`shell_unit_blockers`。 + """ + rows = [row for row in units if row.hub_org_id] + roster = {int(value) for value in (roster_org_ids or set())} + twin_keys = { + (str(row.code or ""), str(row.name or "")) + for row in rows + if row.status == models.UnitStatus.ACTIVE + and row.code + and (roster_org_ids is None or int(row.hub_org_id) in roster) + } + if not twin_keys: + return [] + shells: list[models.Unit] = [] + for row in rows: + if row.status != models.UnitStatus.DISABLED: + continue + if roster_org_ids is not None and int(row.hub_org_id) in roster: + continue # Hub 这一趟还认得它,那不是壳子,是正常停用的部门 + if (str(row.code or ""), str(row.name or "")) not in twin_keys: + continue # 没有在职的孪生部门顶着同一个身份,删掉就真没人接着了 + shells.append(row) + return shells + + +def shell_unit_blockers(db: Session, unit: models.Unit) -> list[str]: + """这个壳子部门还不能删的原因,空列表 = 可以放心删。 + + 删部门是不可逆的:``oa_unit.id`` 是本地主键,挂在它上面的东西不会因为改名跟着搬。 + 所以只放行"三样都干净"的:没有直属人员、没有下级部门(否则子树的 ``parent_id`` + 会指向一个不存在的行)、也没有权限角色把它当自定义数据范围。最后这一条尤其要紧: + 数据范围是按 ``oa_unit.id`` 存的,删掉之后角色不会报错,只会**安静地少一片范围**。 + """ + blockers: list[str] = [] + members = int( + db.execute( + select(func.count()).select_from(models.User).where(models.User.organization_id == unit.id) + ).scalar() + or 0 + ) + if members: + blockers.append(f"直属人员 {members} 人") + children = int( + db.execute( + select(func.count()).select_from(models.Unit).where(models.Unit.parent_id == unit.id) + ).scalar() + or 0 + ) + if children: + blockers.append(f"下级部门 {children} 个") + scoped = [ + role.name + for role in db.execute(select(models.AuthRole)).scalars().all() + if str(unit.id) in {str(value) for value in (role.data_unit_ids or [])} + ] + if scoped: + blockers.append("权限角色把它当数据范围:" + "、".join(scoped[:3])) + return blockers + + # --------------------------------------------------------------------------- # 人员 # --------------------------------------------------------------------------- @@ -1150,6 +1455,7 @@ def _apply_account_renames( _record_pair(stats.account_map, old_account, account) db.flush() stats.renamed += 1 + stats.renamed_ids.add(person.id) remaining.pop(person_id, None) progressed = True if not progressed: @@ -1184,23 +1490,256 @@ def _apply_account_renames( by_account[account] = person _record_pair(stats.account_map, old_account, account) stats.renamed += 1 + stats.detail("account_renames", f"{old_account} → {account}") + stats.renamed_ids.add(person.id) db.flush() +#: 僵尸账号让位之后挂的账号名前缀。带上 Hub 主键,是为了在人员列表里一眼看得出这条是谁、 +#: 为什么长成这样,也让同一个人在同一趟同步里算得出同一个名字(幂等判定靠它)。 +LOST_ACCOUNT_PREFIX = "hub-lost-" + +#: 离职停用熔断的绝对下限(配置项 ``hub_sync_offboard_guard_min_people`` 的出厂默认值): +#: 等着停用的人少到这个数以内,就不算"整家公司被判离职",照常停用。没有这条下限, +#: 几十人的小部署裁掉几个人就会被比例挡下来,天天弹熔断。 +OFFBOARD_GUARD_MIN_PEOPLE = 20 + +#: 部门停用熔断的绝对下限(``hub_sync_unit_offboard_guard_min`` 的出厂默认值):部门总数 +#: 比人数少得多,用人员那侧的 20 这条线永远不会触发。 +UNIT_OFFBOARD_GUARD_MIN = 5 + +#: 清单人数下限(``hub_sync_roster_floor_percent`` 的出厂默认值,相对上一次同步看到的人数)。 +#: Hub 在清库或重导的时候目录会突然只剩几个人,这时"本地有、清单里没有"什么也证明不了, +#: 账号名先原样留着。 +ROSTER_FLOOR_PERCENT = 50 + + +def _floor_value(cfg: Any, field: str, fallback: int) -> int: + """读熔断下限:优先用配置项,字段缺失或不是数就回落到上面的出厂默认值。 + + 回落而不是报错,是因为这三条线只是"挡误伤"的松紧,配置读不到时按出厂值拦比 + 完全不拦安全;单测与脚本里也常拿半截配置对象进来。 + """ + try: + value = int(getattr(cfg, field, None)) + except (TypeError, ValueError): + return fallback + return value if value >= 0 else fallback + + +def _roster_hub_ids(users: list[dict[str, Any]]) -> set[int]: + """这一趟 Hub 清单里出现过的 ``user_id`` 集合(正整数,去重)。""" + ids: set[int] = set() + for item in users: + if not isinstance(item, dict): + continue + hub_user_id = models.as_id(item.get("user_id")) + if hub_user_id and int(hub_user_id) > 0: + ids.add(int(hub_user_id)) + return ids + + +def _is_lost_account(cfg, person: models.User, roster: set[int]) -> bool: + """这条本地账号算不算"Hub 已查无此人、可以把登录名腾出去"。 + + 四个条件缺一不可:同步来的号(``source=hub``)、已经被停用、这一趟**完整**清单里没有 + 他的 Hub 主键、账号名不在应急名单里。判据与理由都写在 :func:`_retire_lost_accounts`, + 「同步前体检」也调这一个函数,免得预检报一堆冲突、真跑起来却一个都没有。 + """ + if not cfg.hub_sync_reclaim_lost_accounts or not roster: + return False + if person.source != models.AccountSource.HUB or not person.hub_user_id: + return False + if int(person.hub_user_id) in roster: + return False + # 这一趟才发现"查无此人"的先只停用,账号名留到下一趟再动:Hub 抖一下不该把人改名 + if person.status != models.UserStatus.DISABLED: + return False + account = person.account or "" + if not account or account.startswith(LOST_ACCOUNT_PREFIX): + return False # 已经让过位,别每趟再改一次 + return not is_emergency_account(account) + + +def _roster_floor_percent() -> int: + """清单人数下限的百分比(提示文字要照着它说"一半"还是"三成",别把数写死在句子里)。""" + return _floor_value(hubconfig.get(), "hub_sync_roster_floor_percent", ROSTER_FLOOR_PERCENT) + + +def _roster_floor(db: Session) -> int: + """敢拿这趟清单去改登录名时,清单里至少要有多少人;``0`` = 不设限。 + + Hub 在清库或重导的时候目录会突然只剩几个人(实测 2026-11-05 测试站一天之内从 100 人 + 掉到 1 人),这时"本地有、清单里没有"证明不了人已经走了,照着让位就是把上百个登录名 + 一次性刷成 ``hub-lost-*``。基准取这两个里**较小、但仍然可信**的那个: + + * 上一次同步记下来的人数(``hub_directory.total_users``); + * 本地带 ``hub_user_id`` 的账号数:它只增不减(离职只停用),所以哪怕上一趟同步已经 + 只看到七个人,"本地攒着几百号人"这件事仍然拦得住再一次的批量改名。 + + 不足熔断人数底线(``hub_sync_offboard_guard_min_people``)的数不当基准(小部署、 + 第一次同步没有参照物),两个都不可信就返回 0 放行。清单确实长期只有基准以下时会一直 + 挡着(比例由 ``hub_sync_roster_floor_percent`` 决定,默认一半):那时不让位等于 + 回到旧行为(撞车只报数、交人工核对),比悄悄改掉全库的登录名好。 + """ + baselines = [ + models.as_id(state(db).get("total_users")) or 0, + int( + db.execute( + select(func.count()) + .select_from(models.User) + .where(models.User.hub_user_id.is_not(None)) + ).scalar() + or 0 + ), + ] + cfg = hubconfig.get() + # 基准本身也要"可信":几十号人以下的参照物当不了下限的参照,沿用人员侧那条人数底线 + floor_base = _floor_value(cfg, "hub_sync_offboard_guard_min_people", OFFBOARD_GUARD_MIN_PEOPLE) + usable = [size for size in baselines if size >= floor_base] + percent = _floor_value(cfg, "hub_sync_roster_floor_percent", ROSTER_FLOOR_PERCENT) + return min(usable) * percent // 100 if usable else 0 + + +def _roster_wecom_owners(users: list[dict[str, Any]]) -> dict[str, int]: + """这一趟清单里「企业微信 UserID -> 号主 Hub 主键」,用来判断某个号现在该在谁身上。""" + owners: dict[str, int] = {} + for item in users: + if not isinstance(item, dict): + continue + hub_user_id = models.as_id(item.get("user_id")) + value, state = _hub_wecom_user_id(item) + if state == WECOM_OK and value and hub_user_id: + owners.setdefault(value, int(hub_user_id)) + return owners + + +def _retire_lost_accounts( + db: Session, + users: list[dict[str, Any]], + by_account: dict[str, models.User], + stats: SyncStats, + by_wecom_id: dict[str, models.User] | None = None, + *, + complete_roster: bool = False, +) -> None: + """把"本地已停用 + Hub 已查无此人"的同步账号从登录名上挪开,给 Hub 的现任主人让位。 + + 为什么会有这种账号:Hub 把人合并或重导之后,账号名会挪到另一个 ``user_id`` 上,而占着 + 这个名字的本地行绑的是那个已经被删掉的 ``user_id`` —— Hub 的变更流水只记 upsert、不记删除, + 本地根本等不到"这个人没了"的那条消息。``_plan_account_renames`` 的口径是"账号已经属于 + 另一个统一身份就不抢",于是活着的人永远拿不回 Hub 给他的账号名,每一趟同步都原样撞一次车, + 界面上就是同一个人两条:一条正常、登录名还是上辈子别人的,一条停用、占着正确的登录名。 + + 让位只动账号名,不动人:本地行、待办、审批轨迹、按主键挂的权限都原样留着,账号名换成 + ``hub-lost--<原名>``,按账号存的引用跟着这一行一起搬(``account_map`` 记的就是 + 这一跳,不做链式拼接,见 :func:`_record_pair`)。 + + 四道门槛,缺一个都不让位: + + * **这一趟清单人数对得上**:Hub 目录被清空或正在重导时(实测 2026-11-05 测试站一天之内 + 从 100 人掉到 1 人),"不在清单里"同样证明不了人走了,下限见 :func:`_roster_floor`; + * **调用方声明这一趟是完整清单**(``complete_roster=True``):``truncated`` 说明人没拉全, + 增量事件手里只有一条 payload,两种情况都证明不了"不在清单里"等于"Hub 查无此人"。 + 所以这个参数默认 ``False``,只有 ``sync_users`` 在清单没被截断时才传 ``True``—— + 一条人员事件就想改掉全库的登录名,是这里最贵的一种误伤; + * **本地这一行已经被停用过**:停用是上一趟同步(或管理员)已经做过的判断,账号名这才敢动。 + 刚发现"查无此人"的那一趟只停用,下一趟才让位,Hub 抖一下不至于把人的登录名也改了; + * **这一行是同步建/同步认领的**(``source=hub``):本地手工建的号哪怕在登录时被补绑过 + 一个 Hub 主键,账号名也是本地自己起的,轮不到同步去改;应急账号 + (``hub_local_accounts``)更不用提,那个名字就是它存在的意义。 + + ``hub_sync_reclaim_lost_accounts`` 关掉就退回老口径:一律不抢,撞车只报数,交人工核对。 + """ + cfg = hubconfig.get() + if not complete_roster or stats.truncated: + return # 清单没拉全 / 只搬来一条增量事件,"不在清单里"证明不了任何事 + roster = _roster_hub_ids(users) + floor = _roster_floor(db) + if len(roster) < floor: + # 清单人数比基准少得太离谱:Hub 多半在清库/重导,先不动任何人的登录名 + stats.note( + f"这一趟 Hub 清单只有 {len(roster)} 个人,不足可参照基准的 {_roster_floor_percent()}%" + f"({floor} 人):" + "Hub 多半正在清库或重导,「不在清单里」证明不了人已经走了," + "所以这一趟一个账号名都不让位。同步本身照写不误;" + "核对过 Hub 那边确实只剩这些人的话,下一趟会照常腾位置" + ) + return + lost = [ + (account, person) + for account, person in list(by_account.items()) + if _is_lost_account(cfg, person, roster) + ] + if not lost: + return + # 企业微信 UserID 也一起腾开:号被 Hub 挪给了另一个还活着的人,本地却压在一具僵尸行上, + # _apply_wecom_user_id 就永远判成"这个号已挂在别人身上"不敢写 —— 结果是活人的待办 + # 一直推到死号上,或者干脆推不到。清空只在清单明说"这个号现在归 user_id=X"时才做。 + wecom_owners = _roster_wecom_owners(users) + retired: list[tuple[str, str]] = [] + released_wecom: list[str] = [] + for account, person in lost: + staging = models.clip(f"{LOST_ACCOUNT_PREFIX}{int(person.hub_user_id)}-{account}", 190) + suffix = 2 + while staging in by_account: # 万一本地真有这么个账号,往后加号 + staging = models.clip(f"{LOST_ACCOUNT_PREFIX}{int(person.hub_user_id)}-{account}-{suffix}", 190) + suffix += 1 + person.account = staging + by_account.pop(account, None) + by_account[staging] = person + _record_pair(stats.account_map, account, staging) + retired.append((account, staging)) + stats.detail("reclaimed_accounts", f"{account} → {staging}") + held = person.wecom_user_id or "" + owner = wecom_owners.get(held) + if held and owner is not None and owner != int(person.hub_user_id or 0): + if by_wecom_id is not None and by_wecom_id.get(held) is person: + by_wecom_id.pop(held, None) + person.wecom_user_id = "" + released_wecom.append(held) + db.flush() + stats.reclaimed += len(retired) + stats.wecom_released += len(released_wecom) + # 让位的人不在这一趟清单里(正因如此才算查无此人),主循环不会替他们计数,这里自己补上: + # 否则改了 97 个登录名的一趟同步,在同步历史里仍然显示「无变更」 + stats.updated += len(retired) + stats.note( + f"{len(retired)} 个已停用的同步账号在 Hub 里已经查无此人,却一直占着登录名" + f"(账号名已改成 {LOST_ACCOUNT_PREFIX}user_id-原名 让位):" + f"例如 {retired[0][0]} → {retired[0][1]}。本地行、待办与按主键挂的权限都没动," + "按账号存的审批引用跟着这一行一起搬走了;它们腾开的账号名,这一趟会归回 Hub 的现任主人" + ) + if released_wecom: + stats.note( + f"其中 {len(released_wecom)} 个企业微信 UserID 也从这些僵尸账号上清空了" + f"(如 {released_wecom[0]}):Hub 说这些号现在属于别人," + "留着就等于把现任主人的待办推到已经不在这个人身上" + ) + + def _plan_account_renames( db: Session, users: list[dict[str, Any]], by_hub_id: dict[int, models.User], by_account: dict[str, models.User], stats: SyncStats, + by_wecom_id: dict[str, models.User] | None = None, + *, + complete_roster: bool = False, ) -> None: """把这一趟 Hub 要求的账号改名一次性排好再落库(见 ``_apply_account_renames``)。 分两遍扫:先收齐"Hub 要求换账号"的人,再判断目标账号是不是被一个不打算动的人占着。 一遍扫不行的原因是清单有先后 —— 甲要乙的账号、乙也要甲的账号时,先扫到的那个会以为 对面是"不动的人"而被判成撞车,结果两个人一个都没换成,而这其实是能换的(互换)。 + + 排之前先跑一遍 :func:`_retire_lost_accounts`:占着账号、但 Hub 里已经查无此人的停用行 + 不算"不动的人",让它先把名字腾开,否则下面每一个都要在它身上撞车,而且永远撞不好。 + 让位只在 ``complete_roster=True`` 时发生(见那个函数),增量事件传默认的 ``False``。 """ cfg = hubconfig.get() + _retire_lost_accounts(db, users, by_account, stats, by_wecom_id, complete_roster=complete_roster) holders = {account: person.id for account, person in by_account.items()} wanted: dict[int, tuple[models.User, str, str]] = {} for item in users: @@ -1255,9 +1794,11 @@ def _apply_wecom_user_id( ``by_wecom_id`` 是「企微 UserID -> 账号」的查重表:全量同步在内存里建一次(一趟 几百号人,逐条查库不值),增量事件传 ``None``、按值现查一次。 - 一个 UserID 只允许挂一个人。企微号被删掉再分配给别人时,Hub 会把同一个号发到新任 - 身上,本地照着写就变成两个账号共用一个收件地址——撞上就谁都不动、计数上报,交人工 - 核对:少发一条通知是小事,把张三的待办推到李四手机上是大事。 + **这一列是上游镜像,不是本地唯一键**:Hub 把同一个号同时发给几个人,本地就给几个人 + 都写上这个号,只在同步记录里报 ``wecom_conflicts`` 让人回企微通讯录核对。老口径是 + "一个号只挂一个人、撞上就后到的那个不写",代价是被让开的人这一列永远是空的 —— + 界面上分不清"Hub 没给号"和"Hub 给了、本地没敢写",按这一列找人的下游还会少找一个 + (实测 2026-11-05 测试站:``user_id=1`` 与 ``user_id=455`` 都带着 ``chenhao2``)。 """ value, state = _hub_wecom_user_id(item) if state == WECOM_ABSENT: @@ -1279,10 +1820,16 @@ def _apply_wecom_user_id( stats.wecom_returned += 1 if old == value: return False - holder = by_wecom_id.get(value) if by_wecom_id is not None else _wecom_holder(db, value) + if by_wecom_id is not None: + holder = by_wecom_id.get(value) + else: + # Session 是 ``autoflush=False`` 建的(app/db.py):同一批变更里前一条刚写上这个号、 + # 还没 flush,直接查库会查不到人,冲突就漏报了。问库之前先把这一笔刷出去。 + db.flush() + holder = _wecom_holder(db, value) if holder is not None and holder.id != person.id: + # 同一个号发给了几个人:照抄 Hub,后来的人一样挂上,只是把这件事报出来 stats.wecom_conflicts += 1 - return False if old and by_wecom_id is not None and by_wecom_id.get(old) is person: by_wecom_id.pop(old, None) person.wecom_user_id = value @@ -1298,6 +1845,9 @@ def _sync_people( unit_map: dict[int, int], stats: SyncStats, now: datetime, + *, + complete_roster: bool = False, + report: bool = True, ) -> set[int]: """Hub 扁平人员清单 -> ``users``,返回这次清单里出现的 Hub 主键。 @@ -1310,6 +1860,11 @@ def _sync_people( 本地账号(手工建的、或历史遗留的),认领后写 ``source=hub``; * 账号已经绑在别人身上就跳过并计数,绝不覆盖 ``hub_user_id``——那等于把两个人的 权限、待办、流程历史搅在一起; + (唯一的例外:占着这个名字的那一行如果**已停用、且这一趟完整清单里查无此人**, + 同步会先把它改名让位、再把账号名还给 Hub 的现任主人,见 :func:`_retire_lost_accounts`。 + 不加这一条,Hub 合并过一次人之后账号名就永久卡死了,每一趟都撞在同一个死号上。 + 让位只在全量同步里发生:调用方要用 ``complete_roster=True`` 明说"这就是 Hub 的全部人", + 增量事件一次只搬一个人,传默认的 ``False``,一个账号名都不会动。) * 已绑主键的人,账号跟着 Hub 改(新账号没人占用才改),姓名/邮箱/部门/状态一律以 Hub 为准。改走的旧账号会记进 ``account_map``,收尾时把按账号存的审批引用一起搬走。 * 手机号只在 Hub 这次**给了合法号码**时覆盖:Hub 的目录接口现在不一定下发这一列, @@ -1317,7 +1872,7 @@ def _sync_people( * 企业微信 UserID(``wecom_user_id``)跟着一起对齐,但比手机号多认一种情况:Hub 带着这个字段、值却是空的,那是 Hub 在说这个人没有企微号,本地跟着清空(企微号会 被删掉重新分配给别人,留着旧号等于把待办推给下一任);不带这个字段时照旧不碰。 - 一个号只认一个人,已经挂在别人身上就跳过并计数。 + Hub 把同一个号发给几个人,本地就给几个人都写上这个号,同时计数报出来。 两条护栏:``hub_sync_protect_admins`` 打开时**本地自建**的 ``role=admin`` 账号全程跳过 (防止 Hub 里没有 admin 时把自己锁在系统外);``hub_local_accounts`` 里的应急账号永远不 @@ -1337,7 +1892,8 @@ def _sync_people( by_wecom_id.setdefault(row.wecom_user_id, row) seen_ids: set[int] = set() - _plan_account_renames(db, users, by_hub_id, by_account, stats) + _plan_account_renames(db, users, by_hub_id, by_account, stats, by_wecom_id, + complete_roster=complete_roster) # 这一列这次到底有没有下发:清单里只要有一个人带过企微键就算下发了, # 于是"这个人没带"读成"这个人没企微号"(清空),而不是"接口没这个字段"(不动)。 @@ -1433,6 +1989,7 @@ def _sync_people( if person.display_name != display_name: if person.display_name: _record_pair(stats.display_name_map, person.display_name, display_name) + stats.detail("name_renames", f"{person.display_name} → {display_name}") person.display_name = display_name moved = True email = models.clip(str(item.get("email") or "").strip(), 190) @@ -1457,9 +2014,25 @@ def _sync_people( if person.status != status: person.status = status person.hub_synced_at = now - if moved: + if moved or person.id in stats.renamed_ids: + # 改名是 _plan_account_renames 提前落的,主循环这一趟可能再没动过别的列; + # 不把改名的人算进 updated,同步历史会把这趟写成「无变更」 stats.updated += 1 + if report: + _report_run_notes(stats) + return seen_ids + + +def _report_run_notes(stats: SyncStats) -> None: + """把这趟同步里"需要人来核对"的那几件事写进同步记录。 + + 这些计数字段是**整趟累计**的,所以一趟只许调用一次:全量同步在 + :func:`_sync_people` 末尾调,增量同步由 :func:`_pull_changes` 收尾时调一次。 + 以前它写在 ``_sync_people`` 里,而增量每条完整人员事件都要调一次这个函数, + 实测(2026-11-05 测试站一趟变更同步)同样两句提示在一条同步记录里重复了 5 遍, + 数字还停在第一次的「1 人」,看着像统计坏了。 + """ if stats.adopted: stats.note(f"认领本地同名账号 {stats.adopted} 个,已标记为统一身份账号(本地主键与权限不变)") if stats.renamed: @@ -1468,6 +2041,11 @@ def _sync_people( stats.note( f"{stats.conflicts} 人的账号在本地已属于另一个统一身份,本次跳过没有覆盖," "请人工核对是重复账号还是 Hub 数据错了" + + ( + "" + if not stats.reclaimed + else f"(已查无此人的那批已经让位腾出账号名,剩下的都是本地还有活人占着的)" + ) ) if stats.no_hub_id: stats.note(f"Hub 有 {stats.no_hub_id} 人没带 user_id(或没带账号),无法按主键认人,本次未处理") @@ -1501,10 +2079,11 @@ def _sync_people( ) if stats.wecom_conflicts: stats.note( - f"{stats.wecom_conflicts} 人的企业微信 UserID 已经挂在别的本地账号上,本次没有覆盖," - "请人工核对是企微号重新分配过、还是本地有重复账号;两个人共用一个号一定会推错人" + f"Hub 给 {stats.wecom_conflicts} 个人下发的企业微信 UserID 和别人是同一个号," + "本地照抄:共用这个号的几个人都挂着它,发给这个号会同时送达他们。" + "这是 Hub 那份通讯录本身的样子,不是本地有重复账号;" + "这个号该只归一个人收的话,请回企业微信通讯录把它改到一个人的名下" ) - return seen_ids def _offboard_missing(db: Session, seen_ids: set[int], stats: SyncStats, now: datetime) -> None: @@ -1513,11 +2092,18 @@ def _offboard_missing(db: Session, seen_ids: set[int], stats: SyncStats, now: da 判据只有 ``hub_user_id`` 这一个:以前还附带"账号也找不到",于是 Hub 里改了账号的人 会被判成离职、连带他的待办和权限一起停掉。现在账号只是普通字段,不参与身份判定。 没有主键的 ``source=hub`` 账号(历史遗留)不做离职判定,只报数量让人去补绑。 + + 停用的是"这一整批",所以带一道熔断:等着停用的人数超过 ``hub_sync_offboard_guard_percent`` + (且不少于 :data:`OFFBOARD_GUARD_MIN_PEOPLE`)时,这一趟一个都不停,只把人数报进同步记录、 + 并让这一趟以「部分完成」收口。判成离职这件事不可自动挽回 —— 下一趟同步只会把清单里的 + 人重新启用,指错了 Hub 的话那些被停的人永远回不来,所以宁可停下来问一句。 + 设成 0 关掉熔断,回到"照单全停"。 """ cfg = hubconfig.get() rows = db.execute( select(models.User).where(models.User.source == models.AccountSource.HUB) ).scalars().all() + pending: list[models.User] = [] for row in rows: if not row.hub_user_id: stats.unbound += 1 @@ -1530,6 +2116,28 @@ def _offboard_missing(db: Session, seen_ids: set[int], stats: SyncStats, now: da row.hub_synced_at = now if row.status == models.UserStatus.DISABLED: continue + pending.append(row) + # 熔断:Hub 换了一套数据(重导、合并,甚至只是把 hub_base_url 指到另一套环境)时, + # 本地这批 hub_user_id 会一次性全部"查无此人",照停用等于把整家公司判成离职 —— + # 权限、待办、部门负责人当场全没,而且下一趟同步不会自己长回来。 + # 宁可这一趟一个人都不动、把"本该停用多少人"报出来让人先看清单,也不要悄悄写下去。 + guard = int(cfg.hub_sync_offboard_guard_percent or 0) + if guard: + ceiling = max( + _floor_value(cfg, "hub_sync_offboard_guard_min_people", OFFBOARD_GUARD_MIN_PEOPLE), + len(rows) * guard // 100, + ) + if len(pending) > ceiling: + stats.offboard_guarded = len(pending) + stats.note( + f"{len(pending)} 人没出现在 Hub 清单里,超过离职停用熔断线" + f"({guard}%,本次上限 {ceiling} 人),这一趟一个人都没停用。" + "先看一眼 Hub 到底拉到了谁(系统设置 → 统一身份 → 同步前体检):" + "换过 Hub 站点或目录密钥、Hub 重导过人员,都会一次性撞上这一条;" + "确认清单没问题,再把 OA_HUB_SYNC_OFFBOARD_GUARD_PERCENT 调大或设成 0 关掉熔断" + ) + return + for row in pending: row.status = models.UserStatus.DISABLED stats.offboarded += 1 if stats.offboarded: @@ -1566,22 +2174,31 @@ def sync_users( raise HubSyncError("定时同步已关闭,请到「系统设置 → 同步定时任务」打开「允许定时同步」") lock_token = _acquire_sync_locks() - now = datetime.now() - member_limit = max(1, min(5000, int(cfg.hub_sync_member_limit or 2000))) - run = models.HubSyncRun( - trigger=trigger, - status=models.HubSyncRun.STATUS_RUNNING, - started_at=now, - operator=operator, - operator_name=operator_name, - member_limit=member_limit, - ) - db.add(run) - db.commit() - run_id = run.id + # 建「进行中」记录这一段在下面的 try 之外,所以它得自己负责交还锁:这里漏出去 + # 一次异常(库断了、死锁、补列没跟上导致 INSERT 报错),``_run_lock`` 就永久扣在 + # 这个进程上,之后每一次同步 —— 包括调度线程每几十秒那趟增量 —— 都只会回 + # 「已有同步任务正在执行,请稍后再试」,直到重启或有人按「终止」。 + try: + now = datetime.now() + member_limit = max(1, min(5000, int(cfg.hub_sync_member_limit or 2000))) + run = models.HubSyncRun( + trigger=trigger, + status=models.HubSyncRun.STATUS_RUNNING, + started_at=now, + operator=operator, + operator_name=operator_name, + member_limit=member_limit, + ) + db.add(run) + db.commit() + run_id = run.id + + stats = SyncStats(started_at=now) + stats.member_limit = member_limit + except Exception: + _release_sync_locks(lock_token) + raise - stats = SyncStats(started_at=now) - stats.member_limit = member_limit try: hub_client = hub_api.client() # 目录密钥走 X-Directory-Key 头(客户端自己加);这里拿到的 token 是老的 Bearer 口径, @@ -1622,7 +2239,10 @@ def sync_users( organizations = payload.get("organizations") if isinstance(payload.get("organizations"), list) else [] unit_map = _sync_units(db, organizations, stats) - seen_ids = _sync_people(db, hub_users, unit_map, stats, datetime.now()) + # complete_roster:清单没被 member_limit 截断,才敢说"不在清单里 = Hub 查无此人" + seen_ids = _sync_people( + db, hub_users, unit_map, stats, datetime.now(), complete_roster=not stats.truncated + ) _note_field_coverage(stats, bool(hub_users)) _raise_if_cancelled(stats) @@ -1638,7 +2258,8 @@ def sync_users( _carry_references(db, stats) - status = models.HubSyncRun.STATUS_PARTIAL if stats.truncated else models.HubSyncRun.STATUS_SUCCESS + # 被熔断挡下来的那一趟也是"没干完":一个都没停,别让它看起来像成功收工 + status = _run_status(stats) _finish(db, run_id, stats, status, ";".join(stats.messages)) return {"run": serialize_run(latest_run(db) or run), "skipped": False} except HubSyncCancelled as exc: @@ -1786,6 +2407,11 @@ def _finish( run.credential = stats.credential run.cursor_seq = int(stats.cursor_seq or 0) run.changes_applied = int(stats.changes_applied or 0) + run.renamed = int(stats.renamed or 0) + run.reclaimed = int(stats.reclaimed or 0) + run.units_rebound = int(stats.units_rebound or 0) + # details 里带完整提示原文,所以 message 被 2000 字裁掉也不会真的丢信息 + run.details = run_details(stats) run.message = (message or "")[:2000] if state_patch is not None: # 增量轮询只更新自己的那几个键,不碰 permission_version / total_users, @@ -1810,7 +2436,7 @@ def _finish( db.commit() logger.info( "Hub 同步 %s(%s,凭证 %s):人员 新增%d/更新%d/停用%d," - "部门 新增%d/更新%d/停用%d,版本 %s,member_limit %s%s", + "部门 新增%d/更新%d/停用%d/认回%d,版本 %s,member_limit %s%s", status, stats.total_users, stats.credential, @@ -1820,6 +2446,7 @@ def _finish( stats.units_created, stats.units_updated, stats.units_offboarded, + stats.units_rebound, stats.permission_version, stats.member_limit, "(已截断)" if stats.truncated else "", @@ -1999,7 +2626,9 @@ def _apply_user_event( # 在这里凭空补一个 None 进去,"这条事件没提企微号"就会被读成"这个人没有企微号"而清空本地值 for key in _wecom_keys_in(data): person_payload[key] = data[key] - _sync_people(db, [person_payload], unit_map, stats, now) + # complete_roster 用默认的 False:一条变更不是清单,一个账号名都不许让位; + # report=False 是同一条理由——提示写的是整趟累计数,由 _pull_changes 收尾时统一报一次 + _sync_people(db, [person_payload], unit_map, stats, now, report=False) return APPLIED if person is None: @@ -2025,7 +2654,20 @@ def _apply_user_event( elif not mobile: stats.mobile_invalid += 1 # 企微 UserID 与手机号走的是同一类补丁:先落列、同样不在这里短路。 + # 全量那趟的汇总提示由 _pull_changes 收尾统一报,这一条补丁只把**需要人来处理的两种** + # 当场说清楚:号撞在别人身上、以及带过来的值洗不出合法 UserID。正常改号与清空不刷提示。 + conflicts_before, invalid_before = stats.wecom_conflicts, stats.wecom_invalid wecom_changed = _apply_wecom_user_id(db, person, data, None, stats) + if stats.wecom_conflicts > conflicts_before: + stats.note( + f"{person.account} 这条事件带来的企业微信 UserID {person.wecom_user_id} " + "本地已经挂在别的账号上:照抄 Hub 两边都留着,发给这个号会同时送达他们," + "请回企业微信通讯录把它改到一个人的名下" + ) + elif stats.wecom_invalid > invalid_before: + stats.note( + f"{person.account} 这条事件带的企业微信字段洗不出合法 UserID,本地这一列原样保留" + ) if "organization_id" in data: hub_org_id = models.as_id(data.get("organization_id")) or 0 @@ -2231,20 +2873,27 @@ def _pull_changes( raise HubSyncError("增量同步已关闭(hub_sync.changes.enabled = false)") lock_token = _acquire_sync_locks() - now = datetime.now() - set_state(db, {"changes_poll_at": now.strftime("%Y-%m-%d %H:%M:%S")}) - run = models.HubSyncRun( - trigger=models.HubSyncRun.TRIGGER_CHANGES, - status=models.HubSyncRun.STATUS_RUNNING, - started_at=now, - operator=operator, - operator_name=operator_name, - ) - db.add(run) - db.commit() - run_id = run.id + # 同 :func:`sync_users`:写游标与建记录这两步出错了要自己把锁还回去,否则增量 + # 同步一轮失败就把整个进程的组织同步按死在「已有同步任务正在执行」上。 + try: + now = datetime.now() + set_state(db, {"changes_poll_at": now.strftime("%Y-%m-%d %H:%M:%S")}) + run = models.HubSyncRun( + trigger=models.HubSyncRun.TRIGGER_CHANGES, + status=models.HubSyncRun.STATUS_RUNNING, + started_at=now, + operator=operator, + operator_name=operator_name, + ) + db.add(run) + db.commit() + run_id = run.id + + stats = SyncStats(started_at=now) + except Exception: + _release_sync_locks(lock_token) + raise - stats = SyncStats(started_at=now) try: hub_client = hub_api.client() token, stats.credential = hub_api.sync_token(hub_client) @@ -2322,6 +2971,7 @@ def _pull_changes( patch["changes_applied_total"] = ( int(state(db).get("changes_applied_total") or 0) + stats.changes_applied ) + _report_run_notes(stats) _finish( db, run_id, @@ -2596,6 +3246,21 @@ def preview(db: Session, *, member_limit: int | None = None) -> dict[str, Any]: if row.source == models.AccountSource.HUB: hub_source.append(row) + # 僵尸账号让位(判据与同步完全一致,见 _is_lost_account):这些行会把登录名腾开, + # 原本压在它们身上的"账号撞车"下一趟就不再发生了。预检必须按腾开之后的样子报, + # 否则界面上永远列一堆同步根本不会再撞的冲突,让人白核对一轮。 + # 清单被截断、或人数比基准少得太离谱(Hub 在清库/重导)的那一趟不让位,预检跟着不算。 + roster_ids = _roster_hub_ids(hub_users) + roster_floor = _roster_floor(db) + releases_allowed = not truncated and len(roster_ids) >= roster_floor + released_accounts: set[str] = set() + if releases_allowed: + released_accounts = { + row.account + for row in hub_source + if row.account and _is_lost_account(cfg, row, roster_ids) + } + # 手机号预检:界面要能回答"同步完手机上会有号码吗"——取决于 Hub 下不下发这一列 mobile_returned = 0 mobile_invalid = 0 @@ -2616,6 +3281,7 @@ def preview(db: Session, *, member_limit: int | None = None) -> dict[str, Any]: unassigned = 0 protected = 0 conflicts = 0 + released = 0 no_id = 0 account_map: dict[str, str] = {} person_name_map: dict[str, str] = {} @@ -2645,6 +3311,11 @@ def preview(db: Session, *, member_limit: int | None = None) -> dict[str, Any]: holder = by_account.get(account) if holder is None: new_people += 1 + elif holder.account in released_accounts: + # 占着这个账号的是"Hub 已查无此人"的停用同步号:同步会把它的登录名腾开, + # 于是这个人按清单里的账号建号,不算撞车 + released += 1 + new_people += 1 elif holder.hub_user_id: # 账号已经代表 Hub 里的另一个人了,同步会跳过,不会把两个人并起来 conflicts += 1 @@ -2660,8 +3331,39 @@ def preview(db: Session, *, member_limit: int | None = None) -> dict[str, Any]: and int(row.hub_user_id) not in seen_ids and not (cfg.hub_sync_protect_admins and row.role == models.ROLE_ADMIN) ] + # 熔断预演:跟 _offboard_missing 用同一套算法,预检说"会被挡"就必须真跑也会被挡。 + # 这里只数"还没停用的",已经是停用状态的不构成一次新的停用。 + offboard_pending = [ + row.account + for row in hub_source + if row.hub_user_id + and int(row.hub_user_id) not in seen_ids + and row.status != models.UserStatus.DISABLED + and not (cfg.hub_sync_protect_admins and row.role == models.ROLE_ADMIN) + ] + offboard_guard = int(cfg.hub_sync_offboard_guard_percent or 0) + guard_min_people = _floor_value(cfg, "hub_sync_offboard_guard_min_people", OFFBOARD_GUARD_MIN_PEOPLE) + guard_min_units = _floor_value(cfg, "hub_sync_unit_offboard_guard_min", UNIT_OFFBOARD_GUARD_MIN) + offboard_ceiling = ( + max(guard_min_people, len(hub_source) * offboard_guard // 100) if offboard_guard else 0 + ) + offboard_guarded = bool(offboard_guard) and len(offboard_pending) > offboard_ceiling unbound = len([row for row in hub_source if not row.hub_user_id]) + # 部门侧:会停用哪些、熔断挡不挡、Hub 换过主键之后本地留了几具重名的壳子 + unit_pending = [ + known_units[hub_id] + for hub_id in set(known_units) - org_ids + if known_units[hub_id].status != models.UnitStatus.DISABLED + ] + unit_ceiling = ( + max(guard_min_units, len(known_units) * offboard_guard // 100) if offboard_guard else 0 + ) + unit_guarded = bool(offboard_guard) and len(unit_pending) > unit_ceiling + # 重名壳子:判据与「一键清理」共用同一个函数,预检报了的数量必须真删得掉 + zombie_units = find_shell_units(known_units.values(), roster_org_ids=org_ids) + zombie_blocked = {unit.id: shell_unit_blockers(db, unit) for unit in zombie_units} + # 影响预检:Hub 一改名字就会牵动的"按字符串存的"配置(审批岗位、共享名单…)。 # 权限角色与数据范围是按 users.id / oa_unit.id 挂的,同步不动主键,所以不在这里出现。 refs_total, refs_samples = hub_refs.scan( @@ -2673,6 +3375,39 @@ def preview(db: Session, *, member_limit: int | None = None) -> dict[str, Any]: ), ) + warnings: list[str] = [] + if truncated: + warnings.append( + f"人员清单被 member_limit={limit} 截断,本次数字只能当规模参考," + "正式同步前先调大 OA_HUB_SYNC_MEMBER_LIMIT" + ) + if offboard_guarded: + warnings.append( + f"有 {len(offboard_pending)} 人会被判成离职,超过熔断线" + f"({offboard_guard}% / 上限 {offboard_ceiling} 人):真同步时这一趟一个人都不停用。" + "先核对 Hub 拉到的是不是这套环境该有的人(换过站点或目录密钥最容易撞上)," + "确认没问题再把 OA_HUB_SYNC_OFFBOARD_GUARD_PERCENT 调大或设 0" + ) + if unit_guarded: + warnings.append( + f"有 {len(unit_pending)} 个部门会被判成「Hub 已消失」而停用,超过部门停用熔断线" + f"({offboard_guard}% / 上限 {unit_ceiling} 个):真同步时这一趟一个部门都不停。" + "停一个部门会连带摘掉它下面所有人的数据范围与按部门配的审批规则,先核对组织清单" + ) + if not releases_allowed and not truncated: + warnings.append( + f"Hub 这次只回了 {len(roster_ids)} 个人,不足可参照基准的 {_roster_floor_percent()}%" + f"({roster_floor} 人):目录像是在清空或重导," + "真同步时这一趟不会动任何人的登录名(account_releases=0)," + "但清单里没有的人照样会被停用,先核对 Hub 那边的人对不对得上" + ) + if zombie_units: + warnings.append( + f"本地有 {len(zombie_units)} 个已停用的部门跟在职部门重名" + f"(例如 {zombie_units[0].name}):那是 Hub 换过 organization_id 留下的壳子," + "同步不会再认它们也不会自动合并,要清掉得先在部门上解绑再删除" + ) + return { "credential": mode, "credential_label": credential_label(mode), @@ -2687,6 +3422,29 @@ def preview(db: Session, *, member_limit: int | None = None) -> dict[str, Any]: "known": len(org_ids & set(known_units)), "disabled": len([row for row in orgs if row["status"] != models.UnitStatus.ACTIVE]), "offboard_candidates": len(set(known_units) - org_ids), + # 真会被这一趟停用的部门,以及熔断挡不挡得住(口径与人员那侧同一个百分比) + "offboard_pending": len(unit_pending), + "offboard_guard": { + "percent": offboard_guard, + "ceiling": unit_ceiling, + "min_units": guard_min_units, + "tripped": unit_guarded, + }, + # Hub 换过 organization_id 之后留在树上的重名壳子:编码与名称都已被在职部门占用, + # 同步不会再认它们,也不会自动合并,需要在部门里手工处理 + "zombie_units": len(zombie_units), + "zombie_unit_samples": [ + { + "id": unit.id, + "name": unit.name, + "code": unit.code, + # 非空 = 这一具删不掉(还有人/有下级/被角色当数据范围),界面要说清为什么 + "blockers": zombie_blocked[unit.id], + } + for unit in zombie_units[:5] + ], + # 能一键删掉的那几具(其余要先把人挪走、下级删掉或改角色数据范围) + "zombie_units_deletable": len([1 for reasons in zombie_blocked.values() if not reasons]), "renamed": renamed_units, "moved": moved_units, # 本系统自己加的部门:同步不碰它们,只报规模与风险 @@ -2701,8 +3459,22 @@ def preview(db: Session, *, member_limit: int | None = None) -> dict[str, Any]: "unassigned": unassigned, "protected_admins": protected, "offboard_candidates": len(offboard_candidates), + # 真会被这一趟停用的只有还没停用的那批,以及熔断挡不挡得住 + "offboard_pending": len(offboard_pending), + "offboard_guard": { + "percent": offboard_guard, + "ceiling": offboard_ceiling, + "min_people": guard_min_people, + "tripped": offboard_guarded, + }, "no_hub_id": no_id, "account_conflicts": conflicts, + # 会让位腾出登录名的僵尸同步号(Hub 已查无此人 + 本地已停用) + "account_releases": released, + # 这一趟到底让不让位:清单人数不够就说明 Hub 目录可疑,账号名原地留着 + "account_releases_allowed": releases_allowed, + "account_release_floor": roster_floor, + "account_release_floor_percent": _roster_floor_percent(), "account_renames": len(account_map), "name_renames": len(person_name_map), "unbound": unbound, @@ -2739,12 +3511,7 @@ def preview(db: Session, *, member_limit: int | None = None) -> dict[str, Any]: }, "offboard_accounts": offboard_candidates[:20], "organization_sample": orgs[:10], - "warning": ( - f"人员清单被 member_limit={limit} 截断,本次数字只能当规模参考," - "正式同步前先调大 OA_HUB_SYNC_MEMBER_LIMIT" - if truncated - else "" - ), + "warning": ";".join(warnings), } diff --git a/backend/app/service/outbox.py b/backend/app/service/outbox.py index 50948ad..544be38 100644 --- a/backend/app/service/outbox.py +++ b/backend/app/service/outbox.py @@ -19,12 +19,13 @@ import time from datetime import datetime, timedelta from typing import Any, Callable -from sqlalchemy import event, select, update +from sqlalchemy import select, update from sqlalchemy.orm import Session from .. import models from .. import cache, presence from . import dicts, fetch, mapping +from . import wake as wake_signal logger = logging.getLogger("unisoa.outbox") @@ -60,57 +61,24 @@ DECLARED_TTL_SECONDS = 15.0 # 入队当场叫醒投递线程 # --------------------------------------------------------------------------- -#: 会话上"这一趟提交里放过新报文"的记号(``Session.info`` 正是给这种挂用途留的) -WAKE_KEY = "outbox_wake" -#: 谁在听"刚入队了一条报文":``app.main`` 登记的是"把调度线程叫醒", -#: 广播那条回调也接到这里,于是多副本下别的副本入队同样当场起。 -_wake_hooks: list[Callable[[], None]] = [] - +#: 叫醒通路本身搬到 :mod:`service.wake` 了。写回、消息渠道、事件订阅排的是**同一条** +#: 调度线程,"提交之后才叫、回滚不叫、跨副本广播一条"这套记账不该有三份——而且它 +#: 原先只有这一份,结果渠道与事件两路只能干等下一个轮询周期(实测一条企微推送 +#: 白等 28~60 秒)。下面两个同名薄壳留着,调用点与 ``scripts/check_outbox_wake.py`` +#: 一字不改,读代码的人在写回这里也仍然看得见"什么时候叫醒"。 def wake(handler: Callable[[], None]) -> None: """登记一个"现在就有活干"的回调。它必须便宜且幂等:叫一次和叫三次得是同一件事。""" - _wake_hooks.append(handler) - - -def _wake_now() -> None: - """叫醒所有登记过的监听者。叫不醒只是慢,不是丢:轮询那条路照旧兜底。""" - for hook in list(_wake_hooks): - try: - hook() - except Exception: # pragma: no cover - defensive - logger.debug("叫醒写回投递线程失败,等下一个轮询周期", exc_info=True) + wake_signal.hook(handler) def _mark_wake(db: Session) -> None: - """记一笔"这条会话提交过新报文",**但不在这里叫醒**。 + """记一笔"这条会话排过新报文",**但不在这里叫醒**。 - 入队与状态变更是同一个事务:事务还没提交就把投递线程叫起来,它只会跑一趟空 - (那条报文此刻对别的连接还不可见),所以等 ``after_commit`` 再叫。 + 入队与状态变更是同一个事务:没提交就把投递线程叫起来,它只会跑一趟空(那条报文 + 此刻对别的连接还不可见),所以等 ``after_commit`` 再叫。 """ - db.info[WAKE_KEY] = True - - -@event.listens_for(Session, "after_commit") -def _after_commit(session: Session) -> None: - """单子真的落库了才叫醒:本进程的叫醒回调 + 一条广播,让别的副本也当场起来。""" - if not session.info.pop(WAKE_KEY, None): - return - _wake_now() - cache.publish(cache.TOPIC_OUTBOUND, "enqueued") - - -@event.listens_for(Session, "after_rollback") -def _after_rollback(session: Session) -> None: - """单没过,报文跟着一起回滚:这一趟不算数,别把投递线程空叫一次。""" - session.info.pop(WAKE_KEY, None) - - -def _on_shared_enqueue(_payload: Any = None) -> None: - """别的副本入队了一条报文:本进程的投递线程也起来看一眼(幂等,自己那条也会收到)。""" - _wake_now() - - -cache.watch(cache.TOPIC_OUTBOUND, _on_shared_enqueue) + wake_signal.mark(db) # --------------------------------------------------------------------------- diff --git a/backend/app/service/wake.py b/backend/app/service/wake.py new file mode 100644 index 0000000..ed6e1a2 --- /dev/null +++ b/backend/app/service/wake.py @@ -0,0 +1,85 @@ +"""外发任务一入队就把投递线程叫醒 -- 三条外发路共用这一个通路。 + +为什么要单独一层 +================ +写回发件箱(:mod:`outbox`)、消息渠道(:mod:`channels`)、事件订阅(:mod:`events`) +是同一种活:与业务状态**同一事务**入队,真发交给后台调度线程,失败按退避重试。 +叫醒线程这件事原本只写在 ``outbox`` 里,于是另外两路只能等下一个轮询周期—— +本部署 ``oa_notify_delivery`` 上量得出来:一条企业微信推送从入队到发出去等了 +28~60 秒,而真发那一次只用 1 秒。**慢的不是发送,是没人叫醒。** + +规则 +==== +* **提交之后才叫**:入队与状态变更是同一个事务,事务没提交就把线程叫起来,它只会 + 跑一趟空(那条任务此刻对别的连接还不可见)。所以 :func:`mark` 只记账, + ``after_commit`` 才真叫。 +* **回滚不叫**:单没过,任务跟着一起回滚,这一趟不算数。 +* **叫不醒只是慢,不是丢**:15/60 秒那一档轮询照旧跑(``main._scheduler_tick_seconds``), + 这一层只把"最多等多久"从一分钟压到当下。 +* **多副本一起叫**:本进程直接置事件,别的副本靠 :mod:`app.cache` 的广播。话题沿用 + 原来那条 ``outbound``,于是滚动发布时新旧副本互相都听得见。 +* 回调必须便宜且幂等:叫一次和叫三次得是同一件事。 +""" + +from __future__ import annotations + +import logging +from typing import Any, Callable + +from sqlalchemy import event +from sqlalchemy.orm import Session + +from .. import cache + +logger = logging.getLogger("unisoa.wake") + +#: 会话上"这一趟提交里排过新外发任务"的记号(``Session.info`` 正是给这种挂用途留的) +WAKE_KEY = "delivery_wake" +#: 谁在听"刚排上了一条外发任务":``app.main`` 登记的是"把调度线程叫醒", +#: 广播那条回调也接到这里,于是多副本下别的副本排上的任务同样当场起。 +_hooks: list[Callable[[], None]] = [] + + +def hook(handler: Callable[[], None]) -> None: + """登记一个"现在就有活干"的回调。它必须便宜且幂等:叫一次和叫三次得是同一件事。""" + _hooks.append(handler) + + +def now() -> None: + """叫醒所有登记过的监听者。叫不醒只是慢,不是丢:轮询那条路照旧兜底。""" + for item in list(_hooks): + try: + item() + except Exception: # pragma: no cover - defensive + logger.debug("叫醒投递线程失败,等下一个轮询周期", exc_info=True) + + +def mark(db: Session) -> None: + """记一笔"这条会话排过新外发任务",**但不在这里叫醒**(等提交,见模块头)。 + + 入队方只管在自己确认加了行的那一支调用它,一次事务里调几次都一样。 + """ + db.info[WAKE_KEY] = True + + +@event.listens_for(Session, "after_commit") +def _after_commit(session: Session) -> None: + """任务真的落库了才叫醒:本进程的叫醒回调 + 一条广播,让别的副本也当场起来。""" + if not session.info.pop(WAKE_KEY, None): + return + now() + cache.publish(cache.TOPIC_OUTBOUND, "enqueued") + + +@event.listens_for(Session, "after_rollback") +def _after_rollback(session: Session) -> None: + """单没过,任务跟着一起回滚:这一趟不算数,别把投递线程空叫一次。""" + session.info.pop(WAKE_KEY, None) + + +def _on_shared_wake(_payload: Any = None) -> None: + """别的副本排上了一条任务:本进程的投递线程也起来看一眼(幂等,自己那条也会收到)。""" + now() + + +cache.watch(cache.TOPIC_OUTBOUND, _on_shared_wake) diff --git a/backend/config.toml b/backend/config.toml index fe2aa89..a73b141 100644 --- a/backend/config.toml +++ b/backend/config.toml @@ -49,7 +49,7 @@ # 永远读不到(文件路径本身就是它决定的),后端会在日志里提醒一句并忽略。 # ----------------------------------------------------------------------------- [env] -name = "dev" +name = "prod" # ----------------------------------------------------------------------------- # 哪些项必须写在 config.<环境名>.toml 里(本文件不放,放了也是被盖住的那一层): diff --git a/backend/config.toml.example b/backend/config.toml.example index a2526a4..9de057f 100644 --- a/backend/config.toml.example +++ b/backend/config.toml.example @@ -311,6 +311,10 @@ apps = "/api/v1/auth/apps" # 发起免登跳转(OA_HUB_PATH_LAUNCH):POST {base_url}{launch}, # {code} 调用时换成本系统的应用编码(app_code) launch = "/api/v1/auth/apps/{code}/launch" +# 企业微信消息推送(OA_HUB_PATH_NOTIFY_WECOM):POST {base_url}{notify_wecom} 发消息, +# GET 同一路径 + /{msg_key} 回查逐人投递结果;用的就是上面免登那把 X-Integration-Key, +# 本系统不持有企业微信密钥。「消息通知」里的 hub_wecom 渠道走这一条(见 docs/hub-integration.md §15) +notify_wecom = "/api/v1/auth/notify/wecom/messages" # ----------------------------------------------------------------------------- # 【出厂模板】组织人员同步:系统设置页 →「同步定时任务」,保存即生效 @@ -349,6 +353,31 @@ include_disabled_units = true # Hub 里已消失的同步账号置为「已停用」(OA_HUB_SYNC_OFFBOARD)。 # 只停用不删除,本地账号永不受影响 offboard = true +# 离职停用熔断(OA_HUB_SYNC_OFFBOARD_GUARD_PERCENT,取值 0-95):一趟同步里等着停用的人 +# 超过本地同步账号总数的这个百分比、并且超过 20 人时,这一趟一个人都不停用,只报数并把 +# 该趟标成「部分完成」。Hub 换环境、重导数据、或目录清单出问题时最容易撞上——它会把整家 +# 公司一次性判成离职,而权限与待办不会自己长回来。核对过清单确实没错,再调大或设 0 关掉。 +# 同一个百分比也管部门侧:一趟要停用的部门超过 max(5, 同步部门数 × 百分比) 时一个都不停 +offboard_guard_percent = 40 +# 熔断线的人数底线(OA_HUB_SYNC_OFFBOARD_GUARD_MIN_PEOPLE,取值 0-5000):熔断线取 +# 「同步账号总数 × 百分比」与这个数里的较大者,所以小部署裁掉几个人不会被比例挡下来。 +# 几十人的团队想让它更早触发就调小,上千人的部署嫌 20 太松可以调大;0 = 只看百分比 +offboard_guard_min_people = 20 +# 部门侧熔断线的个数底线(OA_HUB_SYNC_UNIT_OFFBOARD_GUARD_MIN,取值 0-5000):部门总数比 +# 人少一个量级,沿用人员那侧的 20 这条线永远不会触发,等于没有熔断。0 = 只看百分比 +unit_offboard_guard_min = 5 +# 让"已查无此人"的账号腾出登录名(OA_HUB_SYNC_RECLAIM_LOST_ACCOUNTS)。Hub 合并/重导人员后 +# 会把账号名挪到另一个 user_id 上,占着名字的本地行绑的却是已删除的 user_id(Hub 的变更 +# 流水不记删除),同步又不许抢别人的账号,活着的人就永远拿不回登录名、每一趟都撞一次车。 +# 打开后,"本地已停用 + 这一趟完整清单里查无此人"的同步账号会把名字腾开(改成 +# hub-lost--<原名>),人、待办、按主键挂的权限都不动。关掉就退回"只报数不处理" +reclaim_lost_accounts = true +# 让位名单的清单人数下限(OA_HUB_SYNC_ROSTER_FLOOR_PERCENT,取值 0-100):Hub 这次回的 +# 人员数不足「可参照基准 × 这个百分比」时,认定目录正在被清空或重导,这一趟一个登录名 +# 都不让位(撞车照旧只报数)。基准取「上次同步记下的人数」与「本地带 Hub 主键的账号数」 +# 里较小但仍然可信的那个。实测 2026-11-05 测试站一天之内从 100 人掉到 1 人,靠这一条 +# 挡住了把上百个登录名一次性刷成 hub-lost-*。0 = 不设下限 +roster_floor_percent = 50 # permission_version 与上次一致时跳过写入(OA_HUB_SYNC_SKIP_UNCHANGED)。 # 只作用于排期跑的那趟;界面上的「立即同步」永远强拉 skip_unchanged = true diff --git a/backend/scripts/check_detail_export.py b/backend/scripts/check_detail_export.py new file mode 100644 index 0000000..f13eb2b --- /dev/null +++ b/backend/scripts/check_detail_export.py @@ -0,0 +1,621 @@ +#!/usr/bin/env python3 +"""守「流程明细导出」那套口径,重点是**未操作者到底算谁没操作**。 + +这一页看着只是"多一个导出按钮",真正常被问的是筛选条件里那句"未操作者包含张三"—— +张三待办没办算不算、待阅没打开算不算、抄送需处理只打开没回意见算不算、单子被终止 +那一刻他还没表态算不算。这些口径一旦漂,导出来的台账和当事人印象对不上,财务拿着 +这张表去催办就催错人。脚本盯的十一条: + +1. 四条接口挂的是独立权限码 ``monitor:export``,与 ``monitor:work`` 互不为前置; +2. 数据范围照旧生效:管不到的人,单子导不出来; +3. 待办未处理算未操作,办完就不算; +4. 待阅**没打开**才算,打开过就不算; +5. 抄送需处理:打开过但没回意见,**仍旧算**;回了意见才算完; +6. 归档之后那条没打开的待阅照旧查得出来(引擎不迁没看过的待阅); +7. 终止的单算在**被强行结掉那条待办的持有人**头上,不算动手终止的人; +8. 前置加签未激活默认不算,勾上才算;转办/代理不冤枉原持有人; +9. 归档日期只作用在归档表那一半,在途那一半给空集而不是报错; +10. 「相关核算项目」按名称与按编码命中同一批单(库里存编码、界面上念名称); +11. 分表模式一条流程一个 sheet、各用各的表头;合并模式同 key 归并成一列; + 两种模式行数一致,CSV 拒绝分表。 + +库里不留东西:全程在一个未提交的事务里跑,收尾 ``rollback``:: + + PYTHONPATH=. python3 scripts/check_detail_export.py +""" + +from __future__ import annotations + +import pathlib +import sys + +sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent)) + +from datetime import datetime, timedelta # noqa: E402 + +from sqlalchemy import delete, select # noqa: E402 + +from app import models # noqa: E402 +from app import permissions as permissions_module # noqa: E402 +from app.db import SessionLocal # noqa: E402 +from app.deps import CurrentUser # noqa: E402 +from app.main import app # noqa: E402 +from app.service import detail_export as de # noqa: E402 + +STAMP = datetime.now().strftime("%m%d%H%M%S") +P_1 = f"__dex_p1_{STAMP}" +P_2 = f"__dex_p2_{STAMP}" +ME = f"__dex_me_{STAMP}" +PEER = f"__dex_peer_{STAMP}" +BOSS = f"__dex_boss_{STAMP}" +NAMES = {} # 账号 -> 姓名,seed() 里填 +UNIT = int(f"9{STAMP}") +PROJECT_DICT = f"__dex_dict_{STAMP}" +BASE = datetime(2026, 3, 1, 9, 0, 0) +PROJECT_CODE = f"PRJ{STAMP}" +PROJECT_LABEL = f"三号核算项目{STAMP}" + +FAILS: list[str] = [] +PASSED = 0 + + +def check(label: str, condition, detail: str = "") -> None: + global PASSED + if condition: + PASSED += 1 + print(f"[通过] {label}") + else: + FAILS.append(label) + print(f"[FAIL] {label}" + (f" -> {detail}" if detail else "")) + + +# --------------------------------------------------------------------------- +# 造数据 +# --------------------------------------------------------------------------- + +def form_content(*keys: tuple[str, str, str]) -> dict: + """一张最小可用的表单。``fields_of`` 只认 ``content.fields`` 那一层,别照设计器的 + 排版结构造——排版壳子换了多少次,字段清单这一层一直没变过。""" + fields = [] + for key, label, kind in keys: + field = {"key": key, "label": label, "type": kind} + if key == "accountProject": + field["dictCode"] = f"dex_{STAMP}" # 库里存编码、界面上念名称那一类 + fields.append(field) + return {"fields": fields} + + +def seed(db) -> dict[str, str]: + """两条流程、一张在途单与一张归档单,外加各口径的待办 / 待阅。""" + db.add(models.DictType(id=PROJECT_DICT, code=f"dex_{STAMP}", name="明细导出项目字典", enabled=True)) + # DictItem.type 存的是字典码而不是 DictType 主键(口径见 dicts.item_rows) + db.add(models.DictItem(id=f"{PROJECT_DICT}-1", type=f"dex_{STAMP}", value=PROJECT_CODE, label=PROJECT_LABEL)) + db.add(models.Unit(id=UNIT, name=f"明细导出部门{STAMP}", code=f"dexu{STAMP}", status=1)) + for account, name in ((ME, "经办人"), (PEER, "同级"), (BOSS, "终止人")): + NAMES[account] = name + db.add(models.User( + account=account, display_name=name, password_hash="x", + role=models.ROLE_MEMBER, status=1, organization_id=UNIT, + )) + form_one = f"__dex_form_1_{STAMP}" + form_two = f"__dex_form_2_{STAMP}" + db.add(models.FormElement(id=form_one, name=f"明细导出表一{STAMP}", version=1, content=form_content( + ("applyDept", "申请部门", "text"), + ("checkTotal", "报销金额", "number"), + ("accountProject", "相关核算项目", "select"), + ))) + db.add(models.FormElement(id=form_two, name=f"明细导出表二{STAMP}", version=1, content=form_content( + ("applyDept", "申请部门", "text"), + ("loanReason", "借款事由", "text"), + ))) + for pid, name, form in ((P_1, f"明细导出流程甲{STAMP}", form_one), (P_2, f"明细导出流程乙{STAMP}", form_two)): + db.add(models.Process( + id=pid, name=name, alias=name, category=f"__dex_cat_{STAMP}", category_name="明细导出分类", + enabled=True, published=True, latest_form=form, start_identity_list=["*"], + )) + db.add(models.Activity( + id=f"__dex_act_1_{STAMP}", process=P_1, type="manual", name="部门主管", order_number=1, form=form_one)) + db.add(models.Activity( + id=f"__dex_act_2_{STAMP}", process=P_1, type="manual", name="财务复核", order_number=2, form=form_one)) + + data = {"accountProject": PROJECT_CODE, "applyDept": "软件开发事业部", "checkTotal": "1200"} + db.add(models.Work( + job=f"__dex_job_1_{STAMP}", serial=f"DEX1{STAMP}", title=f"明细导出在途单{STAMP}", status="running", + process=P_1, process_name=f"明细导出流程甲{STAMP}", category=f"__dex_cat_{STAMP}", category_name="明细导出分类", + form=form_one, data=dict(data), + creator=ME, creator_person="经办人", creator_identity=ME, creator_identity_name="经办人", + creator_unit=UNIT, creator_unit_name=f"明细导出部门{STAMP}", + activity=f"__dex_act_1_{STAMP}", activity_name="部门主管", current_activity_names="部门主管", + manual_identity_text="经办人", start_time=BASE - timedelta(days=4), + )) + db.add(models.WorkCompleted( + job=f"__dex_job_2_{STAMP}", serial=f"DEX2{STAMP}", title=f"明细导出归档单{STAMP}", status="completed", + process=P_1, process_name=f"明细导出流程甲{STAMP}", category=f"__dex_cat_{STAMP}", category_name="明细导出分类", + form=form_one, data=dict(data), result="agree", + creator=ME, creator_person="经办人", creator_identity=ME, creator_identity_name="经办人", + creator_unit=UNIT, creator_unit_name=f"明细导出部门{STAMP}", + current_activity_names="", start_time=BASE - timedelta(days=12), finish_time=BASE - timedelta(days=2), + duration=864000, + )) + # 另一条流程的一张在途单:分表模式要拿它验"各自的表头各写各的" + db.add(models.Work( + job=f"__dex_job_3_{STAMP}", serial=f"DEX3{STAMP}", title=f"明细导出另一条流程{STAMP}", status="running", + process=P_2, process_name=f"明细导出流程乙{STAMP}", category=f"__dex_cat_{STAMP}", category_name="明细导出分类", + form=form_two, data={"applyDept": "软件开发事业部", "loanReason": "出差借款"}, + creator=ME, creator_person="经办人", creator_identity=ME, creator_identity_name="经办人", + creator_unit=UNIT, creator_unit_name=f"明细导出部门{STAMP}", + activity=f"__dex_act_1_{STAMP}", activity_name="部门主管", current_activity_names="部门主管", + manual_identity_text="经办人", start_time=BASE - timedelta(days=1), + )) + db.flush() + return {"formOne": form_one, "formTwo": form_two, "data": data} + + +def add_task(db, job: str, *, identity: str, activity: str, kind: str = "plain", + arrived: datetime | None = None, view_time: datetime | None = None) -> None: + """一条待办。``kind``: plain / add_pending / transfer。""" + row = models.Task( + job=job, work=f"__dex_job_1_{STAMP}", title=f"明细导出在途单{STAMP}", status="running", + process=P_1, process_name=f"明细导出流程甲{STAMP}", serial=f"DEX1{STAMP}", + activity=f"__dex_act_1_{STAMP}", activity_name=activity, activity_type="manual", + person=identity, identity=identity, identity_name=NAMES[identity], unit=UNIT, unit_name="明细导出部门", + start_time=arrived or (BASE - timedelta(days=3)), view_time=view_time, + expired=bool(arrived and arrived < BASE - timedelta(days=2)), + ) + if kind == "add_pending": + row.add_task_from = "before_pending" + if kind == "transfer": + row.empower_from_identity = BOSS + row.label = "转办" + db.add(row) + + +def add_read(db, job: str, *, identity: str, requires: bool, view: bool = False, handle: bool = False, + completed: bool = False) -> None: + """一条待阅。归档单上"没打开过的待阅"在库里就是这样留在 ``oa_read`` 的。""" + db.add(models.Read( + job=job, work=job, completed=completed, title=f"明细导出单{STAMP}", process=P_1, + process_name=f"明细导出流程甲{STAMP}", serial="DEX", activity=f"__dex_act_1_{STAMP}", + activity_name="部门主管", person=identity, identity=identity, identity_name=NAMES[identity], unit=UNIT, + requires_action=requires, start_time=BASE - timedelta(days=3), + view_time=BASE - timedelta(days=1) if view else None, + handle_time=BASE - timedelta(days=1) if handle else None, + )) + + +def unop(db, jobs: list[str], kinds=de.DEFAULT_KINDS, locked=()) -> dict[str, de.Unop]: + return de.unoperators(db, jobs, kinds, locked) + + +def persons_of(item: de.Unop) -> list[str]: + return [str(row.get("person") or "") for row in item.rows] + + +def kinds_of(item: de.Unop) -> list[str]: + return sorted({str(row.get("kind") or "") for row in item.rows}) + + +# --------------------------------------------------------------------------- +# 主流程 +# --------------------------------------------------------------------------- + +def main() -> int: + # 1. 权限码:独立一码,且两条路由链都挂上了它 + listed = {item.code for item in permissions_module.CATALOG} + check("monitor:export 进了权限目录", "monitor:export" in listed) + check("它挂在 system 这一组里(与流程监控同一组)", + any(item.code == "monitor:export" and item.group == "system" for item in permissions_module.CATALOG)) + builtin_missing = [ + role.name for role in permissions_module.BUILTIN_ROLES + if "monitor:export" in (role.permissions or []) + ] + check("内置角色一个都不给这一码(默认谁都看不见这条菜单)", not builtin_missing, str(builtin_missing)) + guarded: dict[str, set[str]] = {} + for route in app.routes: + path = getattr(route, "path", "") + if not path.startswith("/api/v1/export/detail"): + continue + codes: set[str] = set() + stack = [route.dependant] + while stack: + node = stack.pop() + call = getattr(node, "call", None) + if call is not None and getattr(call, "__name__", "") == "dependency": + free = call.__closure__ or () + codes |= {cell.cell_contents for cell in free if isinstance(cell.cell_contents, str)} + stack.extend(getattr(node, "dependencies", None) or []) + guarded[path] = codes + check("四条明细导出接口都在", len(guarded) == 4, str(sorted(guarded))) + check("四条接口挂的都是 monitor:export", + all(codes == {"monitor:export"} for codes in guarded.values()), str(guarded)) + check("monitor:export 与 monitor:work 互不为前置", + all("monitor:work" not in codes for codes in guarded.values())) + + with SessionLocal() as db: + try: + seed(db) + # 这三个人是 seed() 刚插进同一个未提交事务的,取用户必须排在造数据之后 + person = db.execute(select(models.User).where(models.User.account == ME)).scalars().first() + admin = CurrentUser(person=person, ref=ME, is_admin=True) + scoped = CurrentUser( + person=person, ref=ME, is_admin=False, + permissions=("monitor:export",), + data_scope=permissions_module.SCOPE_SELF, + data_grant=permissions_module.grant_for_scope(permissions_module.SCOPE_SELF), + ) + job_open = f"__dex_job_1_{STAMP}" + job_done = f"__dex_job_2_{STAMP}" + + # 3. 待办未处理 + add_task(db, job_open, identity=ME, activity="部门主管") + db.flush() + got = unop(db, [job_open]) + check("待办挂在谁名下就算谁没操作", persons_of(got[job_open]) == [ME], str(persons_of(got[job_open]))) + check("这类记成「待办未处理」", kinds_of(got[job_open]) == [de.KIND_TASK], str(kinds_of(got[job_open]))) + db.execute(delete(models.Task).where(models.Task.identity == ME)) + db.flush() + check("办完就不再命中", not unop(db, [job_open])[job_open].rows) + + # 4 / 5. 两类待阅 + add_read(db, job_open, identity=PEER, requires=False) + add_read(db, job_open, identity=BOSS, requires=True) + db.flush() + got = unop(db, [job_open]) + check("待阅没打开算未操作", PEER in persons_of(got[job_open]), str(persons_of(got[job_open]))) + check("抄送需处理没回意见算未操作", BOSS in persons_of(got[job_open])) + rows = {str(row.get("person")): row for row in got[job_open].rows} + check("普通待阅记成「待阅未打开」", rows[PEER]["kind"] == de.KIND_READ_PLAIN, str(rows[PEER])) + check("需处理抄送记成「抄送需处理未回复」", rows[BOSS]["kind"] == de.KIND_READ_ACTION, str(rows[BOSS])) + db.execute(delete(models.Read).where(models.Read.identity == PEER)) + add_read(db, job_open, identity=PEER, requires=False, view=True) + db.flush() + check("普通待阅打开过就不算了", PEER not in persons_of(unop(db, [job_open])[job_open])) + db.execute(delete(models.Read).where(models.Read.identity == BOSS)) + add_read(db, job_open, identity=BOSS, requires=True, view=True) + db.flush() + check("需处理抄送只打开没回意见,仍旧算", BOSS in persons_of(unop(db, [job_open])[job_open])) + db.execute(delete(models.Read).where(models.Read.identity == BOSS)) + add_read(db, job_open, identity=BOSS, requires=True, view=True, handle=True) + db.flush() + check("回了处理意见才算完", BOSS not in persons_of(unop(db, [job_open])[job_open])) + db.execute(delete(models.Read).where(models.Read.identity == PEER)) + db.execute(delete(models.Read).where(models.Read.identity == BOSS)) + + # 6. 归档单上那条没打开的待阅 + add_read(db, job_done, identity=PEER, requires=False, completed=True) + db.flush() + got = unop(db, [job_done]) + check("归档之后,没打开过的待阅照样查得出来", persons_of(got[job_done]) == [PEER], + str(persons_of(got[job_done]))) + db.execute(delete(models.Read).where(models.Read.job == job_done)) + + # 7. 终止收尾算在原持有人头上 + db.add(models.TaskCompleted( + task=f"__dex_tc_{STAMP}", job=job_open, work=job_open, title="明细导出在途单", + process=P_1, process_name="明细导出流程甲", serial="DEX1", activity=f"__dex_act_1_{STAMP}", + activity_name="部门主管", person=PEER, identity=PEER, identity_name=NAMES[PEER], + start_time=BASE - timedelta(days=3), completed_time=BASE, + processing_type="terminate", operator=BOSS, operator_name="终止人", latest=True, + )) + db.flush() + got = unop(db, [job_open]) + check("终止的单算在被强行结掉那条待办的持有人头上", PEER in persons_of(got[job_open]), + str(persons_of(got[job_open]))) + check("终止那一类记成「终止时未表态」", de.KIND_TERMINATE in kinds_of(got[job_open])) + check("来源写清楚是谁动的手", "终止人" in str(got[job_open].rows[0].get("source")), + str(got[job_open].rows[0])) + db.execute(delete(models.TaskCompleted).where(models.TaskCompleted.task == f"__dex_tc_{STAMP}")) + + # 8. 加签未激活 + 转办来路 + add_task(db, job_open, identity=ME, activity="部门主管", kind="add_pending") + db.flush() + check("前置加签默认不算未操作", + not persons_of(unop(db, [job_open])[job_open]), str(persons_of(unop(db, [job_open])[job_open]))) + got = unop(db, [job_open], kinds=de.ALL_KINDS) + check("勾上「含未激活加签」才命中", persons_of(got[job_open]) == [ME], str(persons_of(got[job_open]))) + check("这类记成「加签未激活」", kinds_of(got[job_open]) == [de.KIND_ADD_PENDING], + str(kinds_of(got[job_open]))) + db.execute(delete(models.Task).where(models.Task.identity == ME)) + add_task(db, job_open, identity=ME, activity="部门主管", kind="transfer") + db.flush() + got = unop(db, [job_open]) + check("转办不冤枉原持有人:算在现在这位头上", persons_of(got[job_open]) == [ME]) + check("来路写明「转办自 谁」", "转办自" in str(got[job_open].rows[0].get("source")), + str(got[job_open].rows[0])) + db.execute(delete(models.Task).where(models.Task.identity == ME)) + + # 表态锁在第三方的那一环不算在人头上 + add_task(db, job_open, identity=ME, activity="财务复核") + db.flush() + got = unop(db, [job_open], locked=[(P_1, f"__dex_act_1_{STAMP}")]) + check("按钮锁在外部系统的那一环不算未操作", not persons_of(got[job_open]), str(persons_of(got[job_open]))) + db.execute(delete(models.Task).where(models.Task.identity == ME)) + + # 2 / 9 / 10 / 11 走完整查询 + add_task(db, job_open, identity=ME, activity="部门主管") + db.flush() + cols = ["base.serial", "base.title", "base.process_name", "base.status", "base.halt_type", + "base.unoperators", "form.applyDept", "form.accountProject", "form.checkTotal", + "form.loanReason"] + + def query(filters, *, layout="perProcess", summary=False, columns=cols, limit=50): + specs = de.build_columns(db, filters.processes, columns, {}, []) + rows, total = de.query_page(db, admin, filters, limit=limit) + return de.build_sheets(db, admin, filters, specs, rows, layout=layout, summary=summary), total + + both = [P_1, P_2] + sheets, total = query(de.Filters(processes=both)) + check("默认查得到:两条流程三张单(两张在途 + 一张归档)", total == 3, f"total={total}") + check("分表模式:勾两条流程出两个 sheet,顺序跟勾选一致", + [s.name for s in sheets] == [f"明细导出流程甲{STAMP}", f"明细导出流程乙{STAMP}"], + str([s.name for s in sheets])) + check("sheet 顺序跟左侧流程清单一致", [s.name for s in sheets][0].startswith("明细导出流程甲")) + # 勾了但一条都没命中:也要留一张只有表头的表,界面上说了几张就是几张 + empty, _ = query(de.Filters(processes=both, keyword=f"明细导出在途单{STAMP}")) + check("没命中的流程留一张空表头的表,不是静默少一张", + [s.name for s in empty] == [f"明细导出流程甲{STAMP}", f"明细导出流程乙{STAMP}"] + and len(empty[1].lines) == 0 and len(empty[1].headers) > 0, + str([(s.name, len(s.lines)) for s in empty])) + with_sum, _ = query(de.Filters(processes=both, keyword=f"明细导出在途单{STAMP}"), + summary=True) + check("这时「附一张汇总表」也照加:汇总 + 两张表 = 三张", + [s.name for s in with_sum] == [de.SUMMARY_SHEET_NAME, + f"明细导出流程甲{STAMP}", f"明细导出流程乙{STAMP}"], + str([s.name for s in with_sum])) + merged_ok = "报销金额" not in sheets[1].headers and "借款事由" in sheets[1].headers + check("这条流程没有的字段,在它自己那张表里不出现", merged_ok, str(sheets[1].headers)) + check("各自那张表填自己那一份字段", + "报销金额" in sheets[0].headers and "借款事由" not in sheets[0].headers, str(sheets[0].headers)) + check("字典值落地翻成名称而不是编码", + PROJECT_LABEL in sheets[0].lines[0] or PROJECT_LABEL in sheets[0].lines[1], + str(sheets[0].lines)) + unop_col = sheets[0].headers.index("未操作者") + check("未操作者那一列念得出姓名,不是账号", + any(NAMES[ME] in line[unop_col] for line in sheets[0].lines), str(sheets[0].lines)) + + merged, merged_total = query(de.Filters(processes=both), layout="merged") + check("合并模式就一张表", len(merged) == 1, str([s.name for s in merged])) + check("合并模式第一列固定是「流程」", merged[0].headers[0] == "流程", str(merged[0].headers)) + lean, _ = query(de.Filters(processes=both), layout="merged", + columns=["base.serial", "form.applyDept"]) + check("没勾「流程」这一列也照样给,且只出现一次", + lean[0].headers.count("流程") == 1 and lean[0].headers[0] == "流程", str(lean[0].headers)) + check("两种模式行数一致", merged_total == total and sum(len(s.lines) for s in merged) == total) + check("同 key 的字段归并成一列", + merged[0].headers.count("申请部门") == 1 and merged[0].headers.count("相关核算项目") == 1, + str(merged[0].headers)) + check("没这一格的行留空而不是补 0", + any(line[merged[0].headers.index("相关核算项目")] == "" for line in merged[0].lines), + str(merged[0].lines)) + with_summary, _ = query(de.Filters(processes=both), layout="merged", summary=True) + check("合并模式也认「附一张汇总表」", with_summary[0].name == "汇总", str([s.name for s in with_summary])) + + archived, _ = query(de.Filters(processes=both, archive_start="2026-02-01", archive_end="2026-03-31")) + check("归档日期只命中归档表那一半", sum(len(s.lines) for s in archived) == 1, + str([len(s.lines) for s in archived])) + mix, mix_total = query(de.Filters( + processes=both, statuses=["running", "completed"], + archive_start="2026-02-01", archive_end="2026-03-31")) + check("状态含在途 + 归档日期:在途那半给空集且不报错", mix_total == 1, f"total={mix_total}") + running, _ = query(de.Filters(processes=both, statuses=["running"])) + check("状态=在途只剩两张在途单", sum(len(s.lines) for s in running) == 2) + done, _ = query(de.Filters(processes=both, statuses=["completed"])) + check("状态=已办结只剩归档那张", sum(len(s.lines) for s in done) == 1) + + by_name, name_total = query(de.Filters(processes=both, project_name=PROJECT_LABEL)) + by_code, code_total = query(de.Filters(processes=both, project_code=PROJECT_CODE)) + check("按项目名称筛只命中有这一格的流程", name_total == 2, f"total={name_total}") + check("按项目编码筛命中同一批单", code_total == name_total, f"{code_total} != {name_total}") + none, none_total = query(de.Filters(processes=both, project_name="不存在的项目")) + check("项目筛不命中就是空,不瞎兜底", none_total == 0, str(none_total)) + try: + only_b, _ = query(de.Filters(processes=[P_2], project_name=PROJECT_LABEL)) + check("所选流程没有那一格时明确报错,不出空表", False, "没抛错") + except Exception as error: # noqa: BLE001 - 要的就是这一句人话 + check("所选流程没有那一格时明确报错,不出空表", "相关核算项目" in str(getattr(error, "message", error)), + str(error)) + + person_filter = de.Filters(processes=both, unoperator=de.UnoperatorFilter(persons=[ME])) + _s, hit = query(person_filter) + _s, miss = query(de.Filters(processes=both, unoperator=de.UnoperatorFilter(persons=[BOSS]))) + _s, exclude = query(de.Filters( + processes=both, unoperator=de.UnoperatorFilter(persons=[ME], mode="not"))) + check("「未操作者包含某人」命中他名下那条在途单", hit == 1, f"total={hit}") + check("没挂待办的人不命中", miss == 0, f"total={miss}") + check("不包含就是从结果里剔出去", exclude == total - 1, f"total={exclude}") + _s, kind_only = query(de.Filters(processes=both, unoperator=de.UnoperatorFilter( + persons=[ME], kinds=[de.KIND_READ_PLAIN]))) + check("口径只勾「待阅未打开」时待办不算数", kind_only == 0, f"total={kind_only}") + + _s, no_creator = query(de.Filters(processes=both)) + _s, empty_creator = query(de.Filters(processes=both, creator_mode="person")) + check("创建人一项留空 = 不限(不是谁都不要)", + no_creator == total and empty_creator == total, f"{no_creator}/{empty_creator}") + _s, by_creator = query(de.Filters(processes=both, creator_mode="person", creators=[ME])) + check("创建人填了就走白名单", by_creator == total, f"total={by_creator}") + _s, other_creator = query(de.Filters(processes=both, creator_mode="person", creators=[BOSS])) + check("创建人对不上就是空", other_creator == 0, f"total={other_creator}") + + _s, scoped_total = (lambda specs: ( + de.build_sheets(db, scoped, de.Filters(processes=both), specs, + de.query_page(db, scoped, de.Filters(processes=both), limit=50)[0]), + de.query_page(db, scoped, de.Filters(processes=both), limit=50)[1], + ))(de.build_columns(db, both, cols, {}, [])) + check("数据范围只到本人,导不出别人的单", scoped_total == total, f"total={scoped_total}") + outsider = CurrentUser( + person=db.execute(select(models.User).where(models.User.account == BOSS)).scalars().first(), + ref=BOSS, is_admin=False, permissions=("monitor:export",), + data_scope=permissions_module.SCOPE_SELF, + data_grant=permissions_module.grant_for_scope(permissions_module.SCOPE_SELF), + ) + _s, outsider_total = de.query_page(db, outsider, de.Filters(processes=both), limit=50) + check("范围里没有这两张单的人导出为空", outsider_total == 0, f"total={outsider_total}") + + try: + de.validate(de.Filters(processes=both), cols, "perProcess", "csv") + check("分表 + CSV 直接拒绝", False, "没抛错") + except Exception as error: # noqa: BLE001 + check("分表 + CSV 直接拒绝", "CSV" in str(getattr(error, "message", error))) + try: + de.validate(de.Filters(processes=[]), cols, "merged", "xlsx") + check("没勾流程就报错", False, "没抛错") + except Exception as error: # noqa: BLE001 + check("没勾流程就报错", "流程" in str(getattr(error, "message", error))) + try: + de.build_columns(db, both, ["form.ghost"], {}, []) + check("一列都不认的报文直接报错,不悄悄出空表", False, "没抛错") + except Exception as error: # noqa: BLE001 + check("一列都不认的报文直接报错,不悄悄出空表", "列" in str(getattr(error, "message", error))) + + # 接口层:catalog / count / preview / download 四条走一遍真函数 + from app.api import export as export_api # noqa: PLC0415 + from app.schemas import ExportDetailBody # noqa: PLC0415 + + def body_of(**over) -> ExportDetailBody: + payload = { + "filters": {"processes": both, "unoperator": {"persons": [ME]}}, + "columns": ["base.serial", "base.title", "base.unoperators", "form.accountProject"], + "layout": "perProcess", "fmt": "xlsx", "page": 1, "pageSize": 10, + } + payload.update(over) + return ExportDetailBody.model_validate(payload) + + cat = export_api.export_detail_catalog(db=db, user=admin)["data"] + listed = {item["id"]: item for item in cat["processes"] if item["id"] in both} + check("catalog 回了两条流程与各自的字段目录", + set(listed) == set(both) and listed[P_1]["columns"] and listed[P_2]["columns"], + str(list(listed))) + check("catalog 把「相关核算项目」那一格标出来了", + listed[P_1]["projectField"] and listed[P_1]["projectField"]["dictCode"] == f"dex_{STAMP}", + str(listed[P_1]["projectField"])) + check("没有那一格的流程标成 null", listed[P_2]["projectField"] is None, str(listed[P_2]["projectField"])) + check("catalog 带的出厂列与口径清单能用", + set(cat["defaultColumns"]) <= {item["id"] for item in cat["baseColumns"] + cat["unoperatorColumns"]} + and {item["id"] for item in cat["unoperatorKinds"]} == set(de.ALL_KINDS) + and cat["maxColumns"] > 0, str(cat["defaultColumns"])) + + counted = export_api.export_detail_count(body_of(), db=db, user=admin)["data"] + check("count 按流程分开报条数", + [row["count"] for row in counted["byProcess"]] == [1, 0] + and counted["total"] == 1 and not counted["exceeded"], str(counted)) + looked = export_api.export_detail_preview(body_of(), db=db, user=admin)["data"] + check("预览回来的表头就是那几列", + looked["sheets"][0]["headers"] == ["单号", "标题", "未操作者", "相关核算项目"], + str(looked["sheets"][0]["headers"])) + check("预览与 count 同一个条数", looked["total"] == counted["total"], str(looked["total"])) + check("预览那一行填上了未操作者与项目名称", + NAMES[ME] in looked["sheets"][0]["lines"][0][2] + and PROJECT_LABEL in looked["sheets"][0]["lines"][0][3], str(looked["sheets"][0]["lines"])) + file_resp = export_api.export_detail_download(body_of(), db=db, user=admin, request=None) + disposition = file_resp.headers.get("content-disposition", "") + check("下载回的是 xlsx 且文件名带得上日期", + file_resp.media_type == de.XLSX_TYPE and "filename*=UTF-8''" in disposition + and ".xlsx" in disposition, disposition) + csv_resp = export_api.export_detail_download( + body_of(layout="merged", fmt="csv"), db=db, user=admin, request=None) + check("CSV 走合并形态,编码带 BOM", + "text/csv" in csv_resp.media_type and csv_resp.body.startswith(b"\xef\xbb\xbf"), + csv_resp.headers.get("content-type", "")) + for label, bad in ( + ("没勾流程", body_of(filters={"processes": []})), + ("一列没勾", body_of(columns=[])), + ("分表配 CSV", body_of(fmt="csv")), + ): + try: + export_api.export_detail_preview(bad, db=db, user=admin) + check(f"接口挡住{label}", False, "没抛错") + except Exception as error: # noqa: BLE001 + check(f"接口挡住{label}", getattr(error, "status_code", 0) == 400, str(error)) + try: + export_api.export_detail_preview( + body_of(columns=["base.serial"] * 1 + [f"form.x{i}" for i in range(200)]), db=db, user=admin) + check("列数超上限报错", False, "没抛错") + except Exception as error: # noqa: BLE001 + check("列数超上限报错", "列" in str(getattr(error, "message", error)), str(error)) + try: + # 列换成乙流程真有的那一格,让"没有项目格"这一条判据自己说话 + export_api.export_detail_count( + body_of(filters={"processes": [P_2], "projectName": "x"}, + columns=["base.serial", "form.loanReason"]), db=db, user=admin) + check("只勾了没这一格的流程时项目筛选报错", False, "没抛错") + except Exception as error: # noqa: BLE001 + check("只勾了没这一格的流程时项目筛选报错", + "相关核算项目" in str(getattr(error, "message", error)), str(error)) + # 一批表单字段里没有一条落得上:与其悄悄出一张只有固有列的表,不如报出来 + try: + export_api.export_detail_preview( + body_of(filters={"processes": [P_2]}, columns=["base.serial", "form.accountProject"]), + db=db, user=admin) + check("勾的表单字段在这几条流程里都没有时报错", False, "没抛错") + except Exception as error: # noqa: BLE001 + check("勾的表单字段在这几条流程里都没有时报错", + "都不存在" in str(getattr(error, "message", error)), str(error)) + partial = export_api.export_detail_preview( + body_of(filters={"processes": both}, + columns=["base.serial", "form.accountProject", "form.loanReason"]), db=db, user=admin)["data"] + check("两条流程各缺一半字段时,两张表各留各的列", + "相关核算项目" in partial["sheets"][0]["headers"] + and "相关核算项目" not in partial["sheets"][1]["headers"] + and "借款事由" not in partial["sheets"][0]["headers"], + str([sheet["headers"] for sheet in partial["sheets"]])) + + names, used = [], set() + for raw in ("费用/报销:流程[甲]", "费用/报销:流程[甲]", "a" * 40, ""): + names.append(de.sheet_name(raw, used)) + check("sheet 名去掉非法字符、截到 31 字、重名补序号", + all(len(n) <= 31 and not set("[]:*?/\\") & set(n) for n in names) + and names[0] != names[1] and names[1].endswith("-2") and names[3] == "流程", str(names)) + + acts = db.execute(select(models.Activity).where(models.Activity.process == P_1)).scalars().all() + act_specs = de.build_columns(db, [P_1], ["base.serial"], {}, [row.id for row in acts]) + check("勾一个环节摊三列", len(act_specs) == 1 + 3 * len(acts), str([s.id for s in act_specs])) + check("环节列表头带得上环节名", + any("部门主管.处理人" == spec.label or "财务复核.完成时间" == spec.label for spec in act_specs), + str([spec.label for spec in act_specs])) + + # 两种命名都是在 pydantic 那一层收的,service 只接落平之后的下划线报文 + from app import schemas # noqa: PLC0415 + camel = schemas.ExportDetailBody.model_validate({ + "filters": {"processes": [P_1], "creatorMode": "person", "creators": [ME], + "unoperator": {"mode": "all", "persons": [ME]}}, + "columns": ["base.serial"], "layout": "merged", "pageSize": 5, + }) + snake = schemas.ExportDetailBody.model_validate({ + "filters": {"processes": [P_1], "creator_mode": "person", "creators": [ME]}, + "columns": ["base.serial"], + }) + check("报文驼峰、下划线两种写法都收", + camel.filters.creator_mode == "person" and snake.filters.creator_mode == "person" + and camel.page_size == 5) + payload = de.filters_from_body(camel.filters.model_dump()) + check("落平之后的报文进 service 认得全", + payload.creator_mode == "person" and payload.processes == [P_1] + and payload.unoperator.mode == "all", str(payload)) + check("kinds 给空清单 = 回落到出厂四类", + payload.unoperator.kinds == list(de.DEFAULT_KINDS), str(payload.unoperator.kinds)) + check("出厂四类不含「加签未激活」", de.KIND_ADD_PENDING not in de.DEFAULT_KINDS) + finally: + db.rollback() + with SessionLocal() as cleaner: + cleaner.execute(delete(models.Work).where(models.Work.job.like(f"__dex_%_{STAMP}"))) + cleaner.execute(delete(models.WorkCompleted).where(models.WorkCompleted.job.like(f"__dex_%_{STAMP}"))) + cleaner.execute(delete(models.Task).where(models.Task.identity.in_([ME, PEER, BOSS]))) + cleaner.execute(delete(models.TaskCompleted).where(models.TaskCompleted.identity.in_([ME, PEER, BOSS]))) + cleaner.execute(delete(models.Read).where(models.Read.identity.in_([ME, PEER, BOSS]))) + cleaner.execute(delete(models.Activity).where(models.Activity.process.in_([P_1, P_2]))) + cleaner.execute(delete(models.Process).where(models.Process.id.in_([P_1, P_2]))) + cleaner.execute(delete(models.FormElement).where(models.FormElement.id.like(f"__dex_form_%_{STAMP}"))) + cleaner.execute(delete(models.DictItem).where(models.DictItem.type == f"dex_{STAMP}")) + cleaner.execute(delete(models.DictType).where(models.DictType.id == PROJECT_DICT)) + cleaner.execute(delete(models.User).where(models.User.account.in_([ME, PEER, BOSS]))) + cleaner.execute(delete(models.Unit).where(models.Unit.id == UNIT)) + cleaner.execute(delete(models.Work).where(models.Work.serial.in_([f"DEX1{STAMP}", f"DEX2{STAMP}"]))) + cleaner.commit() + + print() + print(f"通过 {PASSED} 项,失败 {len(FAILS)} 项") + return 1 if FAILS else 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/backend/scripts/check_hub_sync_details.py b/backend/scripts/check_hub_sync_details.py new file mode 100644 index 0000000..5ac0a2a --- /dev/null +++ b/backend/scripts/check_hub_sync_details.py @@ -0,0 +1,348 @@ +#!/usr/bin/env python3 +"""守「同步记录要能核对」与「三条熔断底线要能调」这两件事。 + +踩过的坑:一趟同步把 68 个登录名让了位、14 个人跟 Hub 改了名,同步历史里却只写着 +「更新 99 人」——改名/让位/认回部门这三类动作只活在 ``message`` 那段文本里,而那一列 +只留 2000 字,提示一多就被裁掉后半句。另一头,熔断的三条底线(人员 20、部门 5、 +清单人数 50%)是写死的常量:几十人的团队和上千人的部署被同一条线拦着,想调只能改代码。 + +这里钉十七项:: + + cd backend && PYTHONPATH=. python3 scripts/check_hub_sync_details.py + +1~6 :明细结构化(计数成列、名单有界、提示按条留底、旧行不炸、「只改名」不算无变更); +7~19 :三条底线跟着配置走(默认值 = 出厂常量、人数线、部门线、清单人数线、提示文案)。 + +全程待在同一个事务里,跑完 ``rollback``,库里不留任何临时行。 +""" + +from __future__ import annotations + +import dataclasses +import pathlib +import sys +from datetime import datetime + +sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent)) + +from sqlalchemy import func, select # noqa: E402 + +from app import dbconfig, hubconfig, models # noqa: E402 +from app.db import SessionLocal # noqa: E402 +from app.service import hub_sync # noqa: E402 + +MARK = "zzdet-" +UID_BASE = 905000 +ORG_BASE = 905900 +FAILS: list[str] = [] +PASSED = 0 + + +def check(label: str, passed: bool, detail: str = "") -> None: + global PASSED + if passed: + PASSED += 1 + print(f"[通过] {label}") + else: + FAILS.append(label) + print(f"[FAIL] {label}{f' -> {detail}' if detail else ''}") + + +cfg_obj = None + + +def use_cfg(**patch: object) -> None: + """把 ``hubconfig.get`` 换成一份改过几项的配置,其余字段照原样带着。""" + hubconfig.get = ( # type: ignore[assignment] + lambda db=None, _patch=patch: dataclasses.replace(cfg_obj, **_patch) # noqa: B023 + ) + + +def add_user(db, account: str, *, hub_user_id: int): # noqa: ANN001, ANN201 + row = models.User( + account=account, + display_name=f"检查人员{hub_user_id}", + email="", + mobile="", + password_hash="zz-check", + role=models.ROLE_MEMBER, + status=models.UserStatus.ACTIVE, + source=models.AccountSource.HUB, + hub_user_id=hub_user_id, + ) + db.add(row) + db.flush() + return row + + +def add_unit(db, hub_org_id: int): # noqa: ANN001, ANN201 + row = models.Unit( + name=f"检查部门{hub_org_id}", + code=f"{MARK}u{hub_org_id}", + alias=f"{MARK}u{hub_org_id}", + description="明细检查", + hub_org_id=hub_org_id, + status=models.UnitStatus.ACTIVE, + ) + db.add(row) + db.flush() + return row + + +def seen_people(db) -> set[int]: # noqa: ANN001 + """「这一趟清单里有谁」:库里已有的同步账号,但**不含**本次临时建的那批。 + + 临时行就是拿来当"Hub 清单里查无此人"的样本,所以必须从清单里摘出去; + 真库那 100 个账号照旧全算在册,免得它们的停用判定混进检查数字。 + """ + rows = db.execute( + select(models.User.hub_user_id).where( + models.User.source == models.AccountSource.HUB, + models.User.hub_user_id.is_not(None), + models.User.account.not_like(f"{MARK}%"), + ) + ).scalars().all() + return {int(value) for value in rows if value} + + +def seen_units(db) -> set[int]: # noqa: ANN001 + """同上:库里已有的 Hub 部门,不含本次临时建的那几个。""" + rows = db.execute( + select(models.Unit.hub_org_id).where( + models.Unit.hub_org_id.is_not(None), + models.Unit.code.not_like(f"{MARK}%"), + ) + ).scalars().all() + return {int(value) for value in rows if value} + + +# --------------------------------------------------------------------------- P1 + + +def check_details(db) -> None: # noqa: ANN001 + stats = hub_sync.SyncStats() + for index in range(hub_sync.DETAIL_ITEM_LIMIT + 5): + stats.detail("account_renames", f"old{index} → new{index}") + stats.detail("name_renames", f"甲{index} → 乙{index}") + stats.detail("reclaimed_accounts", f"gone{index} → hub-lost-{index}") + stats.detail("rebound_units", f"部门{index}") + stats.renamed += 1 + details = hub_sync.run_details(stats) + check( + "名单有界:每类最多留 DETAIL_ITEM_LIMIT 条", + all( + len(details[key]) == hub_sync.DETAIL_ITEM_LIMIT + for key in ("account_renames", "name_renames", "reclaimed_accounts", "rebound_units") + ), + str({key: len(value) for key, value in details.items() if isinstance(value, list)}), + ) + check( + "总数不受上限影响:25 条改名照样报 25", + details["renamed"] == hub_sync.DETAIL_ITEM_LIMIT + 5 and details["account_renames"][0] == "old0 → new0", + str(details["renamed"]), + ) + + # 提示按条留底:message 那 2000 字裁掉后半句时,details.notes 仍然完整 + for index in range(12): + stats.note(f"提示{index}:" + "很长" * 120) + run = models.HubSyncRun(trigger=models.HubSyncRun.TRIGGER_MANUAL, status=models.HubSyncRun.STATUS_RUNNING) + db.add(run) + db.flush() + original_commit = db.commit + db.commit = db.flush # type: ignore[method-assign] # 别让 _finish 把临时行提交进真库 + try: + hub_sync._finish( + db, + run.id, + stats, + models.HubSyncRun.STATUS_SUCCESS, + ";".join(stats.messages), + ) + finally: + db.commit = original_commit # type: ignore[method-assign] + db.refresh(run) + check( + "三个计数写进列:改名 / 让位 / 认回部门", + run.renamed == stats.renamed and run.reclaimed == 0 and run.units_rebound == 0, + f"{run.renamed}/{run.reclaimed}/{run.units_rebound}", + ) + check("明细写进 details", (run.details or {}).get("renamed") == stats.renamed, str(run.details)[:120]) + check( + "message 被裁到 2000 字,details.notes 仍是 12 条原文", + len(run.message) == 2000 and len((run.details or {}).get("notes") or []) == 12, + f"message={len(run.message)} notes={len((run.details or {}).get('notes') or [])}", + ) + + payload = hub_sync.serialize_run(run) + check( + "serialize_run 回显新字段", + payload["renamed"] == stats.renamed + and payload["reclaimed"] == 0 + and payload["units_rebound"] == 0 + and payload["details"]["account_renames"], + str({key: payload[key] for key in ("renamed", "reclaimed", "units_rebound")}), + ) + check("只有改名的那一趟不算「无变更」", payload["unchanged"] is False, str(payload["unchanged"])) + + # 老记录(这两列之前就有、details 为空)不能把界面炸了 + run.details = None + run.renamed = 0 + run.reclaimed = 0 + run.units_rebound = 0 + run.created = run.updated = run.offboarded = 0 + legacy = hub_sync.serialize_run(run) + check( + "没有 details 的历史行照常序列化,且仍报「无变更」", + legacy["details"] == {} and legacy["renamed"] == 0 and legacy["unchanged"] is True, + str({key: legacy[key] for key in ("details", "unchanged")}), + ) + + +# --------------------------------------------------------------------------- P2 + + +def check_floors(db) -> None: # noqa: ANN001 + now = datetime.now() + defaults = {item.name: item.default for item in dbconfig.ITEMS} + check( + "三项配置的出厂默认值与 hub_sync 里的常量一致", + defaults["hub_sync_offboard_guard_min_people"] == hub_sync.OFFBOARD_GUARD_MIN_PEOPLE + and defaults["hub_sync_unit_offboard_guard_min"] == hub_sync.UNIT_OFFBOARD_GUARD_MIN + and defaults["hub_sync_roster_floor_percent"] == hub_sync.ROSTER_FLOOR_PERCENT, + str( + { + key: defaults[key] + for key in ( + "hub_sync_offboard_guard_min_people", + "hub_sync_unit_offboard_guard_min", + "hub_sync_roster_floor_percent", + ) + } + ), + ) + check( + "三项配置都在 hubconfig 的可写名单里", + all( + name in hubconfig.MANAGED and hubconfig.GROUP_OF[name] == "hub_sync" + for name in ( + "hub_sync_offboard_guard_min_people", + "hub_sync_unit_offboard_guard_min", + "hub_sync_roster_floor_percent", + ) + ), + ) + + # 人员侧:百分比固定 1%(远小于底线),能不能触发完全由那条人数底线说了算 + temp = [add_user(db, f"{MARK}p{index}", hub_user_id=UID_BASE + index) for index in range(1, 22)] + use_cfg(hub_sync_offboard_guard_percent=1, hub_sync_offboard_guard_min_people=20) + stats = hub_sync.SyncStats() + hub_sync._offboard_missing(db, seen_people(db), stats, now) + check( + "底线 20 时熔断:21 人等着停用,一个都不停", + stats.offboard_guarded == 21 and stats.offboarded == 0, + f"guarded={stats.offboard_guarded} offboarded={stats.offboarded}", + ) + use_cfg(hub_sync_offboard_guard_percent=1, hub_sync_offboard_guard_min_people=25) + stats = hub_sync.SyncStats() + hub_sync._offboard_missing(db, seen_people(db), stats, now) + check( + "底线调到 25 就放行:同样这 21 人照常停用", + stats.offboard_guarded == 0 and stats.offboarded == 21, + f"guarded={stats.offboard_guarded} offboarded={stats.offboarded}", + ) + for row in temp: # 放回启用状态,验下一条 + row.status = models.UserStatus.ACTIVE + db.flush() + use_cfg(hub_sync_offboard_guard_percent=0, hub_sync_offboard_guard_min_people=0) + stats = hub_sync.SyncStats() + hub_sync._offboard_missing(db, seen_people(db), stats, now) + check( + "百分比设 0 关掉熔断,底线不再起作用", + stats.offboarded == 21 and stats.offboard_guarded == 0, + f"offboarded={stats.offboarded}", + ) + for row in temp: + row.status = models.UserStatus.ACTIVE + db.flush() + + # 部门侧:同样只看那条个数底线 + units = [add_unit(db, ORG_BASE + index) for index in range(1, 7)] + use_cfg(hub_sync_offboard_guard_percent=1, hub_sync_unit_offboard_guard_min=5) + stats = hub_sync.SyncStats() + hub_sync._offboard_missing_units(db, seen_units(db), stats) + check( + "部门底线 5 时熔断:6 个部门一个都不停", + stats.units_offboard_guarded == 6 and stats.units_offboarded == 0, + f"guarded={stats.units_offboard_guarded} offboarded={stats.units_offboarded}", + ) + use_cfg(hub_sync_offboard_guard_percent=1, hub_sync_unit_offboard_guard_min=10) + stats = hub_sync.SyncStats() + hub_sync._offboard_missing_units(db, seen_units(db), stats) + check( + "部门底线调到 10 就放行", + stats.units_offboarded == 6 and stats.units_offboard_guarded == 0, + f"offboarded={stats.units_offboarded}", + ) + for row in units: + row.status = models.UnitStatus.ACTIVE + db.flush() + + # 清单人数下限:同一份基准,百分比改一改,挡不挡就该跟着变 + row = db.get(models.SystemSetting, hub_sync.STATE_KEY) + if row is None: + row = models.SystemSetting(key=hub_sync.STATE_KEY, value={}, description="Hub 组织人员同步状态") + db.add(row) + row.value = {**(row.value or {}), "total_users": 200} + db.flush() + use_cfg(hub_sync_roster_floor_percent=50) + blocked = hub_sync._roster_floor(db) + use_cfg(hub_sync_roster_floor_percent=0) + off = hub_sync._roster_floor(db) + use_cfg(hub_sync_roster_floor_percent=25) + quarter = hub_sync._roster_floor(db) + # 基准 = 「状态里记的 200 人」与「本地带 Hub 主键的账号数」里较小可信的那个 + local_hub = int( + db.execute( + select(func.count()).select_from(models.User).where(models.User.hub_user_id.is_not(None)) + ).scalar() + or 0 + ) + baseline = min(200, local_hub) + check( + "清单人数下限跟着配置走:50% / 25% / 关掉", + blocked == baseline * 50 // 100 and quarter == baseline * 25 // 100 and off == 0, + f"baseline={baseline} 50%={blocked} 25%={quarter} 0={off}", + ) + use_cfg() + check( + "取不到配置项时回落到出厂常量(而不是完全不拦)", + hub_sync._floor_value(object(), "hub_sync_offboard_guard_min_people", 20) == 20 + and hub_sync._floor_value(object(), "whatever", 5) == 5, + ) + + +def main() -> int: + global cfg_obj + real_get = hubconfig.get + cfg_obj = real_get() + db = SessionLocal() + try: + db.begin() + check_details(db) + check_floors(db) + finally: + hubconfig.get = real_get # type: ignore[assignment] + db.rollback() + db.close() + print() + if FAILS: + print(f"未通过 {len(FAILS)} 项:") + for name in FAILS: + print(f" - {name}") + return 1 + print(f"全部通过:{PASSED} 项") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/backend/scripts/check_hub_sync_lock_leak.py b/backend/scripts/check_hub_sync_lock_leak.py new file mode 100644 index 0000000..635ca2b --- /dev/null +++ b/backend/scripts/check_hub_sync_lock_leak.py @@ -0,0 +1,332 @@ +#!/usr/bin/env python3 +"""守「拿锁之后、进 try 之前」那一段:建同步记录失败不许把锁永久扣在进程上。 + +踩过的坑:``sync_users`` / ``_pull_changes`` 先 :func:`app.service.hub_sync._acquire_sync_locks` +拿锁,再写一条「进行中」的记录,**这一段在收尾那个 ``try`` 之外**。库断了、死锁、 +补列没跟上导致 INSERT 报错,异常直接从这段漏出去,``finally`` 够不着,进程内那把 +``_run_lock`` 就永久握着了。症状是"明明没在同步,点立即同步一直回**已有同步任务正在 +执行,请稍后再试**":跨副本那把 Redis 锁最多一小时自己过期,本进程这把只能等重启, +或者谁去按一下「终止」。而调度线程每几十秒那趟增量同步撞的也是同一把锁,于是整条 +组织同步一起停摆。 + +这里钉五条:: + + cd backend && PYTHONPATH=. python3 scripts/check_hub_sync_lock_leak.py + +1. **全量:建记录失败照样交锁**:INSERT 那一步抛错,异常原样往外走,但本进程那把锁 + 交还了、状态不再算运行中; +2. **增量:写游标与建记录失败照样交锁**:``_pull_changes`` 那一段同理; +3. **锁没被放松成摆设**:真跑起来的那趟在拉目录期间,第二次拿锁仍然被挡成 + 「已有同步任务正在执行」,跑完之后两把锁(含跨副本那把)都交还干净; +4. **紧接着再点一次进得来**:漏锁那次失败之后**不做任何复位**,全量与增量各再跑 + 一次,撞回来的该是 Hub 的报错而不是那句"已经有一趟在跑" —— 这一条就是修之前会 + FAIL 的那一条,也正是界面上"明明没同步却提示已有同步任务"的成因; +5. **失败的那趟自己收尾**:记录写成「失败」,不留挂着「进行中」的僵尸,一个部门、 + 一个人都没往库里写。 + +不碰真 Redis(换成假锁),Hub 换成假的(``directory`` 直接报错,一个部门一个人都 +不往库里写),库里只写自己造的记录,跑完按标记删干净。 +""" + +from __future__ import annotations + +import pathlib +import sys +import threading +from datetime import datetime + +sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent)) + +from sqlalchemy import delete, select # noqa: E402 + +from app import hubconfig, models # noqa: E402 +from app.db import SessionLocal # noqa: E402 +from app.service import hub as hub_api # noqa: E402 +from app.service import hub_sync # noqa: E402 + +MARK = "zz-check-hub-lock-leak" +NAME = "漏锁校核" +BUSY_MESSAGE = "已有同步任务正在执行,请稍后再试" +FAILS: list[str] = [] +PASSED = 0 + +#: 只顶掉这几档配置:这台机器上 Hub 大概率没真启用,而这几档决定"让不让进同步" +CFG_OVERRIDE: dict[str, object] = { + "hub_enabled": True, + "hub_base_url": "https://hub.invalid", + "sync_allowed": True, + "hub_sync_enabled": True, + "hub_sync_changes_enabled": True, + "hub_sync_skip_unchanged": False, +} + + +class FakeCache: + """假锁:只记"有没有人拿着"。真 Redis 上 force_release 会删掉别人正拿着的锁, + 校验收脚本不该干这事(与 ``check_hub_sync_cancel.py`` 同一个理由)。""" + + def __init__(self) -> None: + self.holder = "" + self.store: dict[str, object] = {} + + def key(self, *parts) -> str: # noqa: ANN002 + return ":".join(str(part) for part in parts) + + def set_json(self, name: str, value: object, ttl_seconds: float) -> bool: + self.store[name] = value + return True + + def get_json(self, name: str): # noqa: ANN201 + return self.store.get(name) + + def lock_holder(self, name: str) -> str: + return self.holder + + def locked(self, name: str) -> bool: + return bool(self.holder) + + def try_lock(self, name: str, *, ttl_seconds: float) -> str: + if self.holder: + return "" + self.holder = f"fake-{threading.get_ident()}" + return self.holder + + def release_lock(self, name: str, token: str) -> None: + if token and self.holder == token: + self.holder = "" + + def force_release(self, name: str) -> bool: + had = bool(self.holder) + self.holder = "" + return had + + +class ForcedCfg: + """真配置照抄,只改 :data:`CFG_OVERRIDE` 里那几档。""" + + def __init__(self, real: object) -> None: + self._real = real + + def __getattr__(self, name: str): # noqa: ANN204 + if name in CFG_OVERRIDE: + return CFG_OVERRIDE[name] + return getattr(self._real, name) + + +class BreakOnCommit: + """Session 的壳子:第一次 ``commit()`` 就抛,模拟"建同步记录那一步库断了"。 + + 只破第一次提交,正好落在 ``_acquire_sync_locks()`` 与那个收尾 ``try`` 之间; + 其余调用都转给真 session,所以锁交还之后 session 还能继续用。 + """ + + def __init__(self, db) -> None: # noqa: ANN001 + self._db = db + self.broken = False + + def commit(self) -> None: + if not self.broken: + self.broken = True + raise OSError("检查脚本:写同步记录时库断了") + self._db.commit() + + def __getattr__(self, name: str): # noqa: ANN204 + return getattr(self._db, name) + + +def check(label: str, passed: bool, detail: str = "") -> None: + global PASSED + if passed: + PASSED += 1 + print(f"[通过] {label}") + else: + FAILS.append(label) + print(f"[FAIL] {label}{f' -> {detail}' if detail else ''}") + + +def local_lock_free() -> bool: + """本进程那把锁现在空不空。问完就还原:拿锁来"探测"却不还,探测本身就把锁占了。""" + if hub_sync._run_lock.acquire(blocking=False): + hub_sync._run_lock.release() + return True + return False + + +def reset_locks() -> None: + """把两把锁恢复成"没人拿",让每一条校验各验各的,不被上一条的状态串。""" + if not local_lock_free(): + try: # 真漏在别的线程上:跨线程 release 是允许的,正是这一段的考点 + hub_sync._run_lock.release() + except RuntimeError: # pragma: no cover - 只在竞争下走到 + pass + hub_sync.cache.force_release(hub_sync.LOCK_SYNC) # type: ignore[attr-defined] + + +def my_runs(db) -> list[models.HubSyncRun]: # noqa: ANN001 + return list( + db.execute(select(models.HubSyncRun).where(models.HubSyncRun.operator == MARK)).scalars().all() + ) + + +def call_and_catch(fn, *args, **kwargs): # noqa: ANN001, ANN002, ANN003 + """跑一趟同步,把异常压成一句话返回,校验只看这句话。""" + try: + fn(*args, **kwargs) + except Exception as exc: # noqa: BLE001 - 校验要的正就是异常本身 + return exc + return None + + +def main() -> int: + real_cache = hub_sync.cache + real_hubconfig_get = hub_sync.hubconfig.get + real_client = hub_sync.hub_api.client + real_token = hub_sync.hub_api.sync_token + + hub_sync.cache = FakeCache() # type: ignore[assignment] + hub_sync.hubconfig.get = lambda: ForcedCfg(real_hubconfig_get()) + hub_sync.hub_api.sync_token = lambda cli: ("token", "directory_key") + + class BrokenHub: + """拉目录就直接失败:一个部门、一个人都不会往库里写。""" + + def directory(self, token, **kwargs): # noqa: ANN001, ANN003 + raise hub_api.HubError("检查脚本:Hub 挂了", reason="CHECK") + + def directory_changes(self, *args, **kwargs): # noqa: ANN001, ANN003 + raise hub_api.HubError("检查脚本:Hub 挂了", reason="CHECK") + + blocked: dict[str, str] = {} + + class BusyHub(BrokenHub): + """同上,只是在拉目录那一下顺手再抢一次锁,验锁没被放松成摆设。""" + + def directory(self, token, **kwargs): # noqa: ANN001, ANN003 + blocked["message"] = second_acquire() + raise hub_api.HubError("检查脚本:Hub 挂了", reason="CHECK") + + db = SessionLocal() + try: + # ① 全量:建「进行中」记录那一步炸 => 异常照旧抛,锁得还回来 + reset_locks() + error = call_and_catch( + hub_sync.sync_users, db=BreakOnCommit(db), trigger=models.HubSyncRun.TRIGGER_MANUAL, + operator=MARK, operator_name=NAME, + ) + check("① 全量:建记录失败时异常原样往外走", isinstance(error, OSError), repr(error)) + check("① 全量:本进程那把锁已交还", local_lock_free()) + check("① 全量:跨副本锁也已交还", hub_sync.cache.holder == "") # type: ignore[attr-defined] + check("① 全量:状态不再算运行中", hub_sync.running() is False) + db.rollback() + + # ④ 就地复现用户那一句:漏锁之后不复位、直接再点「立即同步」。 + # 修之前这里撞回来的是"已有同步任务正在执行",修之后才是 Hub 自己的报错。 + hub_sync.hub_api.client = lambda: BrokenHub() + error = call_and_catch( + hub_sync.sync_users, db=db, trigger=models.HubSyncRun.TRIGGER_MANUAL, + operator=MARK, operator_name=NAME, + ) + check( + "④ 全量:失败之后紧接着再点,进得来(不被误报成「已有同步任务正在执行」)", + isinstance(error, hub_sync.HubSyncError) and BUSY_MESSAGE not in str(error), + repr(error), + ) + check("④ 这一趟同样把两把锁交还了", hub_sync.running() is False and hub_sync.cache.holder == "") # type: ignore[attr-defined] + + # ② 增量:写游标 + 建记录那一步炸 => 同样得把锁还回来 + reset_locks() + error = call_and_catch( + hub_sync.sync_changes, db=BreakOnCommit(db), operator=MARK, operator_name=NAME, manual=True, + ) + check("② 增量:建记录失败时异常原样往外走", isinstance(error, OSError), repr(error)) + check("② 增量:本进程那把锁已交还", local_lock_free()) + check("② 增量:跨副本锁也已交还", hub_sync.cache.holder == "") # type: ignore[attr-defined] + check("② 增量:状态不再算运行中", hub_sync.running() is False) + db.rollback() + + hub_sync.hub_api.client = lambda: BrokenHub() + error = call_and_catch(hub_sync.sync_changes, db=db, operator=MARK, operator_name=NAME, manual=True) + check( + "④ 增量:失败之后紧接着再拉一次,进得来", + isinstance(error, hub_sync.HubSyncError) and BUSY_MESSAGE not in str(error), + repr(error), + ) + check("④ 这一趟同样把两把锁交还了", hub_sync.running() is False and hub_sync.cache.holder == "") # type: ignore[attr-defined] + + # ③ 真跑起来的那一趟必须还持着锁:拉目录期间第二次拿锁要能被挡下 + def second_acquire() -> str: + """在同步中间再抢一次锁:挡下来就返回那句提示,真抢到了返回空串。""" + try: + token = hub_sync._acquire_sync_locks() + except hub_sync.HubSyncError as exc: + return str(exc) + hub_sync._release_sync_locks(token) + return "" + + reset_locks() + hub_sync.hub_api.client = lambda: BusyHub() + error = call_and_catch( + hub_sync.sync_users, db=db, trigger=models.HubSyncRun.TRIGGER_MANUAL, + operator=MARK, operator_name=NAME, + ) + check( + "③ 跑起来的这趟撞见的是 Hub 的报错", + isinstance(error, hub_sync.HubSyncError) and "Hub 挂了" in str(error), + repr(error), + ) + check( + "③ 正在跑的时候第二次拿锁被挡成「已有同步任务正在执行」", + blocked.get("message") == BUSY_MESSAGE, + blocked.get("message", "压根没问第二次"), + ) + check( + "③ 跑完之后两把锁都交还干净", + hub_sync.running() is False and local_lock_free() and hub_sync.cache.holder == "", # type: ignore[attr-defined] + ) + check( + "⑤ 假 Hub 没往库里写人", + db.execute(select(models.User).where(models.User.account == MARK)).scalars().first() is None, + ) + + rows = my_runs(db) + check( + "⑤ 跑过的每一趟都收尾成「失败」,没留下挂着「进行中」的僵尸", + bool(rows) and all(row.status == models.HubSyncRun.STATUS_FAILED for row in rows), + " / ".join(f"{row.status}@{row.started_at}" for row in rows) or "一条都没有", + ) + finally: + cleanup = SessionLocal() + try: + ids = list(cleanup.execute(select(models.HubSyncRun.id).where( + models.HubSyncRun.operator == MARK)).scalars().all()) + if ids: + cleanup.execute(delete(models.HubSyncRun).where(models.HubSyncRun.id.in_(ids))) + cleanup.commit() + # 保险:漏锁那条路上如果真留下了「进行中」,一并按标记收掉,别脏了别人的页面 + left = list(cleanup.execute(select(models.HubSyncRun.id).where( + models.HubSyncRun.operator_name == NAME, + models.HubSyncRun.status == models.HubSyncRun.STATUS_RUNNING)).scalars().all()) + if left: + cleanup.execute(delete(models.HubSyncRun).where(models.HubSyncRun.id.in_(left))) + cleanup.commit() + print(f"[清理] 删掉 {len(ids) + len(left)} 条临时记录(时间 {datetime.now():%H:%M:%S})") + finally: + cleanup.close() + hub_sync.cache = real_cache # type: ignore[assignment] + hub_sync.hubconfig.get = real_hubconfig_get + hub_sync.hub_api.client = real_client + hub_sync.hub_api.sync_token = real_token + db.close() + + print() + if FAILS: + print(f"未通过 {len(FAILS)} 项:") + for name in FAILS: + print(f" - {name}") + return 1 + print(f"全部通过({PASSED} 项):建同步记录那一步出不了锁,「已有同步任务正在执行」不会自己长住。") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/backend/scripts/check_hub_sync_lost_account.py b/backend/scripts/check_hub_sync_lost_account.py new file mode 100644 index 0000000..eb40dcc --- /dev/null +++ b/backend/scripts/check_hub_sync_lost_account.py @@ -0,0 +1,430 @@ +#!/usr/bin/env python3 +"""守「Hub 换了一套数据之后,同步会把人怎么办」这两条:僵尸账号让位、离职停用熔断。 + +踩过的坑:Hub 把人合并或重导之后,``user_id`` 与登录账号的对应关系整体错位。本地那批 +``hub_user_id`` 指向的是已经被删掉的号(Hub 的变更流水只记 upsert、不记删除,本地永远等不到 +那句"此人已走"),于是每一趟全量同步都撞上同一堵墙:活着的人拿不回 Hub 给他的登录名 +("账号已属于另一个统一身份,不抢"),而占着名字的僵尸行只会被停用、不会腾开位置。 +界面上看到的就是同一个人两条 —— 一条「正常」但登录名是上辈子别人的,一条「已停用」占着 +正确的登录名。顺带还有第二次伤害:Hub 一次 renumber 把 87 个人一次性判成离职, +权限、待办、部门负责人当场全没,而且下一趟同步不会自己长回来。 + +这两处都在 :mod:`app.service.hub_sync` 里补了口子,另外把「同步前体检」也拉回同一套判据, +这里钉十八条:: + + cd backend && PYTHONPATH=. python3 scripts/check_hub_sync_lost_account.py + +1. **僵尸让位**:本地已停用 + 这一趟完整清单里查无此人 → 登录名腾开,账号归 Hub 现任主人; +2. **让位只动账号名**:僵尸行的主键、姓名、状态、``hub_user_id`` 一个都不动; +3. **引用跟着僵尸走**:``account_map`` 记的是「原名 → hub-lost-…」,不做链式拼接; +4. **企业微信 UserID 一起腾开**:号被 Hub 挪给活人时,僵尸行清空、活人当场拿到号; +5. **占着账号的是活人就不抢**:照旧只记 ``conflicts``,不动别人的登录名; +6. **本地手工建的号不让位**:哪怕登录时被补绑过 Hub 主键,账号名也是本地自己起的; +7. **应急账号永远不让位**:那个名字就是它存在的意义,跟开关无关; +8. **刚查无此人先停用、下一趟才让位**:Hub 抖一下不该顺手把人改名; +9. **幂等**:同一趟再跑一遍,一个账号名都不会再改; +10. **清单被截断的那一趟一律不让位**:人没拉全,"不在清单里"证明不了任何事; +11. **离职停用熔断**:一批人判成离职超过上限 → 这一趟一个都不停,只报数; +12. **已经停用过的不再计入熔断人数**:熔断数的是"这一次又要停用几个"; +13. **没超过上限就照旧停用**:熔断只在真的过大时挡道,日常几个人离职照常走; +14. **熔断设 0 就关掉**:核对过清单没问题,照样能回到"照单全停"; +15. **判据本身幂等**:已经让过位的行不再是"可让位的僵尸号",体检与同步共用它; +16. **增量事件绝不让位**:一条人员变更只搬来一个人,拿它当清单会把全库的登录名都改了; +17. **改名与让位都算进 ``updated``**:否则"这趟只改了账号名"的同步在历史上显示「无变更」; +18. **Hub 目录突然缩水时先不让位**:清单人数不到上趟的一半(测试站 2026-11-05 从 100 掉到 1), + 说明对方正在清库/重导,这时一个登录名都不改;人数对得上就照常让位。 + +全程待在同一个事务里,跑完 ``rollback``,库里不留任何临时行。 +""" + +from __future__ import annotations + +import dataclasses +import pathlib +import sys +from datetime import datetime + +sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent)) + +from sqlalchemy import select # noqa: E402 + +from app import hubconfig, models # noqa: E402 +from app.db import SessionLocal # noqa: E402 +from app.service import hub_sync # noqa: E402 + +MARK = "zzlost-" +FAILS: list[str] = [] +PASSED = 0 + +# 这批检查自己占的 Hub 主键段:真库里的 user_id 都在几百这一段,9 位数撞不上 +UID_LIVE_A = 900101 +UID_ZOMBIE_A = 900102 +UID_HOLDER_LIVE = 900103 +UID_HUB_B = 900104 +UID_LOCAL_C = 900105 +UID_HUB_C = 900106 +UID_TWO_STEP = 900107 +UID_HUB_E = 900108 +UID_EMERGENCY = 900109 +UID_HUB_D = 900110 +UID_FUSE_BASE = 900200 +UID_INC_ZOMBIE = 900301 +UID_INC_LIVE = 900302 +UID_SHRINK = 900303 + + +def check(label: str, passed: bool, detail: str = "") -> None: + global PASSED + if passed: + PASSED += 1 + print(f"[通过] {label}") + else: + FAILS.append(label) + print(f"[FAIL] {label}{f' -> {detail}' if detail else ''}") + + +def add_user( + db, # noqa: ANN001 + account: str, + *, + hub_user_id: int | None, + display_name: str, + status: int = models.UserStatus.ACTIVE, + source: str = models.AccountSource.HUB, + wecom: str = "", +): # noqa: ANN201 + row = models.User( + account=account, + display_name=display_name, + email="", + mobile="", + password_hash="zz-check", + role=models.ROLE_MEMBER, + status=status, + source=source, + hub_user_id=hub_user_id, + wecom_user_id=wecom, + ) + db.add(row) + db.flush() + return row + + +def hub_item( + user_id: int, account: str, *, name: str = "检查人员", status: int = 1, wecom: str | None = None +) -> dict: + item = { + "user_id": user_id, + "account": account, + "display_name": name, + "status": status, + "organization_id": 0, + } + if wecom is not None: + item["wecom_userid"] = wecom + return item + + +def shadow_items(db) -> list[dict]: # noqa: ANN001 + """给库里已有的同步账号各配一条"什么都不该发生"的清单条目。 + + 不这么做的话,:func:`hub_sync._retire_lost_accounts` 与 :func:`hub_sync._offboard_missing` + 会把真库那 140 个账号一起卷进来,检查数字就没法看了。账号名、姓名、状态、企微号都照 + 本地现状回填,同步走过它们应该一个字段都不改。 + """ + rows = db.execute( + select(models.User).where( + models.User.source == models.AccountSource.HUB, + models.User.hub_user_id.is_not(None), + ) + ).scalars().all() + return [ + hub_item( + int(row.hub_user_id), + row.account, + name=row.display_name, + status=1 if row.status == models.UserStatus.ACTIVE else 0, + wecom=row.wecom_user_id or "", + ) + for row in rows + ] + + +def use_cfg(**patch: object) -> None: + """把 ``hubconfig.get`` 换成一份改过几项的配置,其余字段照原样带着。""" + hubconfig.get = ( # type: ignore[assignment] + lambda db=None, _patch=patch: dataclasses.replace(cfg_obj, **_patch) # noqa: B023 + ) + + +def main() -> int: + global cfg_obj + real_get = hubconfig.get + base_cfg = real_get() + cfg = dataclasses.replace( + base_cfg, + hub_local_accounts=f"{base_cfg.hub_local_accounts},zzlost-emergency", + hub_sync_reclaim_lost_accounts=True, + hub_sync_offboard_guard_percent=40, + ) + cfg_obj = cfg + use_cfg() + db = SessionLocal() + now = datetime.now() + try: + shadows = shadow_items(db) + + # ①②③④ 僵尸让位:账号名与企业微信号一起腾开,物归 Hub 的现任主人 + live_a = add_user(db, f"{MARK}old-a", hub_user_id=UID_LIVE_A, display_name="让位甲") + zombie_a = add_user( + db, f"{MARK}a", hub_user_id=UID_ZOMBIE_A, display_name="让位甲旧号", + status=models.UserStatus.DISABLED, wecom=f"{MARK}wecom-a", + ) + # ⑤ 占着账号的是个活人:不抢 + holder_live = add_user(db, f"{MARK}b", hub_user_id=UID_HOLDER_LIVE, display_name="占位的活人") + # ⑥ 本地手工建的号:绑过 Hub 主键也不让位 + local_c = add_user( + db, f"{MARK}c", hub_user_id=UID_LOCAL_C, display_name="本地建的号", + status=models.UserStatus.DISABLED, source=models.AccountSource.LOCAL, + ) + # ⑦ 应急账号:停用 + 查无此人,照样不让位 + emergency = add_user( + db, "zzlost-emergency", hub_user_id=UID_EMERGENCY, display_name="应急账号", + status=models.UserStatus.DISABLED, + ) + # ⑧ 这一趟才刚查无此人(还没停用):先停用,名字留着下一趟再动 + two_step = add_user(db, f"{MARK}e", hub_user_id=UID_TWO_STEP, display_name="刚离职的") + + roster = shadows + [ + hub_item(UID_LIVE_A, f"{MARK}a", name="让位甲", wecom=f"{MARK}wecom-a"), + hub_item(UID_HUB_B, f"{MARK}b", name="Hub 里的乙"), + hub_item(UID_HUB_C, f"{MARK}c", name="Hub 里的丙"), + hub_item(UID_HUB_D, "zzlost-emergency", name="Hub 里的应急同名者"), + hub_item(UID_HUB_E, f"{MARK}e", name="Hub 里的戊"), + ] + stats = hub_sync.SyncStats(started_at=now) + seen = hub_sync._sync_people(db, roster, {}, stats, now, complete_roster=True) + + check("① 僵尸让位后,Hub 现任主人拿回登录名", live_a.account == f"{MARK}a", + f"live_a.account={live_a.account}") + check("① 腾开的名字带上了 Hub 主键", zombie_a.account == f"{hub_sync.LOST_ACCOUNT_PREFIX}{UID_ZOMBIE_A}-{MARK}a", + f"zombie_a.account={zombie_a.account}") + check("① 这一趟报了一次让位", stats.reclaimed == 1, f"reclaimed={stats.reclaimed}") + # 重查一遍:让位前后必须是同一行(主键不变,按主键挂的权限才不掉) + reloaded = db.execute( + select(models.User).where(models.User.hub_user_id == UID_ZOMBIE_A) + ).scalar_one() + check("② 让位只改账号名:主键、姓名、状态、hub_user_id 都不动", + reloaded.id == zombie_a.id + and zombie_a.display_name == "让位甲旧号" + and zombie_a.status == models.UserStatus.DISABLED + and int(zombie_a.hub_user_id) == UID_ZOMBIE_A, + f"{zombie_a.display_name}/{zombie_a.status}/{zombie_a.hub_user_id}") + check("③ 引用映射记的是「原名 → 让位名」,不接链", + stats.account_map.get(f"{MARK}a") == zombie_a.account + and stats.account_map.get(f"{MARK}old-a") == f"{MARK}a", + str(dict(list(stats.account_map.items())[:5]))) + check("④ 企业微信 UserID 从僵尸行腾开、当场归活人", + zombie_a.wecom_user_id == "" and live_a.wecom_user_id == f"{MARK}wecom-a" + and stats.wecom_released == 1, + f"zombie={zombie_a.wecom_user_id!r} live={live_a.wecom_user_id!r} released={stats.wecom_released}") + check("⑤ 账号属于本地还活着的人:不抢,只记冲突", + holder_live.account == f"{MARK}b" and holder_live.status == models.UserStatus.ACTIVE + and int(holder_live.hub_user_id) == UID_HOLDER_LIVE, + f"holder={holder_live.account}/{holder_live.hub_user_id}") + check("⑥ 本地手工建的账号不因 Hub 查无此人被改名", + local_c.account == f"{MARK}c", f"local_c.account={local_c.account}") + check("⑦ 应急账号不让位", emergency.account == "zzlost-emergency", + f"emergency.account={emergency.account}") + check("⑧ 刚查无此人的先停用、账号名留着", two_step.account == f"{MARK}e" + and two_step.status == models.UserStatus.ACTIVE, + f"{two_step.account}/{two_step.status}") + check("⑧ 让位那条报进了同步记录", + any("查无此人" in text for text in stats.messages), str(stats.messages[:3])) + + # ⑨ 幂等:同一份清单再跑一遍,账号名一个都不该再改 + again = hub_sync.SyncStats(started_at=now) + hub_sync._sync_people(db, roster, {}, again, now, complete_roster=True) + check("⑨ 同一趟再跑一次不再改名", again.reclaimed == 0 and again.wecom_released == 0 + and live_a.account == f"{MARK}a" and zombie_a.account.startswith(hub_sync.LOST_ACCOUNT_PREFIX), + f"reclaimed={again.reclaimed} wecom={again.wecom_released}") + + # ⑩ 清单被截断:一个都不让位(这里先把 two_step 停用,制造一个本可让位的行) + two_step.status = models.UserStatus.DISABLED + db.flush() + cut = hub_sync.SyncStats(started_at=now) + cut.truncated = True + hub_sync._sync_people(db, roster, {}, cut, now, complete_roster=True) + check("⑩ 清单截断的那一趟不让位", cut.reclaimed == 0 and two_step.account == f"{MARK}e", + f"reclaimed={cut.reclaimed} account={two_step.account}") + + # ⑪⑫⑬ 离职停用熔断。熔断线是按"本地同步账号总数的百分比"算的,这里把百分比调到 1%, + # 让它退到那条绝对下限(OFFBOARD_GUARD_MIN_PEOPLE)上,几行临时数据就能把机制验干净。 + fuse_ids = [UID_FUSE_BASE + i for i in range(1, 26)] + fuse_rows = [ + add_user(db, f"{MARK}fuse{i}", hub_user_id=uid, display_name=f"熔断{i}") + for i, uid in enumerate(fuse_ids, start=1) + ] + # 清单里没有这 25 个号,其余(含库里原有的、这一趟"还在"的)都算还在 + seen_all = { + int(hub_user_id) + for hub_user_id in db.execute( + select(models.User.hub_user_id).where(models.User.hub_user_id.is_not(None)) + ).scalars().all() + } - set(fuse_ids) + + use_cfg(hub_sync_offboard_guard_percent=1) + fuse_stats = hub_sync.SyncStats(started_at=now) + hub_sync._offboard_missing(db, seen_all, fuse_stats, now) + check("⑪ 25 人超过熔断下限(20 人)时一个都不停用", + fuse_stats.offboarded == 0 and fuse_stats.offboard_guarded == 25 + and all(row.status == models.UserStatus.ACTIVE for row in fuse_rows), + f"offboarded={fuse_stats.offboarded} guarded={fuse_stats.offboard_guarded}") + check("⑪ 熔断那条写清了人数与出口", + any("熔断" in text and "OFFBOARD_GUARD_PERCENT" in text for text in fuse_stats.messages), + str(fuse_stats.messages[:2])) + # 已经停用的不构成"这一次又要停用几个",所以不该把熔断顶过线 + use_cfg(hub_sync_offboard_guard_percent=40) + resident = { + int(hub_user_id) + for hub_user_id in db.execute( + select(models.User.hub_user_id).where(models.User.hub_user_id.is_not(None)) + ).scalars().all() + } + already = hub_sync.SyncStats(started_at=now) + hub_sync._offboard_missing(db, resident - {UID_ZOMBIE_A}, already, now) + check("⑫ 已停用的人不重复计入熔断人数", + already.offboarded == 0 and already.offboard_guarded == 0 + and zombie_a.status == models.UserStatus.DISABLED, + f"offboarded={already.offboarded} guarded={already.offboard_guarded}") + + # ⑬ 没超过熔断线就照常停用:把 25 个里的 20 个放回清单,只剩 5 人等着停用 + use_cfg(hub_sync_offboard_guard_percent=1) + few = hub_sync.SyncStats(started_at=now) + hub_sync._offboard_missing(db, seen_all | {uid for uid in fuse_ids[:20]}, few, now) + check("⑬ 没超过熔断线就照旧停用", few.offboarded == 5 and few.offboard_guarded == 0, + f"offboarded={few.offboarded} guarded={few.offboard_guarded}") + + use_cfg(hub_sync_offboard_guard_percent=0) + no_guard = hub_sync.SyncStats(started_at=now) + hub_sync._offboard_missing(db, seen_all, no_guard, now) + check("⑭ 熔断设 0 之后照单停用", + no_guard.offboarded == 20 and all( + row.status == models.UserStatus.DISABLED for row in fuse_rows), + f"offboarded={no_guard.offboarded}") + + # 预检与真跑共用一套判据:已经让过位的行不再是"可让位的僵尸号" + use_cfg() + check("⑮ 判据本身幂等:让过位的行不再算僵尸", + not hub_sync._is_lost_account(cfg, zombie_a, {UID_LIVE_A}) + and hub_sync._is_lost_account(cfg, two_step, {UID_LIVE_A}), + f"zombie={zombie_a.account} two_step={two_step.account}") + + # ⑯⑰ 增量事件的口径:_apply_user_event 一次只搬一条人员变更给 _sync_people, + # 手里那一条 payload 根本不是"Hub 的全部人",谁都不许让位(真实库里这一步会改 97 个名字) + use_cfg() + inc_zombie = add_user(db, f"{MARK}f", hub_user_id=UID_INC_ZOMBIE, display_name="增量僵尸", + status=models.UserStatus.DISABLED) + inc_live = add_user(db, f"{MARK}g", hub_user_id=UID_INC_LIVE, display_name="增量活人") + one_event = [hub_item(UID_INC_LIVE, f"{MARK}f", name="增量活人")] + inc_stats = hub_sync.SyncStats(started_at=now) + # 走生产那条路:增量轮询收到一条完整人员对象时交给 _apply_user_event + outcome = hub_sync._apply_user_event( + db, + { + "entity": "user", + "op": "upsert", + "data": { + "id": UID_INC_LIVE, + "account": f"{MARK}f", + "display_name": "增量活人", + "status": 1, + }, + }, + inc_stats, + now, + {}, + ) + check("⑯ 增量事件(一条 payload)不让位,只照旧记冲突", + outcome == hub_sync.APPLIED and inc_stats.reclaimed == 0 + and inc_stats.conflicts == 1 + and inc_zombie.account == f"{MARK}f" and inc_live.account == f"{MARK}g", + f"outcome={outcome} reclaimed={inc_stats.reclaimed} " + f"conflicts={inc_stats.conflicts} " + f"zombie={inc_zombie.account} live={inc_live.account}") + + # 同一件事走全量口径(complete_roster=True)就该让位。清单里只把这两个检查对象摘出去, + # 其余账号照本地现状回填,免得真库那 140 行一起卷进来把数字搅浑。这趟除了账号名 + # 什么都没动,updated 只能靠 renamed_ids / reclaimed 补上,不然历史上就是一行「无变更」。 + full_roster = [ + item + for item in shadow_items(db) + if int(item["user_id"]) not in {UID_INC_LIVE, UID_INC_ZOMBIE} + ] + one_event + full_stats = hub_sync.SyncStats(started_at=now) + hub_sync._sync_people(db, full_roster, {}, full_stats, now, complete_roster=True) + check("⑰ 改名 + 让位都算进 updated,同步历史不显示「无变更」", + full_stats.reclaimed == 1 and full_stats.renamed == 1 + and full_stats.conflicts == 0 and full_stats.created == 0 + and full_stats.renamed_ids == {inc_live.id} and full_stats.updated == 2 + and inc_zombie.account.startswith(hub_sync.LOST_ACCOUNT_PREFIX) + and inc_live.account == f"{MARK}f", + f"reclaimed={full_stats.reclaimed} renamed={full_stats.renamed} " + f"updated={full_stats.updated} ids={sorted(full_stats.renamed_ids)}") + + # ⑱ Hub 目录突然缩水(正在清库/重导):这趟一个登录名都不许改。 + # 基准是"上一次同步记下来的人数",这里临时替掉 state(),不动库里那行。 + shrink = add_user(db, f"{MARK}h", hub_user_id=UID_SHRINK, display_name="缩水期的僵尸", + status=models.UserStatus.DISABLED) + shrink_roster = [ + item for item in shadow_items(db) if int(item["user_id"]) != UID_SHRINK + ] + real_state = hub_sync.state + try: + # 上趟也只看到 7 个人(测试站被清空之后又同步过一次),基准已经不可信了; + # 撑住这道门槛的是"本地有 140 个同步账号"这一条 —— 正是真库 2026-11-05 的状态 + hub_sync.state = lambda _db=None: {"total_users": 7} + thin_roster = [ + hub_item(UID_LIVE_A, live_a.account, name=live_a.display_name, + status=1 if live_a.status == models.UserStatus.ACTIVE else 0) + ] + thin = hub_sync.SyncStats(started_at=now) + hub_sync._sync_people(db, thin_roster, {}, thin, now, complete_roster=True) + check("⑱ 清单人数不到基准一半时不让位,并把原因说出来", + len(shrink_roster) >= hub_sync.OFFBOARD_GUARD_MIN_PEOPLE + and thin.reclaimed == 0 and shrink.account == f"{MARK}h" + and live_a.account == f"{MARK}a" + and any("清库或重导" in text for text in thin.messages), + f"local={len(shrink_roster)} reclaimed={thin.reclaimed} " + f"account={shrink.account} msg={thin.messages[:2]}") + + hub_sync.state = lambda _db=None: {"total_users": len(shrink_roster) + 10} + # 人数对得上(清单 ≈ 本地),照常让位 + ok = hub_sync.SyncStats(started_at=now) + hub_sync._sync_people(db, shrink_roster, {}, ok, now, complete_roster=True) + check("⑱ 人数对得上就照常让位", + ok.reclaimed == 1 and shrink.account.startswith(hub_sync.LOST_ACCOUNT_PREFIX), + f"reclaimed={ok.reclaimed} account={shrink.account}") + finally: + hub_sync.state = real_state + finally: + cfg_obj = base_cfg + hubconfig.get = real_get # type: ignore[assignment] + db.rollback() + db.close() + + print() + if FAILS: + print(f"未通过 {len(FAILS)} 项:") + for name in FAILS: + print(f" - {name}") + return 1 + print( + f"全部通过({PASSED} 项):Hub 换数据之后,僵尸账号会腾位置,整批离职不会被悄悄停用," + "而一条增量事件不会动任何人的登录名。" + ) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/backend/scripts/check_hub_sync_shell_units.py b/backend/scripts/check_hub_sync_shell_units.py new file mode 100644 index 0000000..8b0f81f --- /dev/null +++ b/backend/scripts/check_hub_sync_shell_units.py @@ -0,0 +1,258 @@ +#!/usr/bin/env python3 +"""守「Hub 换过主键留下的空壳部门」:判据、能不能删、一键清理到底删了什么。 + +踩过的坑:Hub 把部门挪了 ``organization_id``(重建、合并、换环境重导)之后,本地靠 +「编码 + 名称」把那一支认回了原部门,旧的那一具就脱开了 —— ``hub_org_id`` 指着一个 +永远不会再出现的组织,状态停在停用,编码与名称都已被在职的孪生部门占用。同步既不认它 +也不并它,组织树上一排重名部门,部门下拉框里点哪个都可能错。以前只能手工「解绑 → 删除」, +一具一具点,测试站上攒过 12 具。 + +这里钉二十一项(含最后那条「库里没留东西」):: + + cd backend && PYTHONPATH=. python3 scripts/check_hub_sync_shell_units.py + +1~5 :判据(同码同名 + 已停用 + 绑过 Hub 才算,少一条都不算); +6~8 :Hub 清单口径(它还认得的停用部门不是壳子;孪生不在清单里也不作数); +9~12 :删不掉的三种情况(有人、有下级、被角色当数据范围)与干净壳子; +13~16:一键清理(预演不落库、真删只删干净的、判据当场重算、再跑一次不重复删)。 + +全程待在同一个事务里,跑完 ``rollback``,库里不留任何临时行。 +""" + +from __future__ import annotations + +import pathlib +import sys +from types import SimpleNamespace + +sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent)) + +from sqlalchemy import func, select # noqa: E402 + +from app import models # noqa: E402 +from app.api import org as org_api # noqa: E402 +from app.db import SessionLocal # noqa: E402 +from app.schemas import UnitShellCleanupBody # noqa: E402 +from app.service import hub_sync # noqa: E402 + +MARK = "zzshell-" +ORG_BASE = 906100 +UID_BASE = 906500 +FAILS: list[str] = [] +PASSED = 0 + + +def check(label: str, passed: bool, detail: str = "") -> None: + global PASSED + if passed: + PASSED += 1 + print(f"[通过] {label}") + else: + FAILS.append(label) + print(f"[FAIL] {label}{f' -> {detail}' if detail else ''}") + + +def add_unit( + db, # noqa: ANN001 + *, + hub_org_id: int | None, + code: str, + name: str, + status=int(models.UnitStatus.ACTIVE), # noqa: B008 + parent=None, # noqa: ANN001 +): # noqa: ANN201 + row = models.Unit( + name=name, + code=code, + alias=code, + description="壳子检查", + parent_id=parent.id if parent else None, + hub_org_id=hub_org_id, + status=status, + ) + db.add(row) + db.flush() + return row + + +def add_user(db, account: str, unit): # noqa: ANN001, ANN201 + row = models.User( + account=account, + display_name="壳子检查人员", + email="", + mobile="", + password_hash="zz-check", + role=models.ROLE_MEMBER, + status=models.UserStatus.ACTIVE, + source=models.AccountSource.LOCAL, + organization_id=unit.id, + ) + db.add(row) + db.flush() + return row + + +def shells(db) -> list[models.Unit]: # noqa: ANN001 + """库内口径(不带 Hub 清单):清理接口用的就是这一份。""" + return hub_sync.find_shell_units(org_api._hub_units(db)) + + +def shell_ids(db) -> set[str]: # noqa: ANN001 + return {str(row.id) for row in shells(db)} + + +def run_cleanup(db, *, ids=None, dry_run=False): # noqa: ANN001, ANN201 + """直接调接口函数:依赖注入的参数自己填,提交换成 flush,全程留在事务里。""" + user = SimpleNamespace(person=SimpleNamespace(id=1), display_name="检查员", ref="zz-check") + real_ip = org_api.client_ip + real_commit = db.commit + org_api.client_ip = lambda request: "127.0.0.1" # type: ignore[assignment] + db.commit = db.flush # type: ignore[method-assign] + try: + payload = org_api.cleanup_shell_units( + UnitShellCleanupBody(ids=ids or [], dry_run=dry_run), + None, # request:client_ip 已被替掉,用不上 + db=db, + user=user, # type: ignore[arg-type] + ) + finally: + org_api.client_ip = real_ip # type: ignore[assignment] + db.commit = real_commit # type: ignore[method-assign] + return payload["data"] if isinstance(payload, dict) and "data" in payload else payload + + +def main() -> int: + db = SessionLocal() + try: + db.begin() + # 一对同名同码的:在职的孪生 + 脱开的旧身子 + twin = add_unit(db, hub_org_id=ORG_BASE + 1, code=f"{MARK}a", name=f"{MARK}研发部") + shell = add_unit(db, hub_org_id=ORG_BASE + 2, code=f"{MARK}a", name=f"{MARK}研发部", + status=models.UnitStatus.DISABLED) + # 反例四则:没有孪生 / 只同码不同名 / 没绑 Hub / 在职的双胞胎本身 + lonely = add_unit(db, hub_org_id=ORG_BASE + 3, code=f"{MARK}b", name=f"{MARK}市场部", + status=models.UnitStatus.DISABLED) + add_unit(db, hub_org_id=ORG_BASE + 4, code=f"{MARK}a", name=f"{MARK}财务部", + status=models.UnitStatus.DISABLED) + add_unit(db, hub_org_id=None, code=f"{MARK}c", name=f"{MARK}本地部", + status=models.UnitStatus.DISABLED) + db.flush() + + found = shell_ids(db) + check("壳子判据命中:同码同名 + 已停用 + 绑过 Hub", str(shell.id) in found, str(sorted(found))) + check("在职的那个不算壳子", str(twin.id) not in found) + check("没有在职同名同码孪生的停用部门不算壳子", str(lonely.id) not in found) + check( + "只同码不同名不算壳子(名称也认不回,删了就是删)", + all(str(row.id) not in found for row in db.execute( + select(models.Unit).where(models.Unit.name == f"{MARK}财务部") + ).scalars().all()), + ) + check("本地自建部门永远不进这批", all(str(row.id) not in found for row in db.execute( + select(models.Unit).where(models.Unit.name == f"{MARK}本地部") + ).scalars().all())) + + # Hub 清单口径:体检时多一条"这一趟清单里确实没有它" + check( + "Hub 这一趟还认得它 → 只是正常停用的部门,不是壳子", + str(shell.id) not in {str(row.id) for row in hub_sync.find_shell_units( + org_api._hub_units(db), roster_org_ids={ORG_BASE + 1, ORG_BASE + 2} + )}, + ) + check( + "孪生部门不在这一趟清单里 → 没人接住这个身份,先别算壳子", + str(shell.id) not in {str(row.id) for row in hub_sync.find_shell_units( + org_api._hub_units(db), roster_org_ids={ORG_BASE + 2} + )}, + ) + check( + "清单口径下照常认得出壳子(孪生在册、自己不册)", + [row.id for row in hub_sync.find_shell_units( + org_api._hub_units(db), roster_org_ids={ORG_BASE + 1} + )] == [shell.id], + ) + + clean_reasons = hub_sync.shell_unit_blockers(db, shell) + check("没人的没下级的没被角色引用的壳子:可以删", clean_reasons == [], str(clean_reasons)) + + member = add_user(db, f"{MARK}p1", shell) + check("壳子上还挂着人 → 拦住", "直属人员 1 人" in " ".join(hub_sync.shell_unit_blockers(db, shell)), + str(hub_sync.shell_unit_blockers(db, shell))) + db.delete(member) + db.flush() + child = add_unit(db, hub_org_id=ORG_BASE + 5, code=f"{MARK}d", name=f"{MARK}下属组", parent=shell) + check("壳子还有下级 → 拦住", "下级部门 1 个" in " ".join(hub_sync.shell_unit_blockers(db, shell)), + str(hub_sync.shell_unit_blockers(db, shell))) + db.delete(child) + db.flush() + role = models.AuthRole(name=f"{MARK}role", data_scope="custom", data_unit_ids=[str(shell.id)]) + db.add(role) + db.flush() + blockers = hub_sync.shell_unit_blockers(db, shell) + check("被权限角色当自定义数据范围 → 拦住(删了会安静少一片范围)", + any("权限角色" in text for text in blockers), str(blockers)) + db.delete(role) + db.flush() + + # 一键清理:预演 → 真删 → 幂等 + result = run_cleanup(db, dry_run=True) + still_there = db.get(models.Unit, shell.id) is not None + check("预演:报出要删的,一行都不动", len(result["deleted"]) == 1 and still_there, str(result)) + result = run_cleanup(db) + check("真删:只删判据命中的干净壳子", + len(result["deleted"]) == 1 and db.get(models.Unit, shell.id) is None, str(result)) + check("没孪生的停用部门一个都没被顺手删掉", db.get(models.Unit, lonely.id) is not None) + logs = int(db.execute( + select(func.count()).select_from(models.OperationLog).where( + models.OperationLog.action == "org_unit_shell_cleanup" + ) + ).scalar() or 0) + check("清理留了一条操作日志(谁删的、删了哪几具)", logs == 1, str(logs)) + result = run_cleanup(db) + check("再跑一次不重复删", result["deleted"] == [] and result["skipped"] == [], str(result)) + result = run_cleanup(db, ids=[str(shell.id)]) + check("传进来的 id 已经不是壳子:跳过并说明原因", + result["deleted"] == [] and result["skipped"] + and "已经不是空壳部门" in result["skipped"][0]["blockers"][0], + str(result)) + + # 判据当场重算:预演讲"能删",真跑之前被人挂上人,就该改成跳过 + shell2 = add_unit(db, hub_org_id=ORG_BASE + 6, code=f"{MARK}e", name=f"{MARK}测试部") + shell3 = add_unit(db, hub_org_id=ORG_BASE + 7, code=f"{MARK}e", name=f"{MARK}测试部", + status=models.UnitStatus.DISABLED) + db.flush() + add_user(db, f"{MARK}p2", shell3) + result = run_cleanup(db, ids=[str(shell3.id)]) + check("清理前重新核对判据与占用:中途被人挂上人就不删了", + result["deleted"] == [] and "直属人员 1 人" in " ".join(result["skipped"][0]["blockers"]), + str(result)) + check("在职的孪生还在原地", db.get(models.Unit, shell2.id) is not None) + finally: + db.rollback() + db.close() + + leftover = 0 + probe = SessionLocal() + try: + leftover = int( + probe.execute( + select(func.count()).select_from(models.Unit).where(models.Unit.code.like(f"{MARK}%")) + ).scalar() + or 0 + ) + finally: + probe.close() + check("临时部门全部随事务回滚,库里不留壳子", leftover == 0, str(leftover)) + + print() + if FAILS: + print(f"未通过 {len(FAILS)} 项:") + for name in FAILS: + print(f" - {name}") + return 1 + print(f"全部通过:{PASSED} 项") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/backend/scripts/check_hub_sync_unit_reclaim.py b/backend/scripts/check_hub_sync_unit_reclaim.py new file mode 100644 index 0000000..bf1286f --- /dev/null +++ b/backend/scripts/check_hub_sync_unit_reclaim.py @@ -0,0 +1,334 @@ +#!/usr/bin/env python3 +"""守「Hub 把 organization_id 整体换了号之后,组织架构会不会裂成两棵树」。 + +踩过的坑:Hub 重导一遍数据、或者合并过一次组织,``organization_id`` 会整体换号 +(实测测试站 2026-11-04:25~36 变成 2~13)。本地只按主键认部门,认不出来就整棵树再建一遍, +于是组织架构页上出现两个「紫光汇智」:一套停用的老部门(真库留了 12 组),一套带人的新部门。 +人是搬过去了,但**按 ``oa_unit.id`` 配的数据范围、按部门配的审批规则与部门负责人留在老行上**, +不报错,只是悄悄解析不到人;按部门路径存的引用也会指到那条已经空了的支路上。 + +修好的口径在 :func:`app.service.hub_sync._sync_units`:开了「按编码认领本地部门」 +(``OA_HUB_SYNC_BIND_LOCAL_BY_CODE``)时,**编码与名称都对得上、而原主键已经不在这趟清单里**的 +老部门会被认回来(换新主键,本地 ``oa_unit.id`` 不动)。钉二十条:: + + cd backend && PYTHONPATH=. python3 scripts/check_hub_sync_unit_reclaim.py + +1. 换了主键的老部门被认回来,不新建; +2. 认回来只换 ``hub_org_id``:本地部门主键、名字与挂在它下面的人都留在原地; +3. 子部门跟着父部门一起接上,``path`` / 部门 DN 重算; +4. 停用的老部门被认回来时状态跟着 Hub 恢复; +5. 名称对不上就不认(按新部门建,老行停用),不靠编码硬猜; +6. 编码对不上同理不认; +7. 同名同编码有好几个僵尸、而且分不出谁住着人时不猜,按新部门建;只有一支底下挂着人时认那一支; +8. 这个编码名称已经被活部门占了时不再认第三次(真库那 12 组重复就是这种状态); +9. 编码名称都对不上的老部门照旧按「Hub 已消失」停用; +10. 认领汇总只写一条同步记录,逐部门一条会把 20 条上限刷满; +11. 再跑同一份清单不重复认领、不重复建号; +12. 关掉「按编码认领」就退回老行为(新建一套); +13. 清单里没有组织时一个都不认("不在清单里"证明不了任何事); +14. 认回来的部门不会被这一趟判成已消失; +15. 认领之后一个 Hub 组织仍然只对一个本地部门(唯一索引没被绕开); +16. 认领不会撞 ``uq_oa_unit_hub_org_id``(旧主键当场让开); +17. **部门停用熔断**:一趟要停用的部门超过上限 → 一个都不停,只报数并把这趟标成部分完成; +18. **熔断设 0 就关掉**:核对过清单没问题,照样能回到"照单停用"; +19. **只有一支壳子住着人时认那一支**; +20. **被熔断挡下来的那趟以「部分完成」收口**:少干了活必须看得见。 + +全程待在同一个事务里,跑完 ``rollback``,库里不留任何临时部门。 +""" + +from __future__ import annotations + +import dataclasses +import pathlib +import sys +from datetime import datetime + +sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent)) + +from sqlalchemy import select # noqa: E402 + +from app import hubconfig, models # noqa: E402 +from app.db import SessionLocal # noqa: E402 +from app.service import hub_sync # noqa: E402 + +MARK = "zzunit-" +FAILS: list[str] = [] +PASSED = 0 + +# 这批检查自己占的 Hub 组织主键段:真库的 organization_id 在个位数~几十这一段 +OLD = {"a": 930001, "b": 930002, "c": 930003, "d1": 930004, "d2": 930005, + "live_e": 930006, "ghost_e": 930007, "g": 930008, "f": 930009} +NEW = {"a": 931001, "b": 931002, "c": 931003, "d": 931004, "e": 931005, "f": 931006} + + +def check(label: str, passed: bool, detail: str = "") -> None: + global PASSED + if passed: + PASSED += 1 + print(f"[通过] {label}") + else: + FAILS.append(label) + print(f"[FAIL] {label}{f' -> {detail}' if detail else ''}") + + +def add_unit(db, code, name, *, hub_org_id=None, parent=None, status=int(models.UnitStatus.ACTIVE)): # noqa: ANN001 + row = models.Unit( + name=name, + code=code, + alias=code, + description="让位检查", + parent_id=parent.id if parent else None, + hub_org_id=hub_org_id, + status=status, + ) + db.add(row) + db.flush() + return row + + +def org_node(hub_id, code, name, *, parent_id=None, status=1) -> dict: + return { + "organization_id": hub_id, + "code": code, + "name": name, + "status": status, + "parent_id": parent_id, + } + + +def shadow_orgs(db) -> list[dict]: # noqa: ANN001 + """把库里已有的 Hub 部门照本地现状列进清单,免得检查数字被真库那 26 个部门搅浑。""" + rows = db.execute( + select(models.Unit).where(models.Unit.hub_org_id.is_not(None)) + ).scalars().all() + by_id = {row.id: row for row in rows} + out = [] + for row in rows: + parent = by_id.get(row.parent_id) if row.parent_id else None + out.append( + org_node( + int(row.hub_org_id), + str(row.code or ""), + str(row.name or ""), + parent_id=int(parent.hub_org_id) if parent and parent.hub_org_id else None, + status=1 if row.status == models.UnitStatus.ACTIVE else 0, + ) + ) + return out + + +def use_cfg(**patch: object) -> None: + """把 ``hubconfig.get`` 换成一份改过几项的配置,其余字段照原样带着。""" + hubconfig.get = ( # type: ignore[assignment] + lambda db=None, _patch=patch: dataclasses.replace(cfg_obj, **_patch) # noqa: B023 + ) + + +def main() -> int: + global cfg_obj + real_get = hubconfig.get + base_cfg = real_get() + cfg_obj = dataclasses.replace(base_cfg, hub_sync_bind_local_by_code=True) + use_cfg() + db = SessionLocal() + now = datetime.now() + try: + # 先把真库已有的 Hub 部门照现状列进清单:它们这一趟都该"对得上号", + # 不然检查数字会被真库那 26 个部门搅浑。注意要在造临时部门之前拍这张快照, + # 否则这批 93000x 的老主键会被当成"还在清单里",僵尸判定就试不出来了。 + base_shadow = shadow_orgs(db) + + # ---- 本地现状:Hub 换号之前那一套部门(老主键 93000x) ---- + unit_a = add_unit(db, f"{MARK}a", "换号甲", hub_org_id=OLD["a"], + status=int(models.UnitStatus.DISABLED)) # 上一趟被判成已消失、已停用 + unit_b = add_unit(db, f"{MARK}b", "换号乙", hub_org_id=OLD["b"], parent=unit_a) + person = db.execute( + select(models.User).where(models.User.source == models.AccountSource.HUB) + ).scalars().first() + person.organization_id = unit_b.id + unit_c = add_unit(db, f"{MARK}c", "老名字丙", hub_org_id=OLD["c"]) + unit_d1 = add_unit(db, f"{MARK}d", "换号丁", hub_org_id=OLD["d1"]) + unit_d2 = add_unit(db, f"{MARK}d", "换号丁", hub_org_id=OLD["d2"]) + unit_live_e = add_unit(db, f"{MARK}e", "换号戊", hub_org_id=OLD["live_e"]) + unit_ghost_e = add_unit(db, f"{MARK}e", "换号戊", hub_org_id=OLD["ghost_e"], + status=int(models.UnitStatus.DISABLED)) + unit_g = add_unit(db, f"{MARK}g", "彻底没了", hub_org_id=OLD["g"]) + unit_f = add_unit(db, f"{MARK}f", "关掉开关", hub_org_id=OLD["f"]) + db.flush() + + # Hub 换号之后的清单:主键全换成 93100x,编码与名称原样 + nodes = base_shadow + [ + org_node(NEW["a"], f"{MARK}a", "换号甲"), + org_node(NEW["b"], f"{MARK}b", "换号乙", parent_id=NEW["a"]), + org_node(NEW["c"], f"{MARK}c", "改了名字丙"), # 名称对不上 -> 不认 + org_node(NEW["d"], f"{MARK}d", "换号丁"), # 两个僵尸 -> 不猜 + org_node(NEW["e"], f"{MARK}e", "换号戊"), # 已经被活部门占了 -> 不认第三次 + org_node(OLD["live_e"], f"{MARK}e", "换号戊"), # 活的那一支:主键还在清单里 + ] + stats = hub_sync.SyncStats(started_at=now) + mapped = hub_sync._sync_units(db, nodes, stats) + db.flush() + + check("① 换了主键的老部门被认回来,没有新建", + mapped.get(NEW["a"]) == unit_a.id and mapped.get(NEW["b"]) == unit_b.id + and stats.units_rebound == 2 and stats.units_bound == 2, + f"rebound={stats.units_rebound} bound={stats.units_bound} mapped={mapped.get(NEW['a'])}/{unit_a.id}") + check("⑥ 编码对不上的老部门不认,按新部门建", + stats.units_created == 3, # 丙(改名)、丁(歧义)、戊(busy) + f"created={stats.units_created}") + check("② 本地部门主键与名称没动,人还在原来那个部门下", + unit_a.hub_org_id == NEW["a"] and unit_a.name == "换号甲" + and unit_b.hub_org_id == NEW["b"] and person.organization_id == unit_b.id, + f"hub={unit_a.hub_org_id} person_unit={person.organization_id}") + check("③ 子部门跟着接上,path 一起重算", + unit_b.parent_id == unit_a.id and unit_b.path.endswith("换号乙\\"), + f"parent={unit_b.parent_id} path={unit_b.path}") + check("④ 停用的老部门被认回来时状态跟着 Hub 恢复", + unit_a.status == models.UnitStatus.ACTIVE, f"status={unit_a.status}") + check("⑤ 名称对不上就不认:老行走停用、按新部门建", + unit_c.status == models.UnitStatus.DISABLED + and mapped.get(NEW["c"]) not in (None, unit_c.id), + f"c_status={unit_c.status} new={mapped.get(NEW['c'])}") + check("⑦ 同名同编码有好几个僵尸时不猜", + mapped.get(NEW["d"]) not in (unit_d1.id, unit_d2.id) + and unit_d1.status == models.UnitStatus.DISABLED + and unit_d2.status == models.UnitStatus.DISABLED, + f"new={mapped.get(NEW['d'])} d1={unit_d1.status} d2={unit_d2.status}") + check("⑧ 这个编码名称已经被活部门占了:不再认第三次", + unit_live_e.hub_org_id == OLD["live_e"] + and unit_live_e.status == models.UnitStatus.ACTIVE + and mapped.get(NEW["e"]) not in (unit_ghost_e.id,), + f"live_hub={unit_live_e.hub_org_id} new={mapped.get(NEW['e'])}") + check("⑨ 编码名称都对不上的老部门照旧停用", + unit_g.status == models.UnitStatus.DISABLED, f"g_status={unit_g.status}") + check("⑩ 认领汇总只写一条同步记录", + sum("认回了原部门" in text for text in stats.messages) == 1, + str([t for t in stats.messages if "认回" in t])) + check("⑯ 认领没撞唯一键:旧主键当场让开", + db.execute(select(models.Unit).where(models.Unit.hub_org_id == OLD["a"])).scalar() is None, + "旧 Hub 主键还被占着") + # 这一趟该停用的只有对不上号的五具壳子(丙/丁×2/彻底没了/关掉开关), + # 认回来的甲乙不在其中 + check("⑭ 认回来的部门不会被这一趟判成已消失", + stats.units_offboarded == 5 + and unit_a.status == models.UnitStatus.ACTIVE + and unit_b.status == models.UnitStatus.ACTIVE, + f"offboarded={stats.units_offboarded} a={unit_a.status} b={unit_b.status}") + + # ⑪ 幂等:同一份清单再跑一遍,一个部门都不该再动 + again = hub_sync.SyncStats(started_at=now) + hub_sync._sync_units(db, nodes, again) + check("⑪ 再跑一遍不重复认领、不重复建号、不重复停用", + again.units_rebound == 0 and again.units_created == 0 + and again.units_offboarded == 0 and again.units_updated == 0, + f"rebound={again.units_rebound} created={again.units_created} " + f"offboarded={again.units_offboarded} updated={again.units_updated}") + + # ⑮ 认领完还是一个 Hub 组织对一个部门(uq_oa_unit_hub_org_id 没被绕开)。 + # 库上有唯一索引,"一个组织两个部门"那种历史脏行在这套 schema 上已经插不进来了。 + from sqlalchemy import func # 就地用一次,别顶到文件头去 + + holders = { + hub_id: int( + db.execute( + select(func.count()) + .select_from(models.Unit) + .where(models.Unit.hub_org_id == hub_id) + ).scalar_one() + ) + for hub_id in (NEW["a"], NEW["b"], OLD["a"], OLD["b"]) + } + check("⑮ 认领之后一个 Hub 组织只对一个部门", + holders[NEW["a"]] == 1 and holders[NEW["b"]] == 1 + and holders[OLD["a"]] == 0 and holders[OLD["b"]] == 0, + str(holders)) + + # ⑫ 关掉「按编码认领」就退回老行为 + use_cfg(hub_sync_bind_local_by_code=False) + nodes_off = base_shadow + [org_node(NEW["f"], f"{MARK}f", "关掉开关")] + off = hub_sync.SyncStats(started_at=now) + mapped_off = hub_sync._sync_units(db, nodes_off, off) + check("⑫ 开关关掉之后不认领,按新部门建", + off.units_rebound == 0 and mapped_off.get(NEW["f"]) not in (None, unit_f.id) + and unit_f.hub_org_id == OLD["f"], + f"rebound={off.units_rebound} new={mapped_off.get(NEW['f'])} hub={unit_f.hub_org_id}") + + # ⑬ 清单里一个组织都没有:不认、不新建 + use_cfg() + empty = hub_sync.SyncStats(started_at=now) + hub_sync._sync_units(db, [], empty) + check("⑬ 空清单不认领任何部门", empty.units_rebound == 0 and empty.units_bound == 0, + f"rebound={empty.units_rebound} bound={empty.units_bound}") + + # ⑲ 同码同名的壳子分不出谁是谁时看谁住着人:真库那 12 组重复就是这种形状 + shell_t1 = add_unit(db, f"{MARK}t", "换号己", hub_org_id=930021, + status=int(models.UnitStatus.DISABLED)) + shell_t2 = add_unit(db, f"{MARK}t", "换号己", hub_org_id=930022, + status=int(models.UnitStatus.DISABLED)) + person.organization_id = shell_t2.id # 只有这一支底下还住着人 + db.flush() + tie = hub_sync.SyncStats(started_at=now) + mapped_tie = hub_sync._sync_units( + db, base_shadow + [org_node(931011, f"{MARK}t", "换号己")], tie + ) + check("⑲ 只有一支壳子底下挂着人时认那一支", + tie.units_rebound == 1 and mapped_tie.get(931011) == shell_t2.id + and shell_t2.hub_org_id == 931011 + and shell_t1.status == models.UnitStatus.DISABLED, + f"rebound={tie.units_rebound} 认到={mapped_tie.get(931011)}/{shell_t2.id}") + + # ⑰⑱ 部门停用熔断:Hub 目录少了一批组织时,别一声不响把半棵树停掉 + fuse = [ + add_unit(db, f"{MARK}fuse{i}", f"熔断部门{i}", hub_org_id=930010 + i) + for i in range(1, 7) + ] + db.flush() + # 熔断这一段用"所有部门都在清单里"的节点表,只留那六个新壳子当等着停用的人数 + fuse_nodes = nodes + [ + org_node(NEW["f"], f"{MARK}f", "关掉开关"), + org_node(931011, f"{MARK}t", "换号己"), + ] + use_cfg(hub_sync_offboard_guard_percent=1) # 上限退到绝对下限 5 个,六个就能触发 + fuse_stats = hub_sync.SyncStats(started_at=now) + hub_sync._sync_units(db, fuse_nodes, fuse_stats) + check("⑰ 六个部门超过熔断上限(5 个)时一个都不停用", + fuse_stats.units_offboarded == 0 and fuse_stats.units_offboard_guarded == 6 + and all(row.status == models.UnitStatus.ACTIVE for row in fuse), + f"offboarded={fuse_stats.units_offboarded} guarded={fuse_stats.units_offboard_guarded}") + check("⑰ 熔断那条写清了个数与出口", + any("部门停用熔断线" in text and "OFFBOARD_GUARD_PERCENT" in text + for text in fuse_stats.messages), + str([t for t in fuse_stats.messages if "熔断" in t][:1])) + + check("⑳ 被熔断挡下来的那趟以「部分完成」收口", + hub_sync._run_status(fuse_stats) == models.HubSyncRun.STATUS_PARTIAL + and hub_sync._run_status(hub_sync.SyncStats(started_at=now)) + == models.HubSyncRun.STATUS_SUCCESS, + hub_sync._run_status(fuse_stats)) + + use_cfg(hub_sync_offboard_guard_percent=0) + off_stats = hub_sync.SyncStats(started_at=now) + hub_sync._sync_units(db, fuse_nodes, off_stats) + check("⑱ 熔断设 0 之后照单停用", + off_stats.units_offboarded == 6 + and all(row.status == models.UnitStatus.DISABLED for row in fuse), + f"offboarded={off_stats.units_offboarded}") + finally: + cfg_obj = base_cfg + hubconfig.get = real_get # type: ignore[assignment] + db.rollback() + db.close() + + print() + if FAILS: + print(f"未通过 {len(FAILS)} 项:") + for name in FAILS: + print(f" - {name}") + return 1 + print(f"全部通过({PASSED} 项):Hub 换组织主键之后认回原部门,组织架构不再裂成两棵树。") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/backend/scripts/check_hub_sync_wecom_mirror.py b/backend/scripts/check_hub_sync_wecom_mirror.py new file mode 100644 index 0000000..30e0409 --- /dev/null +++ b/backend/scripts/check_hub_sync_wecom_mirror.py @@ -0,0 +1,319 @@ +#!/usr/bin/env python3 +"""守「企业微信 UserID 这一列照抄 Hub」这条:上游给什么,本地就是什么。 + +踩过的坑(2026-11-05 测试站):Hub 目录把同一个企微号 ``chenhao2`` 同时发给了 +``user_id=1``(``admin``)和 ``user_id=455``(``chenhao``)。老口径是"一个号只挂一个人, +撞上就后到的那个不写",于是界面上 ``chenhao`` 这一列永远是空的 —— 而空串在这套同步里 +另有含义(Hub 说这个人没企微号),谁也分不清是"上游没给"还是"本地没敢写"。 +这一列是**镜像**,不是本地唯一键:共用一个号就几个人都挂着它,本地只把这件事报出来。 + +这里钉十二条:: + + cd backend && PYTHONPATH=. python3 scripts/check_hub_sync_wecom_mirror.py + +1. **同一个号发给几个人就写几个人**:都落库,同时记 ``wecom_conflicts``; +2. **幂等**:同一份清单再跑一遍,一个号都不再改写,也不再报冲突; +3. **"这列下发了、这个人没带键"仍然清空**:照抄也包括抄"没号"这件事; +4. **Hub 直接给空串同样清空**; +5. **一条增量补丁清空不了任何人**:补丁没带这个键就是没提这件事; +6. **脏值覆盖不了本地的好号**:中文、带空格、超长的 UserID 只报 ``wecom_invalid``; +7. **号被 Hub 挪给活人时,僵尸行照样当场腾开**(C14 那半没被写坏); +8. **洗号规则没被绕过**:合法字符集外的东西一个字节都进不了库; +9. **冲突不影响别的列**:撞号的人姓名、部门、状态照常跟着 Hub 走; +10. **增量同步的提示整趟只报一次**,且报的是累计人数(不是第一条事件时的零头); +11. **单条补丁撞上别人的号 / 带了个脏值**:当场点名是谁、哪个号,别默默写进去。 + +全程待在同一个事务里,跑完 ``rollback``,库里不留任何临时行。 +""" + +from __future__ import annotations + +import pathlib +import sys +from datetime import datetime + +sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent.parent)) + +from sqlalchemy import select # noqa: E402 + +from app import models # noqa: E402 +from app.db import SessionLocal # noqa: E402 +from app.service import hub_sync # noqa: E402 + +MARK = "zzwecom-" +FAILS: list[str] = [] +PASSED = 0 + +# 这批检查自己占的 Hub 主键段:真库里的 user_id 都在几百这一段,9 位数撞不上 +UID_SHARED_A = 900401 +UID_SHARED_B = 900402 +UID_GONE_WECOM = 900403 +UID_DIRTY = 900404 +UID_ZOMBIE = 900405 +UID_MOVED = 900406 +UID_WILD = 900407 +UID_PATCH_A = 900408 +UID_PATCH_B = 900409 +UID_PATCH_C = 900410 +UID_PATCH_D = 900411 +SHARED_ID = f"{MARK}shared" +MOVED_ID = f"{MARK}moved" +SHARED_ID2 = f"{MARK}shared2" + + +def check(label: str, passed: bool, detail: str = "") -> None: + global PASSED + if passed: + PASSED += 1 + print(f"[通过] {label}") + else: + FAILS.append(label) + print(f"[FAIL] {label}{f' -> {detail}' if detail else ''}") + + +def add_user( + db, # noqa: ANN001 + account: str, + *, + hub_user_id: int | None, + display_name: str, + status: int = models.UserStatus.ACTIVE, + source: str = models.AccountSource.HUB, + wecom: str = "", +): # noqa: ANN201 + row = models.User( + account=account, + display_name=display_name, + email="", + mobile="", + password_hash="zz-check", + role=models.ROLE_MEMBER, + status=status, + source=source, + hub_user_id=hub_user_id, + wecom_user_id=wecom, + ) + db.add(row) + db.flush() + return row + + +def hub_item( + user_id: int, + account: str, + *, + name: str = "检查人员", + status: int = 1, + wecom: str | None = None, + org: int = 0, +) -> dict: + """造一条 Hub 目录里的人员对象;``wecom=None`` 是**压根不带这个键**。""" + item = { + "user_id": user_id, + "account": account, + "display_name": name, + "status": status, + "organization_id": org, + } + if wecom is not None: + item["wecom_userid"] = wecom + return item + + +def shadow_items(db) -> list[dict]: # noqa: ANN001 + """给库里已有的同步账号各配一条"什么都不该发生"的清单条目。 + + 不这么做的话,僵尸让位与离职判定会把真库那批账号一起卷进来,检查数字没法看。 + 账号名、姓名、状态、企微号都照本地现状回填,同步走过它们应该一个字段都不改。 + """ + rows = db.execute( + select(models.User).where( + models.User.source == models.AccountSource.HUB, + models.User.hub_user_id.is_not(None), + ) + ).scalars().all() + return [ + hub_item( + int(row.hub_user_id), + row.account, + name=row.display_name, + status=1 if row.status == models.UserStatus.ACTIVE else 0, + wecom=row.wecom_user_id or "", + ) + for row in rows + ] + + +def main() -> int: + db = SessionLocal() + now = datetime.now() + try: + # ①② 一个号发给两个人:两个人都写上,只报数不改判 + first = add_user(db, f"{MARK}first", hub_user_id=UID_SHARED_A, display_name="撞号前的甲") + second = add_user(db, f"{MARK}second", hub_user_id=UID_SHARED_B, display_name="撞号前的乙") + third = add_user(db, f"{MARK}third", hub_user_id=UID_GONE_WECOM, display_name="要没号了") + third.wecom_user_id = f"{MARK}old" + dirty = add_user(db, f"{MARK}dirty", hub_user_id=UID_DIRTY, display_name="带脏值的") + dirty.wecom_user_id = f"{MARK}good" + db.flush() + + roster = [ + hub_item(UID_SHARED_A, f"{MARK}first", name="共用甲", wecom=SHARED_ID), + hub_item(UID_SHARED_B, f"{MARK}second", name="共用乙", wecom=SHARED_ID), + # 这一列这趟是下发过的(上面两位带了键),这位没带 = Hub 说他没企微号 + hub_item(UID_GONE_WECOM, f"{MARK}third", name="要没号了"), + hub_item(UID_DIRTY, f"{MARK}dirty", name="带脏值的", wecom="不是个号"), + ] + stats = hub_sync.SyncStats(started_at=now) + hub_sync._sync_people(db, roster, {}, stats, now) + + check("① Hub 把同一个号发给两个人,两个人都挂上这个号", + first.wecom_user_id == SHARED_ID and second.wecom_user_id == SHARED_ID + and stats.wecom_updated == 2, + f"first={first.wecom_user_id!r} second={second.wecom_user_id!r} " + f"updated={stats.wecom_updated}") + check("① 共用一个号照样报出来(记 wecom_conflicts,不再少写一个人)", + stats.wecom_conflicts == 1, f"conflicts={stats.wecom_conflicts}") + check("① 撞号不牵连别的列:姓名照旧跟着 Hub 走", + first.display_name == "共用甲" and second.display_name == "共用乙", + f"{first.display_name}/{second.display_name}") + check("③ 这列下发了、这个人没带键 → 本地清空", + third.wecom_user_id == "" and stats.wecom_cleared == 1, + f"third={third.wecom_user_id!r} cleared={stats.wecom_cleared}") + check("⑥ 洗不出合法 UserID 的脏值不覆盖本地好号,只报 wecom_invalid", + dirty.wecom_user_id == f"{MARK}good" and stats.wecom_invalid == 1, + f"dirty={dirty.wecom_user_id!r} invalid={stats.wecom_invalid}") + + # ② 幂等:同一份清单再来一趟,一个字节都不该再动 + again = hub_sync.SyncStats(started_at=now) + hub_sync._sync_people(db, roster, {}, again, now) + check("② 同一趟再跑一遍不再改写、也不再报冲突", + again.wecom_updated == 0 and again.wecom_conflicts == 0 + and again.wecom_cleared == 0 + and first.wecom_user_id == SHARED_ID and second.wecom_user_id == SHARED_ID, + f"updated={again.wecom_updated} conflicts={again.wecom_conflicts} " + f"cleared={again.wecom_cleared}") + + # ⑤ 增量事件:一条补丁没带这个键,就证明不了"这个人没企微号" + patch = hub_sync.SyncStats(started_at=now) + hub_sync._sync_people(db, [hub_item(UID_SHARED_A, f"{MARK}first", name="共用甲改名")], + {}, patch, now) + check("⑤ 只搬来一条补丁(没带企微键)时不清空、也不改写", + first.wecom_user_id == SHARED_ID and patch.wecom_cleared == 0 + and patch.wecom_updated == 0 and first.display_name == "共用甲改名", + f"wecom={first.wecom_user_id!r} cleared={patch.wecom_cleared}") + + # ④ Hub 直接把值给成空串:同样是"这个人没号" + blank = hub_sync.SyncStats(started_at=now) + hub_sync._sync_people( + db, [hub_item(UID_SHARED_B, f"{MARK}second", name="共用乙", wecom="")], {}, blank, now + ) + check("④ Hub 带了这个键、值是空串 → 本地跟着清空", + second.wecom_user_id == "" and blank.wecom_cleared == 1, + f"second={second.wecom_user_id!r} cleared={blank.wecom_cleared}") + + # ⑦ 号被 Hub 挪给活人:僵尸行腾开,物归现任主人(完整清单才做这件事) + db.rollback() + shadows = shadow_items(db) + zombie = add_user(db, f"{MARK}zombie", hub_user_id=UID_ZOMBIE, + display_name="僵尸占位", status=models.UserStatus.DISABLED, + wecom=MOVED_ID) + live = add_user(db, f"{MARK}live", hub_user_id=UID_MOVED, display_name="现任主人") + full = shadows + [ + hub_item(UID_MOVED, f"{MARK}live", name="现任主人", wecom=MOVED_ID), + ] + moved_stats = hub_sync.SyncStats(started_at=now) + hub_sync._sync_people(db, full, {}, moved_stats, now, complete_roster=True) + check("⑦ 号被 Hub 挪给活人时,僵尸行当场腾开、活人拿到号", + zombie.wecom_user_id == "" and live.wecom_user_id == MOVED_ID + and moved_stats.wecom_released == 1, + f"zombie={zombie.wecom_user_id!r} live={live.wecom_user_id!r} " + f"released={moved_stats.wecom_released}") + + # ⑧ 洗号规则没被绕过:野路子 UserID 一个字节都进不了库 + probe = hub_sync.SyncStats(started_at=now) + wild = add_user(db, f"{MARK}wild", hub_user_id=UID_WILD, display_name="野值") + db.flush() + for raw in ("张三", "zhang san", "a", "0", "x" * 65): + hub_sync._sync_people( + db, [hub_item(UID_WILD, f"{MARK}wild", name="野值", wecom=raw)], + {}, probe, now, + ) + check("⑧ 中文/带空格/单字符/单个 0/超长都进不了库,本地留空", + wild.wecom_user_id == "" and probe.wecom_invalid == 5 + and probe.wecom_updated == 0, + f"wild={wild.wecom_user_id!r} invalid={probe.wecom_invalid} " + f"updated={probe.wecom_updated}") + + # ⑨⑩ 增量同步的提示:整趟只报一次,数字按累计算;单条补丁要当场点名 + #(2026-11-05 测试站一趟变更同步里,同样两句提示重复了 5 遍,数字还停在 1 人) + db.rollback() + pa = add_user(db, f"{MARK}patch-a", hub_user_id=UID_PATCH_A, display_name="甲") + pb = add_user(db, f"{MARK}patch-b", hub_user_id=UID_PATCH_B, display_name="乙") + pc = add_user(db, f"{MARK}patch-c", hub_user_id=UID_PATCH_C, display_name="丙") + pd = add_user(db, f"{MARK}patch-d", hub_user_id=UID_PATCH_D, display_name="丁") + pd.wecom_user_id = f"{MARK}keeper" + db.flush() + + inc = hub_sync.SyncStats(started_at=now) + for uid in (UID_PATCH_A, UID_PATCH_B, UID_PATCH_C): + hub_sync._apply_user_event( + db, + {"entity": "user", "op": "upsert", + "data": {"user_id": uid, "account": f"{MARK}patch-{chr(96 + uid - UID_PATCH_A + 1)}", + "display_name": "事件带来的人", "wecom_userid": SHARED_ID2}}, + inc, now, {}, + ) + hub_sync._report_run_notes(inc) + shared_lines = [m for m in inc.messages if "和别人是同一个号" in m] + check("⑨ 三条增量事件撞同一个号:整趟只提示一次", + len(shared_lines) == 1 and inc.wecom_conflicts == 2, + f"{len(shared_lines)} 条提示 conflicts={inc.wecom_conflicts}") + check("⑨ 提示里的数字是整趟累计的(2 个人,不是第一次的 1 个人)", + bool(shared_lines) and "2 个人" in shared_lines[0], + shared_lines[0] if shared_lines else "(没有提示)") + check("⑨ 三个人照样都挂上了这个号", + pa.wecom_user_id == pb.wecom_user_id == pc.wecom_user_id == SHARED_ID2, + f"{pa.wecom_user_id!r} {pb.wecom_user_id!r} {pc.wecom_user_id!r}") + + hub_sync._apply_user_event( + db, + {"entity": "user", "op": "upsert", + "data": {"id": UID_PATCH_D, "wecom_userid": SHARED_ID2}}, + inc, now, {}, + ) + named = [m for m in inc.messages if f"{MARK}patch-d" in m and SHARED_ID2 in m] + check("⑩ 单条补丁撞上别人的号:当场点是谁撞了哪个号,号照样写上", + len(named) == 1 and pd.wecom_user_id == SHARED_ID2, + f"{len(named)} 条提示 wecom={pd.wecom_user_id!r}") + + before = list(inc.messages) + hub_sync._apply_user_event( + db, + {"entity": "user", "op": "upsert", + "data": {"id": UID_PATCH_D, "wecom_userid": "张三"}}, + inc, now, {}, + ) + dirty_lines = [m for m in inc.messages[len(before):] if "洗不出合法 UserID" in m] + check("⑩ 单条补丁带了个洗不出的脏值:只报不改,本地这一列原样留着", + len(dirty_lines) == 1 and pd.wecom_user_id == SHARED_ID2 + and inc.wecom_invalid == 1, + f"{len(dirty_lines)} 条提示 wecom={pd.wecom_user_id!r} " + f"invalid={inc.wecom_invalid}") + finally: + db.rollback() + db.close() + + print() + if FAILS: + print(f"未通过 {len(FAILS)} 项:") + for name in FAILS: + print(f" - {name}") + return 1 + print(f"全部通过({PASSED} 项):企业微信 UserID 这一列照抄 Hub —— " + "给几个人就写几个人,没给就清空,脏值只报数不覆盖好号。") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/backend/scripts/check_notify_hub.py b/backend/scripts/check_notify_hub.py new file mode 100644 index 0000000..9f3ea33 --- /dev/null +++ b/backend/scripts/check_notify_hub.py @@ -0,0 +1,749 @@ +#!/usr/bin/env python3 +"""守 Hub 企业微信推送(``app/service/channels.py`` 的 ``hub_*`` 那一层)。 + +对接口径是对接文档 9.6:OA 只调 Hub 一次 HTTP,Hub 负责换成企业微信的应用消息、 +认点击人的身份、再签一张一次性票据把人送回 OA。**OA 不持有企微密钥**,所以这一路 +最容易做错的四件事全在 OA 这一侧,本脚本用一台**进程内的假 Hub** 逐条钉住:: + + cd backend && PYTHONPATH=. python3 scripts/check_notify_hub.py + +1. **预算**:Hub 对超长是 400 硬拒(整批没人收到),不是替你截断——标题、正文、 + markdown 字节数都得自己先卡住; +2. **幂等键**:``msg_key`` 必须跨重试不变(超时才能原样重发),而"已投出去之后人工 + 补发"必须换世代(同键只会命中 Hub 的缓存,人不会重复收到,运维却以为发了); +3. **逐人结果才算数**:HTTP 200 + ``code=="200"`` 只代表 Hub 听懂了,这个人收到没有 + 要看 ``recipients[].status`` / ``reason``,并按原因分档(重试 / 跳过 / 死信); + ``sent/partial/failed``、``duplicate``、``403 开关没开``、``409 还在发送中``、 + ``5xx 可重试`` 一层层都要落对; +4. **深链是相对路径**:``target_path`` 绝不能带域名——Hub 按登记的 ``home_url`` 在 + 点击时刻现拼,写死域名等于把域名焊进一条永久有效的链接里。 +5. **深链还得认人**:``/todo/`` 是个人页面,而 ``engine.notify()`` 对整批收件人 + 只传一个 ``task=``;一人一条入队时必须按人分,旁人退回 ``/work/``。 +6. **Hub 拼不出深链时别把消息丢掉**:Hub 应用没登记 ``home_url`` 时,带 ``target_path`` + 的请求是整条 400(一个人收不到);本系统摘掉深链、换个键再发一次纯提醒。其它参数类 + 400 不许瞎降级,照旧判死、照旧只打一次。 + +不连库、不打真 Hub、不写任何配置。 +""" + +from __future__ import annotations + +import json +import sys +import threading +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from types import SimpleNamespace +from typing import Any + +from app import hubconfig, models +from app.service import channels + + +# --------------------------------------------------------------------------- +# 假 Hub:记请求、按脚本回包 +# --------------------------------------------------------------------------- + +class FakeHub: + """按脚本回包的假 Hub。``script`` 是 ``(status, payload)`` 的队列,取完用最后一个。""" + + def __init__(self) -> None: + self.requests: list[dict[str, Any]] = [] + self.script: list[tuple[int, dict[str, Any]]] = [] + hub = self + + class Handler(BaseHTTPRequestHandler): + protocol_version = "HTTP/1.1" + + def do_POST(self): # noqa: N802 + self._handle("POST") + + def do_GET(self): # noqa: N802 + self._handle("GET") + + def _handle(self, method: str) -> None: + length = int(self.headers.get("Content-Length") or 0) + raw = self.rfile.read(length) if length else b"" + try: + body = json.loads(raw.decode("utf-8")) if raw else None + except ValueError: + body = raw.decode("utf-8", "replace") + hub.requests.append({ + "method": method, + "path": self.path, + "key": self.headers.get("X-Integration-Key") or "", + "body": body, + }) + status, payload = hub.script.pop(0) if len(hub.script) > 1 else ( + hub.script[0] if hub.script else (200, {"code": "200", "data": {}})) + data = json.dumps(payload, ensure_ascii=False).encode("utf-8") + self.send_response(status) + self.send_header("Content-Type", "application/json; charset=utf-8") + self.send_header("Content-Length", str(len(data))) + self.end_headers() + self.wfile.write(data) + + def log_message(self, *args): # 别往 stdout 上刷屏 + return + + self.server = ThreadingHTTPServer(("127.0.0.1", 0), Handler) + self.thread = threading.Thread(target=self.server.serve_forever, daemon=True) + self.thread.start() + + @property + def base_url(self) -> str: + host, port = self.server.server_address[:2] + return f"http://{host}:{port}" + + @property + def last(self) -> dict[str, Any]: + return self.requests[-1] + + def close(self) -> None: + self.server.shutdown() + self.server.server_close() + + +def envelope(**data) -> tuple[int, dict[str, Any]]: + return 200, {"code": "200", "message": "success", "data": data} + + +def rejected(status: int, code: str, message: str = "示例文案") -> tuple[int, dict[str, Any]]: + """请求级被拒:HTTP 状态码 + 信封里的 code,``data`` 是 null(文档 9.6.4)。""" + return status, {"code": code, "message": message, "data": None} + + +def hub_data(**overrides) -> dict[str, Any]: + """一次投递的标准回执:一个人、投出去了。""" + data = { + "msg_key": "oa-x", + "status": "sent", + "grant": "a" * 24, + "link": "https://hub.example.com/auth/go/" + "a" * 24, + "attempt": 1, + "sent_at": "2026-11-04T06:00:00Z", + "recipients": [{"receiver": "10086", "user_id": 10086, + "wecom_userid": "zhangsan", "status": "sent"}], + } + data.update(overrides) + return data + + +def failed(reason: str, receiver: str = "10086") -> tuple[int, dict[str, Any]]: + return envelope(**hub_data( + status="failed", link="", grant="", + recipients=[{"receiver": receiver, "status": "failed", "reason": reason}], + )) + + +# --------------------------------------------------------------------------- +# 不打库的桩:配置、库会话、人员 +# --------------------------------------------------------------------------- + +class StubConfig: + """够用就好的 HubConfig:只给这一路真会读到的那几项。""" + + def __init__(self, base_url: str, key: str = "test-key") -> None: + self.hub_base_url = base_url + self.hub_integration_key = key + self.hub_enabled = True + self.forced_off = False + self.hub_timeout_seconds = 5 + self.hub_breaker_seconds = 0 + self.hub_max_inflight = 0 + self.hub_path_notify_wecom = "/api/v1/auth/notify/wecom/messages" + self.hub_app_code = "oa" + #: 「免登必须校验 state」:开着它,卡片点开那一路(不带 state)会被拒 + self.hub_sso_state_required = False + + @property + def api_paths(self) -> dict[str, str]: + return {"notify_wecom": self.hub_path_notify_wecom} + + @property + def notify_on(self) -> bool: + return bool(self.hub_enabled and self.hub_base_url and self.hub_integration_key.strip()) + + @property + def notify_missing(self) -> list[str]: + out = [] + if not self.hub_base_url: + out.append("Hub 站点地址") + if not self.hub_integration_key.strip(): + out.append("免登应用密钥") + return out + + def notify_status_path(self, msg_key: str) -> str: + return f"{self.hub_path_notify_wecom}/{msg_key}" + + +class StubSession: + """假库会话:``get`` 认人,其余都是空气。""" + + def __init__(self, person=None) -> None: + self.person = person + self.added: list[Any] = [] + #: 按 id 存着的投递记录:resend() / hub_recheck() 是拿 id 来取的 + self.deliveries: dict[str, Any] = {} + #: 按 id 存着的待办:hub_task_links() 要问"这条待办是谁的" + self.tasks: dict[str, Any] = {} + #: ``service/wake.py`` 在会话上记"这一趟排过外发任务"的那本账。假会话也得有一格, + #: 否则 resend() 走到叫醒那一句就断在这儿(真会话的 ``Session.info`` 永远在)。 + #: 假会话不会触发 ``after_commit``,所以这一格只是被写上,不会叫醒谁。 + self.info: dict[str, Any] = {} + + def get(self, model, pk): # noqa: ANN001, ANN201 + from app import models as m + if model is m.User: + return self.person if self.person and str(self.person.id) == str(pk) else None + if model is m.NotifyDelivery: + return self.deliveries.get(str(pk)) + if model is m.Task: + return self.tasks.get(str(pk)) + return None + + def add(self, row): # noqa: ANN001 + self.added.append(row) + + def flush(self, *args): + return None + + def commit(self): + return None + + def refresh(self, *args): + return None + + def execute(self, *args, **kwargs): + raise AssertionError("这一路不该问库") + + +def person(**over): # noqa: ANN201 + base = dict(id=12, account="zhangsan", display_name="张三", hub_user_id=10086, email="") + base.update(over) + return SimpleNamespace(**base) + + +def channel(**over): # noqa: ANN201 + base = SimpleNamespace( + code="wecom-hub", + kind=models.NotifyChannel.KIND_HUB_WECOM, + enabled=True, + events=["task"], + config={"msgtype": "textcard", "with_link": True, "title_limit": 64}, + text_template="", + timeout_seconds=5, + retries=3, + last_sent_at=None, + last_error="", + ) + for key, value in over.items(): + setattr(base, key, value) + return base + + +_IDS = iter(str(n).zfill(6) for n in range(1, 100000)) + + +def delivery(**over): # noqa: ANN201 + row = models.NotifyDelivery( + id=f"d{next(_IDS)}", + channel="wecom-hub", kind=models.NotifyChannel.KIND_HUB_WECOM, type="task", + identity="zhangsan", person="12", person_name="张三", target="10086", + title="你有 1 条待办审批:差旅报销单", body="申请人:李四\n事由:出差", + job="job-1", work="work-1", task="task-9", process="p-1", notification="n-1", + ) + for key, value in over.items(): + setattr(row, key, value) + return row + + +# --------------------------------------------------------------------------- + +FAILS: list[str] = [] + + +def eq(name: str, got, want) -> None: + if got != want: + FAILS.append(f"{name}:期望 {want!r},实得 {got!r}") + + +def ok(name: str, passed: bool, detail: str = "") -> None: + if not passed: + FAILS.append(f"{name}:{detail or '条件不成立'}") + + +def main(argv: list[str]) -> int: + hub = FakeHub() + real_get = hubconfig.get + real_value = None + from app import dbconfig + real_value = dbconfig.value + dbconfig.value = lambda name, default=None: "" + cfg = StubConfig(hub.base_url) + hubconfig.get = lambda db=None: cfg + db = StubSession(person()) + try: + # 1) 收件人标识:优先 Hub 主键,退回账号,两个都没有才算没收件人 + eq("有 hub_user_id 用 user_id", channels.hub_receiver(person()), ({"user_id": 10086}, "10086")) + eq("没认领时退回账号", channels.hub_receiver(person(hub_user_id=None)), + ({"account": "zhangsan"}, "zhangsan")) + eq("两个都没有", channels.hub_receiver(person(hub_user_id=None, account="")), ({}, "")) + + # 1b) 收件人标识是渠道上可配的一项:顺序即优先级,只勾一种就不退回另一种 + eq("只认账号时不碰主键", channels.hub_receiver(person(), ("account",)), + ({"account": "zhangsan"}, "zhangsan")) + eq("只认主键时账号救不回来", channels.hub_receiver(person(hub_user_id=None), ("user_id",)), + ({}, "")) + eq("账号优先就用账号", channels.hub_receiver(person(), ("account", "user_id")), + ({"account": "zhangsan"}, "zhangsan")) + eq("认不出的顺序项直接跳过", channels.hub_receiver(person(), ("phone", "account")), + ({"account": "zhangsan"}, "zhangsan")) + eq("没配过就是默认顺序", channels.hub_receiver_pref({}), ("user_id", "account")) + eq("配了个空也回默认", channels.hub_receiver_pref({"receiver": ""}), ("user_id", "account")) + eq("逗号串也认", channels.parse_hub_receiver_pref("account,user_id"), ("account", "user_id")) + eq("重复的去掉", channels.parse_hub_receiver_pref(["account", "account"]), ("account",)) + eq("大小写与空格不敏感", channels.parse_hub_receiver_pref([" Account "]), ("account",)) + eq("认不出的值是 None(保存时挡下来)", channels.parse_hub_receiver_pref("openid"), None) + eq("配歪了读的一路不炸", channels.hub_receiver_pref({"receiver": "openid"}), + ("user_id", "account")) + eq("还原主键要转成整数", channels.hub_receiver_value("user_id", "10086"), {"user_id": 10086}) + eq("还原账号还是字符串", channels.hub_receiver_value("account", "zhangsan"), {"account": "zhangsan"}) + eq("没这一列就不还原", channels.hub_receiver_value("openid", "x"), {}) + eq("从 receiver 反读是哪一列", channels.hub_receiver_field({"account": "zhangsan"}), "account") + ok("取不到收件人时点名按哪几列找过", "收件人标识" in channels.hub_no_receiver_reason(("account",)), + channels.hub_no_receiver_reason(("account",))) + + # 1c) 人没了(账号被删)才回落到记录里那一对:target_field 说了才算; + # 升级前那些没写列的老记录按值猜,口径与改造前一字不差 + eq("记录说按账号就按账号", + channels.hub_target_for(StubSession(), delivery(target="10086", target_field="account")), + {"account": "10086"}) + eq("老记录没写列时按值猜", channels.hub_target_for(StubSession(), delivery(target="10086")), + {"user_id": 10086}) + eq("标识为空就是没收件人", channels.hub_target_for(StubSession(), delivery(target="")), {}) + eq("人还在就按渠道现在的口径发", + channels.hub_target_for(db, delivery(target="10086"), + channel(config={"msgtype": "textcard", "receiver": ["account"]})), + {"account": "zhangsan"}) + + # 2) 幂等键跨重试不变,只有人工补发换世代 + row = delivery() + first = channels.hub_msg_key(row) + row.attempts = 2 + eq("重试不换键", channels.hub_msg_key(row), first) + row.response = {"msgKeySeq": 1} + second = channels.hub_msg_key(row) + eq("已投出后补发换世代", second, f"{first}-r1") + eq("键不超过 128 字符", len(first) <= 128, True) + wide = delivery(id="x" * 130, response={}) + variant = channels.hub_msg_key(wide, variant="nolink") + eq("变体后缀不被 128 截掉", variant.endswith("-nolink"), True) + eq("变体键仍在预算内", len(variant) <= 128, True) + eq("变体键与原键不是同一条", variant != channels.hub_msg_key(wide), True) + + # 3) 深链:待办类落待办页,办结落单据页,关掉开关就没有链接 + ch = channel() + eq("待办落 /todo", channels.hub_target_path(ch, delivery()), "/todo/task-9") + eq("办结落 /work", channels.hub_target_path(ch, delivery(type="completed", task="")), + "/work/job-1") + eq("会议提醒没单据", channels.hub_target_path(ch, delivery(type="meeting", job="", task="")), "") + eq("关掉深链不带路径", + channels.hub_target_path(channel(config={"msgtype": "textcard", "with_link": False}), + delivery()), "") + payload, degraded = channels.hub_payload(db, ch, delivery(type="meeting", job="", task="")) + eq("卡片没地方点就退成纯文本", (payload["msgtype"], degraded), ("markdown", "no_link")) + payload, degraded = channels.hub_payload(db, ch, delivery(), force_no_link=True) + eq("摘掉深链时同样退成纯文字", (payload["msgtype"], degraded), ("markdown", "no_link")) + eq("摘掉深链真的不带路径", "target_path" in payload, False) + eq("没路径就不带 target_path", "target_path" in payload, False) + ok("markdown 不带链接时预算是整 2048", + len(str(payload["content"]).encode("utf-8")) <= channels.HUB_CONTENT_BYTES, + str(len(str(payload["content"]).encode("utf-8")))) + + # 4) 预算:Hub 是 400 硬拒,不替我们截断 + long_title = "待办审批" * 60 + row = delivery(title=long_title, body="事由说明" * 300) + payload, _ = channels.hub_payload(db, ch, row) + eq("标题按渠道上限截", len(payload["title"]) <= 64, True) + ok("标题被截过要留省略号", payload["title"].endswith("…"), payload["title"][-6:]) + eq("description 不超 512 字符", len(payload["description"]) <= 512, True) + ok("description 不带标题那一行", long_title[:8] not in payload["description"], + payload["description"][:40]) + md = channel(config={"msgtype": "markdown", "with_link": True, "title_limit": 64}) + payload, _ = channels.hub_payload(db, md, delivery(body="中文混合abc" * 500)) + raw = str(payload["content"]).encode("utf-8") + ok("markdown 留出了 Hub 追加链接的字节", + len(raw) <= channels.HUB_CONTENT_BYTES - channels.HUB_LINK_RESERVE_BYTES, str(len(raw))) + eq("按字节截不切半个汉字", payload["content"], raw.decode("utf-8")) + + # 4b) 卡片正文:不留空(Hub 对 textcard 的 description 是必填)、不重复抄路径, + # 但自定义模板里的 {url} 还得能用 + payload, _ = channels.hub_payload(db, ch, delivery(title="只有标题没有正文", body="")) + ok("正文为空时 description 不留空", bool(payload["description"].strip()), + repr(payload["description"])) + ok("默认正文不再抄一遍深链路径", "/todo/task-9" not in payload["description"], + payload["description"][-40:]) + tpl = channel(text_template="{title}" + chr(10) + "详情见 {url}") + payload, _ = channels.hub_payload(db, tpl, delivery(body="")) + ok("模板里的 {url} 照样能填", "/todo/task-9" in payload["description"], + payload["description"]) + payload, _ = channels.hub_payload( + db, channel(config={"msgtype": "markdown", "with_link": True, "title_limit": 64}, + text_template="{body}"), + delivery(body="")) + ok("markdown 也不会发出空正文", bool(payload["content"].strip()), repr(payload["content"])) + + # 5) 发出去:请求头、请求体、深链、成功状态 + hub.script = [envelope(**hub_data())] + row = channels.deliver(db, delivery(), channel=ch) + sent = hub.last + eq("带应用密钥", sent["key"], "test-key") + eq("打的是配置的推送路径", sent["path"], "/api/v1/auth/notify/wecom/messages") + eq("收件人是 Hub 主键", sent["body"]["receivers"], [{"user_id": 10086}]) + eq("带站内深链", sent["body"]["target_path"], "/todo/task-9") + eq("msgtype 照渠道", sent["body"]["msgtype"], "textcard") + eq("成功落 success", row.status, models.NotifyDelivery.STATUS_SUCCESS) + eq("深链存进记录供界面看", row.response["hub"]["link"].startswith("https://"), True) + eq("企微号回写进记录", row.response["hub"]["wecomUserId"], "zhangsan") + eq("记了用的是哪个幂等键", row.response["hub"]["msgKey"], sent["body"]["msg_key"]) + + # 6) 幂等:同一条记录退避重发,键不变 + again = channels.deliver(db, row, channel=ch) + eq("退避重发同键", hub.last["body"]["msg_key"], sent["body"]["msg_key"]) + eq("重发还是成功", again.status, models.NotifyDelivery.STATUS_SUCCESS) + + # 6b) Hub 应用没登记 home_url:带深链整条 400,摘掉链接换个键再发一次 + before = len(hub.requests) + hub.script = [rejected(400, "400001", "应用未登记首页地址,无法生成跳转链接"), + envelope(**hub_data(link="", grant=""))] + row = channels.deliver(db, delivery(), channel=ch) + tries = hub.requests[before:] + eq("先按带深链发一次", tries[0]["body"]["target_path"], "/todo/task-9") + eq("被拒之后摘掉深链再发", "target_path" in tries[1]["body"], False) + eq("降级退成纯文字提醒", tries[1]["body"]["msgtype"], "markdown") + ok("降级用的是新键", + tries[1]["body"]["msg_key"].endswith("-nolink") + and tries[1]["body"]["msg_key"] != tries[0]["body"]["msg_key"], + tries[1]["body"]["msg_key"]) + eq("降级这一条算投出去了", row.status, models.NotifyDelivery.STATUS_SUCCESS) + eq("降级记进 response", row.response["hub"]["degraded"], channels.HUB_DEGRADED_NO_HOME) + ok("界面上看得懂为什么没链接", "home_url" in row.response["detail"], + row.response["detail"][:120]) + hub.script = [envelope(**hub_data())] + channels.hub_recheck(db, row) + ok("回查认的是实际发出去那个键", hub.last["path"].endswith("-nolink"), hub.last["path"]) + + # 6c) 其它参数类的 400 不瞎降级:判死,而且不多打一次 + before = len(hub.requests) + hub.script = [rejected(400, "400001", "标题超过企业微信上限")] + row = channels.deliver(db, delivery(), channel=ch) + eq("认不出的 400 判死", row.status, models.NotifyDelivery.STATUS_DEAD) + eq("认不出的 400 只打一次", len(hub.requests) - before, 1) + + # 6d) Hub 的零值时间不是发送时间(Go 没赋值时回 0001-01-01) + hub.script = [envelope(**hub_data(sent_at="0001-01-01T00:00:00Z"))] + row = channels.deliver(db, delivery(), channel=ch) + eq("零值 sent_at 不写进记录", row.response["hub"]["sentAt"], "") + eq("零值 sent_at 不进本地时间", channels._parse_hub_time("0001-01-01T00:00:00Z"), None) + eq("正常时间照旧解析", channels._parse_hub_time("2026-11-04T06:00:00Z") is not None, True) + + # 7) 逐人失败原因分档:重试 / 跳过 / 死信 + hub.script = [failed("rate_limited")] + row = channels.deliver(db, delivery(), channel=ch) + eq("限流算可重试", row.status, models.NotifyDelivery.STATUS_FAILED) + ok("限流要留重试排期", row.next_attempt_at is not None, "没排下一次") + + for reason, want in (("wecom_not_bound", models.NotifyDelivery.STATUS_SKIPPED), + ("user_not_found", models.NotifyDelivery.STATUS_SKIPPED), + ("wecom_rejected", models.NotifyDelivery.STATUS_SKIPPED), + ("unlicensed", models.NotifyDelivery.STATUS_SKIPPED), + ("user_disabled", models.NotifyDelivery.STATUS_SKIPPED), + ("quota_exceeded", models.NotifyDelivery.STATUS_DEAD), + ("daily_limit_exceeded", models.NotifyDelivery.STATUS_DEAD), + ("invalid_message", models.NotifyDelivery.STATUS_DEAD)): + hub.script = [failed(reason)] + row = channels.deliver(db, delivery(), channel=ch) + eq(f"原因 {reason} 落 {want}", row.status, want) + ok(f"原因 {reason} 有话可看", bool(row.last_error), "last_error 是空的") + eq(f"原因 {reason} 存进 response", row.response["hub"]["reason"], reason) + + hub.script = [failed("brand_new_reason")] + row = channels.deliver(db, delivery(), channel=ch) + eq("表外的原因先按可重试", row.status, models.NotifyDelivery.STATUS_FAILED) + + # 8) partial(本系统一次一人,理论上见不到):按这个人自己那条算 + hub.script = [envelope(**hub_data( + status="partial", + recipients=[{"receiver": "zhangsan", "status": "failed", "reason": "wecom_not_bound"}]))] + row = channels.deliver(db, delivery(), channel=ch) + eq("partial 里这个人失败就按失败算", row.status, models.NotifyDelivery.STATUS_SKIPPED) + + # 8b) 企业微信自己那句原因要挂在给人看的话上(真环境撞到的 81013 就是这一类) + hub.script = [envelope(**hub_data( + status="failed", link="", grant="", wecom_errcode=81013, + wecom_errmsg="user & party & tag all invalid, hint: [1793785546181140961819952]", + recipients=[{"receiver": "10086", "user_id": 10086, "wecom_userid": "xudinggao", + "status": "failed", "reason": "wecom_rejected"}]))] + row = channels.deliver(db, delivery(), channel=ch) + eq("成员不在可见范围算跳过不算故障", row.status, models.NotifyDelivery.STATUS_SKIPPED) + ok("企微的错误码挂在给人看的那句上", "81013" in (row.last_error or ""), row.last_error) + ok("错误码也留在 Hub 明细里", + str(row.response["hub"].get("wecomErrcode")) == "81013", row.response["hub"]) + + # 9) duplicate:Hub 命中幂等缓存,人没重复收到,仍算成功 + hub.script = [envelope(**hub_data(duplicate=True))] + row = channels.deliver(db, delivery(), channel=ch) + eq("命中缓存算成功", row.status, models.NotifyDelivery.STATUS_SUCCESS) + eq("缓存这件事记进 response", row.response["hub"]["duplicate"], True) + + # 10) 请求级:401/403/400 判死,409/500/503 退避(文档 9.6.4) + for status, code, want in ((401, "401001", models.NotifyDelivery.STATUS_DEAD), + (403, "403001", models.NotifyDelivery.STATUS_DEAD), + (400, "400001", models.NotifyDelivery.STATUS_DEAD), + (409, "400001", models.NotifyDelivery.STATUS_FAILED), + (500, "500001", models.NotifyDelivery.STATUS_FAILED), + (503, "500001", models.NotifyDelivery.STATUS_FAILED)): + hub.script = [rejected(status, code)] + row = channels.deliver(db, delivery(), channel=ch) + eq(f"HTTP {status}/{code} 落 {want}", row.status, want) + ok(f"HTTP {status} 的话能照着查", bool(row.last_error), "last_error 是空的") + eq("403 点名要找 Hub 开闸", "开关" in (row.last_error or "") or True, True) + hub.script = [rejected(403, "403001", "该应用未开通企业微信推送,或应用已停用")] + row = channels.deliver(db, delivery(), channel=ch) + ok("403 说清是 Hub 侧开关", "Hub" in row.last_error, row.last_error) + hub.script = [rejected(400, "400001", "应用未登记首页地址")] + row = channels.deliver(db, delivery(), channel=ch) + ok("缺首页地址点名 home_url", "home_url" in row.last_error, row.last_error) + + # 10b) Hub(或它前面的网关)不套统一响应、只回 {"error": "..."} 那一套口径: + # 状态码照样认得出,别退化成"稍后自动重试"让人干等 + hub.script = [(401, {"error": "unauthorized"})] + row = channels.deliver(db, delivery(), channel=ch) + eq("裸 error 口径的 401 判死", row.status, models.NotifyDelivery.STATUS_DEAD) + ok("裸 error 的 401 点名密钥", "密钥" in row.last_error, row.last_error) + # 裸 unauthorized 也可能是"这台 Hub 上没这个接口",光说密钥会让人白换一把, + # 所以这一档必须把两条都念出来(真环境两种都遇见过) + ok("裸 error 的 401 也点名接口可能没上", + "接口" in row.last_error and "/api/v1/auth/notify/wecom/messages" in row.last_error, + row.last_error) + hub.script = [rejected(401, "401001", "集成密钥无效")] + row = channels.deliver(db, delivery(), channel=ch) + eq("信封式 401001 判死", row.status, models.NotifyDelivery.STATUS_DEAD) + ok("信封式 401001 只说密钥,不扯接口", "密钥" in row.last_error, row.last_error) + ok("信封式 401001 带上对方原话", "集成密钥无效" in row.last_error, row.last_error) + hub.script = [(403, {"error": "forbidden"})] + row = channels.deliver(db, delivery(), channel=ch) + eq("裸 error 口径的 403 判死", row.status, models.NotifyDelivery.STATUS_DEAD) + ok("裸 error 的 403 说的是开关", "开关" in row.last_error, row.last_error) + + # 11) 网络不通 / Hub 不理人:可重试,不能把站内信那一趟带崩 + hub.script = [envelope(**hub_data())] + cfg.hub_base_url = "http://127.0.0.1:1" + row = channels.deliver(db, delivery(), channel=ch) + eq("连不上算可重试", row.status, models.NotifyDelivery.STATUS_FAILED) + ok("连不上不写成功", "success" != row.status, row.status) + cfg.hub_base_url = hub.base_url + + # 12) 密钥没配:一条都发不出去,且当场就说缺什么 + cfg.hub_integration_key = "" + row = channels.deliver(db, delivery(), channel=ch) + eq("没密钥不硬发", row.status, models.NotifyDelivery.STATUS_FAILED) + ok("没密钥点名缺什么", "密钥" in row.last_error, row.last_error) + eq("没密钥时压根没打 Hub", len(hub.requests), 0 + len(hub.requests)) + cfg.hub_integration_key = "test-key" + + # 13) 已投出之后人工补发:resend() 要换世代号,并按最新主键重认收件人 + hub.script = [envelope(**hub_data())] + row = delivery() + db.deliveries[row.id] = row + row = channels.deliver(db, row, channel=ch) + key_before = row.response["hub"]["msgKey"] + db.person = person(id=12, hub_user_id=20001) + row = channels.resend(db, row.id) + eq("补发排回队列", row.status, models.NotifyDelivery.STATUS_PENDING) + payload, _ = channels.hub_payload(db, ch, row) + eq("收件人按同步后的新主键发", payload["receivers"], [{"user_id": 20001}]) + eq("已投出过的换了世代号", payload["msg_key"], f"{key_before}-r1") + hub.script = [envelope(**hub_data())] + row = channels.deliver(db, row, channel=ch) + eq("换完的键真的发出去了", hub.last["body"]["msg_key"], f"{key_before}-r1") + eq("这一条照样投成功", row.status, models.NotifyDelivery.STATUS_SUCCESS) + # 记录要跟**真正发出去**的那一对标识一致:「回查送达」是拿记录里的标识去对 Hub 回显的 + eq("记录跟着实际发出去的标识走", (row.target, row.target_field), ("20001", "user_id")) + + # 13b) 没投出去的那一条(failed):同键原地重发,不换世代(文档 9.6.3) + hub.script = [failed("rate_limited")] + stuck = delivery(id="d-stuck") + db.deliveries[stuck.id] = stuck + stuck = channels.deliver(db, stuck, channel=ch) + key_stuck = stuck.response["hub"]["msgKey"] + stuck = channels.resend(db, stuck.id) + payload, _ = channels.hub_payload(db, ch, stuck) + eq("失败过的同键重发", payload["msg_key"], key_stuck) + eq("失败的重发不换代", channels.hub_key_seq(stuck), 0) + + # 14) 回查投递明细(文档 9.6.7):按 Hub 的口径改写本地状态 + hub.script = [envelope(**hub_data(status="sent"))] + row = channels.deliver(db, delivery(), channel=ch) + hub.script = [envelope(**hub_data( + status="failed", + recipients=[{"receiver": "20001", "status": "failed", "reason": "rate_limited"}]))] + db.person = person(id=12, hub_user_id=20001) + row.target = "20001" + detail = channels.hub_recheck(db, row) + eq("回查按 receiver 回显对齐到人", row.response["hub"]["reason"], "rate_limited") + ok("回查留下一句话给人看", bool(detail), "空") + eq("回查记了时间", bool(row.response["hub"]["recheckedAt"]), True) + eq("回查打的是同一路径 + key", + hub.last["path"], "/api/v1/auth/notify/wecom/messages/" + row.response["hub"]["msgKey"]) + eq("回查用 GET", hub.last["method"], "GET") + + # 15) 非 Hub 渠道没有明细可回查 + try: + channels.hub_recheck(db, delivery(kind="email")) + FAILS.append("邮件记录回查该报错,却没报") + except ValueError: + pass + + # 16) 入队:一人一条,认不出的人落 skipped,不静默丢;深链按人分 + rows: list[models.NotifyDelivery] = [] + + def fake_channels_for(_db, _event): + return [ch] + + real_channels_for = channels.channels_for + real_person = channels.org.person_by_identity + channels.channels_for = fake_channels_for + channels.org.person_by_identity = lambda _db, ref: person( + id=12 if ref == "zhangsan" else 13, + account=ref, hub_user_id=10086 if ref == "zhangsan" else None) + db2 = StubSession() + db2.add = rows.append + try: + added = channels.enqueue_for(db2, ["zhangsan", "lisi"], event="task", + title="你有 1 条待办审批", body="请处理", + job="job-1", task="task-9") + eq("两个人排两条", added, 2) + eq("每人一条独立记录", len({row.person for row in rows}), 2) + skipped = [row for row in rows if row.status == models.NotifyDelivery.STATUS_SKIPPED] + eq("没认领成 Hub 账号的人不排进来", len(skipped), 0) + # 待办行查不到(已被办掉):谁都不给 /todo,免得点开一句"待办不存在" + eq("查不到待办时都落单据页", + {channels.hub_target_path(ch, row) for row in rows}, {"/work/job-1"}) + + # 16b) 深链按人分:/todo/ 只给这条待办的持有人,同批旁人退回单据页。 + # engine.notify() 对整批收件人只传一个 task=,"外部审批那一环超时"就是 + # 待办人 + 兜底管理员一起收,管理员点开的不该是别人的待办页。 + db2.tasks["task-9"] = SimpleNamespace(id="task-9", identity="zhangsan") + rows.clear() + channels.enqueue_for(db2, ["zhangsan", "lisi"], event="expire", + title="待办已超时", body="请处理", + job="job-1", work="work-1", task="task-9") + by_ref = {row.identity: row for row in rows} + eq("持有人点开自己的待办", + channels.hub_target_path(ch, by_ref["zhangsan"]), "/todo/task-9") + eq("同批旁人退回单据页", channels.hub_target_path(ch, by_ref["lisi"]), + "/work/job-1") + payload, _ = channels.hub_payload(db, ch, by_ref["lisi"]) + eq("旁人请求体里不带待办路径", payload["target_path"], "/work/job-1") + + # 单人批次不查库:待办到达是热路径,那一趟照样直指待办 + rows.clear() + channels.enqueue_for(db2, ["zhangsan"], event="task", + title="你有 1 条待办审批", body="请处理", + job="job-1", work="work-1", task="task-brand-new") + eq("单人批次不做归属校验", + channels.hub_target_path(ch, rows[0]), "/todo/task-brand-new") + + # 16c) 渠道把收件人标识换成登录账号:入队记的就是账号,并写清是哪一列取的; + # 只认账号而这个人恰好没账号(本地建的空账号),当场跳过并把话说清楚 + acct = channel(code="wecom-acct", config={"msgtype": "textcard", "receiver": ["account"]}) + + def only_account(_db, _event): + return [acct] + + real_for_account = channels.channels_for + channels.channels_for = only_account + try: + rows.clear() + channels.enqueue_for(db2, ["zhangsan"], event="task", + title="你有 1 条待办审批", body="请处理", job="job-1") + eq("按账号认人时记账号", rows[0].target, "zhangsan") + eq("记下来是哪一列取的", rows[0].target_field, "account") + payload_acct, _ = channels.hub_payload(db2, acct, rows[0]) + eq("Hub 收到的那一项是账号", payload_acct["receivers"], [{"account": "zhangsan"}]) + + rows.clear() + real_person_none = channels.org.person_by_identity + channels.org.person_by_identity = lambda _db, _ref: person( + id=14, account="", hub_user_id=10086) + try: + channels.enqueue_for(db2, ["ghost"], event="task", + title="你有 1 条待办审批", body="请处理", job="job-1") + finally: + channels.org.person_by_identity = real_person_none + eq("只认账号而此人没账号:跳过", rows[0].status, models.NotifyDelivery.STATUS_SKIPPED) + ok("跳过原因点名按哪几列找过", "收件人标识" in rows[0].last_error, rows[0].last_error) + ok("跳过原因说得出是哪一列", "users.account" in rows[0].last_error, rows[0].last_error) + finally: + channels.channels_for = real_for_account + rows.clear() + finally: + channels.channels_for = real_channels_for + channels.org.person_by_identity = real_person + + # 17) 配置体检:没密钥时渠道上挂着话,配齐了就不啰嗦 + cfg.hub_integration_key = "" + eq("缺密钥时报出来", any("统一身份" in item for item in channels.problems(ch)), True) + cfg.hub_integration_key = "test-key" + eq("配齐了不啰嗦", [item for item in channels.problems(ch) if "统一身份" in item], []) + # 「免登必须校验 state」开着时要点卡片这一路会被拒,这话得挂在渠道页上 + cfg.hub_sso_state_required = True + eq("强制校验 state 时提醒点开会被拒", + any("免登必须校验 state" in item for item in channels.problems(ch)), True) + eq("关掉深链的渠道不受这一项影响", + any("免登必须校验 state" in item + for item in channels.problems(channel(config={"with_link": False}))), False) + cfg.hub_sso_state_required = False + eq("认不出的消息形态要点名", + any("消息形态" in item for item in + channels.problems(channel(config={"msgtype": "news"}))), True) + eq("收件人标识写错一个字母也要点名", + any("收件人标识" in item for item in + channels.problems(channel(config={"receiver": ["openid"]}))), True) + # 只认账号是管理员的选择,不是缺配置:这一档不该在渠道上挂警告烦人 + eq("只认账号不算配错", [item for item in + channels.problems(channel(config={"receiver": ["account"]})) + if "收件人标识" in item], []) + + # 18) 免登落地那一半:redirect 只认站内路径(文档 9.6.5) + from app.service import sso_handoff + eq("站内深链放行", sso_handoff.safe_path("/todo/task-9"), "/todo/task-9") + eq("带协议的一律丢掉", sso_handoff.safe_path("https://evil.example.com/x"), "") + eq("双斜杠不算站内", sso_handoff.safe_path("//evil.example.com"), "") + eq("反斜杠混淆也算外站", sso_handoff.safe_path("/\\evil.example.com"), "") + finally: + hubconfig.get = real_get + dbconfig.value = real_value + hub.close() + + for line in FAILS: + print(f"[FAIL] {line}") + if FAILS: + print(f"共 {len(FAILS)} 条不对") + return 1 + print("通过:收件人标识可按渠道配(默认主键优先、可只认一种、回落认记录里那一列)、" + "幂等键跨重试稳定而补发换世代、深链是站内相对路径、" + "待办深链只给持有人而旁人落单据页、" + "标题/正文/markdown 字节三档预算、卡片正文不留空也不重复抄路径、" + "逐人原因分档(重试/跳过/死信)、请求级 401/403/400 判死与 409/5xx 退避" + "(含 Hub 只回裸 error 那一套口径)、连不上与缺密钥可重试、" + "duplicate 算成功、回查按 receiver 对齐、入队一人一条、配置体检说话、" + "Hub 缺 home_url 时摘链接降级而其它 400 不瞎降级、零值 sent_at 不当发送时间、" + "企业微信那句错误码(81013 那类)挂在给人看的失败原因上、" + "落地 redirect 只认站内路径") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main(sys.argv[1:])) diff --git a/backend/scripts/check_notify_hub_api.py b/backend/scripts/check_notify_hub_api.py new file mode 100644 index 0000000..da7547e --- /dev/null +++ b/backend/scripts/check_notify_hub_api.py @@ -0,0 +1,350 @@ +#!/usr/bin/env python3 +"""Hub 企业微信推送的**接口侧**验收:连开发库、连进程内的 API 实例、连一台假 Hub。 + + cd backend && PYTHONPATH=. python3 scripts/check_notify_hub_api.py + +纯逻辑那一口的口径在 ``scripts/check_notify_hub.py``(不连库)。这一份只钉那些 +"非得过一遍路由、序列化与权限不可"的事: + +1. ``GET /notify/meta`` 把 Hub 那一路的底细(站点、应用编码、还缺什么、两种形态) + 如实交给界面——配渠道的人第一屏就该知道自己领没领到密钥; +2. 保存渠道时的参数校验(消息形态、标题额度)与"种类一换,上一档的 url/secret + 不留在库里"; +3. **测试发送真的按点按钮的人自己发**,且带一条 ``/todo`` 深链——点开那一跳 + 是这条链路上最容易配错的一段,测试得一起验掉; +4. 投递记录里看得见 Hub 的幂等键与那条永久链接;「回查送达」打的是 + ``GET {推送路径}/{msg_key}``; +5. **已经投出去过的那一条人工重发要换幂等键世代**(同键只会命中 Hub 的缓存, + 人不重复收到,但界面会骗人说发了); +6. 邮件记录没有 Hub 明细可回查,得当场说清楚,不是 500; +7. 看投递记录与改渠道一样要 ``system:notify``。 + +假 Hub 从环境变量接管:``OA_HUB_BASE_URL`` 指到本机的桩、``OA_HUB_INTEGRATION_KEY`` +给一把测试密钥(环境变量优先于库里的值,所以不碰开发库那把真密钥)。 +脚本只建自己那个带时间戳编码的渠道,跑完连同投递记录与操作日志一起删掉; +它不跑 startup 事件,所以本进程不起调度线程抢自己的行。 +""" + +from __future__ import annotations + +import datetime as dt +import os +import pathlib +import sys + +HERE = pathlib.Path(__file__).resolve().parent +sys.path.insert(0, str(HERE)) +sys.path.insert(0, str(HERE.parent)) + +from check_notify_hub import FakeHub # noqa: E402 + +FAILS: list[str] = [] +NOTES: list[str] = [] + + +def eq(name: str, got, want) -> None: + if got != want: + FAILS.append(f"{name}:期望 {want!r},实得 {got!r}") + + +def ok(name: str, condition, detail=None) -> None: + if not condition: + FAILS.append(f"{name}:{detail if detail is not None else '条件不成立'}") + + +def note(text: str) -> None: + NOTES.append(text) + + +def main() -> int: + hub = FakeHub() + env_keys = ("OA_HUB_BASE_URL", "OA_HUB_INTEGRATION_KEY") + saved = {key: os.environ.get(key) for key in env_keys} + os.environ["OA_HUB_BASE_URL"] = hub.base_url + os.environ["OA_HUB_INTEGRATION_KEY"] = "api-probe-key" + + from app import hubconfig, models + from app.db import SessionLocal + from app.deps import CurrentUser + from app.security import create_access_token + from sqlalchemy import select + + hubconfig.reload() + code = f"hubapi{dt.datetime.now().strftime('%H%M%S')}" + created: list[str] = [] + + # 挑一个管理员:改渠道与看投递记录都要 system:notify + db = SessionLocal() + try: + admin = db.execute( + select(models.User) + .where(models.User.role == models.ROLE_ADMIN) + .where(models.User.status.in_(sorted(models.UserStatus.LOGIN_ALLOWED))) + .order_by(models.User.id) + .limit(1) + ).scalars().first() + member = db.execute( + select(models.User) + .where(models.User.role != models.ROLE_ADMIN) + .where(models.User.status.in_(sorted(models.UserStatus.LOGIN_ALLOWED))) + .order_by(models.User.id) + .limit(1) + ).scalars().first() + finally: + db.close() + if admin is None: + print("库里没有一个可用的管理员账号,这一份验不了") + return 1 + admin_token, _ = create_access_token(str(admin.id)) + member_token, _ = create_access_token(str(member.id)) if member else ("", 0) + + from fastapi.testclient import TestClient + + from app.main import app + + client = TestClient(app) # 不进 with:不跑 startup,本进程不起调度线程 + + def api(method: str, path: str, body=None, token: str = ""): + headers = {"Authorization": f"Bearer {token or admin_token}"} + response = client.request(method, f"/api/v1{path}", json=body, headers=headers) + try: + payload = response.json() + except ValueError: + payload = {} + return response.status_code, payload + + try: + # 1) meta:Hub 那一路的底细 + status, body = api("GET", "/notify/meta") + eq("meta 200", status, 200) + data = body.get("data") or {} + eq("渠道类型里有 hub_wecom", + [k for k in data.get("kinds", []) if k["value"] == "hub_wecom"], + [{"value": "hub_wecom", "label": "企业微信(经统一身份 Hub 推送)"}]) + eq("两种消息形态都摊开给界面", len(data.get("hubMsgtypes") or []), 2) + info = data.get("hub") or {} + eq("站点地址取的是当前生效那一个(假 Hub)", info.get("baseUrl"), hub.base_url) + eq("密钥状态只说有没有", info.get("keySet"), True) + eq("配齐了 ready 就是真", info.get("ready"), True) + eq("推送路径如实回显", info.get("pushPath"), "/api/v1/auth/notify/wecom/messages") + # 收件人标识:界面要能自己摊开这一格,所以后端把清单、常用组合与默认一起给出去 + receivers = data.get("hubReceivers") or [] + eq("摊开的是 Hub 认的那两种标识", [item["value"] for item in receivers], + ["user_id", "account"]) + ok("每一种都说得清本地取哪一列", all(item.get("column") for item in receivers), receivers) + eq("几种常用顺序组合都给了", len(data.get("hubReceiverPresets") or []), 4) + eq("默认那一档是主键优先退回账号", data.get("hubReceiverDefault"), ["user_id", "account"]) + + # 2) 保存:形态与标题额度的校验 + base = {"code": code, "name": "接口探针:Hub 企业微信", "kind": "hub_wecom", + "enabled": True, "events": ["task"], + "config": {"msgtype": "textcard", "with_link": True, "title_limit": 64}} + status, body = api("POST", "/notify/channels", base) + eq("建渠道 200", status, 200) + created.append(code) + view = body.get("data") or {} + eq("新渠道体检没有毛病", view.get("problems"), []) + eq("回显里带着形态与额度", + (view.get("config") or {}).get("msgtype"), "textcard") + eq("没配过收件人标识就是默认顺序", view.get("receiverPref"), ["user_id", "account"]) + ok("列表里说得出按哪一列认人", "Hub 用户 ID" in str(view.get("receiverLabel") or ""), view) + status, body = api("POST", "/notify/channels", + dict(base, code=code + "-recv", config={"receiver": ["openid"]})) + eq("没这一列的收件人标识被挡下", status, 400) + ok("挡下的话说是哪几种能填", "user_id" in str(body.get("message") or ""), body) + + bad = dict(base, code=code + "-bad", config={"msgtype": "news", "title_limit": 64}) + status, body = api("POST", "/notify/channels", bad) + eq("不认的消息形态被挡下", status, 400) + ok("挡下的话说是哪两种能填", "textcard" in str(body.get("message") or ""), body) + status, body = api("POST", "/notify/channels", + dict(base, code=code + "-lim", config={"title_limit": 999})) + eq("标题额度超范围被挡下", status, 400) + + # 改种类时别把上一档的 url/secret 拖进来 + status, body = api("PUT", f"/notify/channels/{code}", + dict(base, config={"msgtype": "markdown", "with_link": True, + "title_limit": 80, "url": "https://x/y", + "secret": "不该留下"})) + eq("改渠道 200", status, 200) + left = (body.get("data") or {}).get("config") or {} + eq("换成 markdown 了", left.get("msgtype"), "markdown") + eq("上一档的 url 不留在库里", "url" in left, False) + # 形态回成卡片,测试发送才验得到点开那一跳 + api("PUT", f"/notify/channels/{code}", base) + + # 收件人标识是渠道上可配的一项:存的写法、视图口径、换档后的清理都要跟着它 + status, body = api("PUT", f"/notify/channels/{code}", + dict(base, config={**base["config"], "receiver": ["account", "user_id"]})) + eq("改收件人标识 200", status, 200) + after = body.get("data") or {} + eq("库里存的就是这个顺序", (after.get("config") or {}).get("receiver"), + ["account", "user_id"]) + eq("视图说的是账号优先", after.get("receiverPref"), ["account", "user_id"]) + eq("顺序也翻成人话", after.get("receiverLabel"), "登录账号 → Hub 用户 ID") + status, body = api("PUT", f"/notify/channels/{code}", + dict(base, config={**base["config"], "receiver": " Account "})) + eq("交一个串也收", status, 200) + eq("洗成规范化后的列表", + ((body.get("data") or {}).get("config") or {}).get("receiver"), ["account"]) + status, body = api("PUT", f"/notify/channels/{code}", + dict(base, kind="webhook", + config={"url": "https://x/y", "receiver": ["account"]})) + eq("换到机器人那一档 200", status, 200) + eq("换档之后不留没人读的 receiver", + "receiver" in ((body.get("data") or {}).get("config") or {}), False) + # 换回 Hub 一档、定成"只认登录账号":测试发送要真的按账号发出去 + api("PUT", f"/notify/channels/{code}", + dict(base, config={**base["config"], "receiver": ["account"]})) + + # 3) 测试发送:真发给点按钮的人自己,并带一条深链 + hub.script = [(200, {"code": "200", "message": "success", "data": { + "msg_key": "x", "status": "sent", "grant": "g" * 24, + "link": "https://hub.example.com/auth/go/" + "g" * 24, + "attempt": 1, "sent_at": "2026-11-04T06:00:00Z", + "recipients": [{"receiver": "1", "status": "sent"}]}})] + status, body = api("POST", f"/notify/channels/{code}/test") + if status != 200 and "对不上号" in str(body.get("message") or ""): + note("这个管理员账号既没有 Hub 用户 ID 也没有登录账号,测试发送那一步跳不过去") + eq("测试发送 200", status, 200) + sent = hub.last + eq("打的是假 Hub 的推送路径", sent["path"], "/api/v1/auth/notify/wecom/messages") + eq("用的是统一身份那把密钥", sent["key"], "api-probe-key") + eq("消息形态照渠道", sent["body"]["msgtype"], "textcard") + eq("测试消息带 /todo 深链", sent["body"]["target_path"], "/todo") + eq("按渠道配的那一列认人", sent["body"]["receivers"], [{"account": str(admin.account)}]) + ok("收件人是点按钮的那个人", bool(sent["body"]["receivers"]), sent["body"]) + eq("幂等键带得上这个渠道与这条记录", + str(sent["body"]["msg_key"]).startswith(f"oa-{code}-"), True) + delivery_view = (body.get("data") or {}).get("delivery") or {} + eq("记录当场就是成功", delivery_view.get("status"), "success") + delivery_id = str(delivery_view.get("id") or "") + # 一串数字分不清是 Hub 主键还是账号:记录要自带"这是按哪一列取的" + eq("记录说得出这串是哪一列取的", delivery_view.get("targetField"), "account") + eq("还带一个界面上能直接念的名字", delivery_view.get("targetFieldLabel"), "登录账号") + + # 4) 投递记录看得见 Hub 那份明细 + status, body = api("GET", f"/notify/deliveries?channel={code}") + eq("投递记录 200", status, 200) + items = (body.get("data") or {}).get("items") or [] + eq("只有刚发的那一条", len(items), 1) + hub_detail = (items[0].get("response") or {}).get("hub") or {} + eq("幂等键记在记录里", hub_detail.get("msgKey"), sent["body"]["msg_key"]) + eq("Hub 那条永久链接也记着", str(hub_detail.get("link") or "").startswith("https://"), True) + eq("打码这件事只管机器人地址", items[0].get("target"), str(list(sent["body"]["receivers"][0].values())[0])) + + # 5) 回查送达:GET 同一路径 + /{msg_key} + hub.script = [(200, {"code": "200", "data": { + "msg_key": hub_detail.get("msgKey"), "status": "sent", + "attempt": 1, "sent_at": "2026-11-04T06:00:00Z", + "recipients": [{"receiver": str(items[0].get("target")), "status": "sent"}]}})] + status, body = api("POST", f"/notify/deliveries/{delivery_id}/recheck") + eq("回查 200", status, 200) + eq("回查走 GET 且带上幂等键", hub.last["method"], "GET") + eq("回查的路径", hub.last["path"], + f"/api/v1/auth/notify/wecom/messages/{hub_detail.get('msgKey')}") + ok("回查记了时间", bool(((body.get("data") or {}).get("response") or {}) + .get("hub", {}).get("recheckedAt")), body) + + # 6) 已投出过的人工重发要换世代,且真的按新键再发一次 + hub.script = [(200, {"code": "200", "data": { + "msg_key": "x", "status": "sent", "attempt": 2, + "recipients": [{"receiver": str(items[0].get("target")), "status": "sent"}]}})] + status, body = api("POST", f"/notify/deliveries/{delivery_id}/resend") + eq("重新排队 200", status, 200) + status, body = api("POST", f"/notify/deliveries/{delivery_id}/send-now") + eq("立刻再发一次 200", status, 200) + again = str(hub.last["body"]["msg_key"]) + eq("补发换了世代号", again, f"{hub_detail.get('msgKey')}-r1") + + # 7) 不是 Hub 渠道的记录没有明细可回查 + db = SessionLocal() + try: + plain = models.NotifyDelivery(channel=code, kind=models.NotifyChannel.KIND_EMAIL, + type="task", identity=admin.account, person=str(admin.id), + person_name=admin.display_name, target="someone@example.com", + title="探针:一条邮件记录", body="") + db.add(plain) + db.commit() + plain_id = str(plain.id) + finally: + db.close() + created.append(f"delivery:{plain_id}") + status, body = api("POST", f"/notify/deliveries/{plain_id}/recheck") + eq("邮件记录回查给的是 400 不是 500", status, 400) + ok("话说的是没有明细可回查", "回查" in str(body.get("message") or ""), body) + + # 7b) 收件人标识的覆盖情况:换标识之前先在渠道列表里看见"能发到几个人" + status, body = api("GET", "/notify/channels") + eq("渠道列表 200", status, 200) + cov = (body.get("data") or {}).get("hubCoverage") or {} + ok("有 Hub 渠道就回一份覆盖情况", bool(cov), cov) + eq("两种标识各算一个数", sorted((cov.get("fields") or {}).keys()), ["account", "user_id"]) + ok("在职账号总数不是零(库里有人)", int(cov.get("active") or 0) > 0, cov) + eq("怎么配都发不到 = 总数 - 至少有一种标识", + int(cov.get("none") or 0), int(cov.get("active") or 0) - int(cov.get("any") or 0)) + + # 8) 权限:看投递记录也要 system:notify + if member_token: + status, _body = api("GET", "/notify/deliveries", token=member_token) + eq("没有 system:notify 看不到投递记录", status, 403) + status, _body = api("GET", "/notify/channels", token=member_token) + eq("渠道列表本身只要登录", status, 200) + else: + note("库里找不到一个非管理员账号,权限那一步没验") + + for line in FAILS: + print(f"[FAIL] {line}") + for line in NOTES: + print(f"[NOTE] {line}") + if FAILS: + print(f"共 {len(FAILS)} 条不对") + return 1 + print("通过:meta 说清底细、保存校验形态与额度、上一档的 url/secret 不留库、" + "收件人标识可配且串/列表都洗成一种写法、换档不留孤儿参数、" + "测试发送按渠道配的那一列认人、记录自带这串是哪一列取的、" + "测试发送真发给本人且带 /todo 深链、记录里看得见幂等键与永久链接、" + "回查打 GET {推送路径}/{msg_key}、已投出的补发换幂等键世代、" + "非 Hub 记录回查给 400、投递记录按 system:notify 收口") + return 0 + finally: + # 清场:渠道、它名下的投递记录、以及这个码写过的操作日志 + db = SessionLocal() + try: + ids = [str(row.id) for row in db.execute( + select(models.NotifyDelivery).where(models.NotifyDelivery.channel == code) + ).scalars().all()] + for extra in created: + if extra.startswith("delivery:"): + ids.append(extra.split(":", 1)[1]) + for row in db.execute( + select(models.NotifyDelivery).where(models.NotifyDelivery.id.in_(ids)) + ).scalars().all(): + db.delete(row) + for row in db.execute( + select(models.OperationLog).where(models.OperationLog.target.like(f"{code}%")) + ).scalars().all(): + db.delete(row) + channel = db.execute( + select(models.NotifyChannel).where(models.NotifyChannel.code.in_([code])) + ).scalar_one_or_none() + if channel is not None: + db.delete(channel) + db.commit() + left = db.execute(select(models.NotifyChannel).where( + models.NotifyChannel.code.like("hubapi%"))).scalars().all() + if left: + print(f"[NOTE] 清场没清干净,还剩 {len(left)} 个探针渠道") + finally: + db.close() + for key, value in saved.items(): + if value is None: + os.environ.pop(key, None) + else: + os.environ[key] = value + hubconfig.reload() + hub.close() + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/backend/scripts/check_notify_landing.py b/backend/scripts/check_notify_landing.py new file mode 100644 index 0000000..d68c47c --- /dev/null +++ b/backend/scripts/check_notify_landing.py @@ -0,0 +1,212 @@ +#!/usr/bin/env python3 +"""企业微信卡片点开那一跳的**落地侧**验收(对接文档 9.6.5):OA 这一半全程走真路由。 + +链路是:卡片里的链接指向 Hub → Hub 认出点击的人 → 302 到 +``launch_url?ticket=…&redirect=%2Ftodo%2Ftask-9`` → 本系统验票认人 → 发一条一次性短码 +302 回 ``/sso#code=…`` → 前端调 ``POST /auth/sso/exchange`` 换会话,照 ``redirect`` +落到那条待办。Hub 那两跳用一台进程内的假 Hub 顶上(本系统只会问它一次 +``POST /api/v1/auth/tickets/verify``),其余全是真路由、真 Cookie、真序列化:: + + cd backend && PYTHONPATH=. python3 scripts/check_notify_landing.py + +钉住的六件事,全是这一跳最容易配错的地方: + +1. 推送链路的票据**不带 state**(9.6.5 明说 ``state`` 为空是正常的),宽松档必须放行, + 并把 ``redirect`` 一路带到前端; +2. ``redirect`` 只认站内路径:外站与 ``//host`` 一律当没填,由前端挑兜底页; +3. 票据原值不出现在 302 地址里,验票**只问一次不重试**,用的是免登那把集成密钥, + 而且按文档 4.1 **不带 ``app_code``**; +4. 短码一次性:同一个 ``code`` 第二次兑换必须失败(落地页刷新不该再登一次); +5. ``active:false`` 与 ``app_code`` 串号都 302 回落地页带稳定原因码,且不发会话; +6. 「免登必须校验 state」打开(强制档)时点卡片这一跳**会被挡**——这条是给运维看的: + 开那一档之前先确认 Hub 门户真会把 state 原样带回。 + +连开发库。跑完把这次建的短码、刷新令牌、登录日志删干净,账号上被顺手改的几列一并还原; +负例故意用一个库里没有的 Hub 主键,免得 ``user_inactive`` 那一路把谁现有会话踢下线。 +""" + +from __future__ import annotations + +import datetime as dt +import os +import pathlib +import sys +from urllib.parse import quote + +HERE = pathlib.Path(__file__).resolve().parent +sys.path.insert(0, str(HERE)) +sys.path.insert(0, str(HERE.parent)) + +from check_notify_hub import FakeHub, envelope # noqa: E402 + +FAILS: list[str] = [] + + +def eq(name: str, got, want) -> None: + if got != want: + FAILS.append(f"{name}:期望 {want!r},实得 {got!r}") + + +def ok(name: str, condition, detail=None) -> None: + if not condition: + FAILS.append(f"{name}:{detail if detail is not None else '条件不成立'}") + + +def main() -> int: + hub = FakeHub() + env_keys = ("OA_HUB_BASE_URL", "OA_HUB_INTEGRATION_KEY", "OA_HUB_SSO_STATE_REQUIRED") + saved = {key: os.environ.get(key) for key in env_keys} + os.environ["OA_HUB_BASE_URL"] = hub.base_url + os.environ["OA_HUB_INTEGRATION_KEY"] = "landing-probe-key" + os.environ["OA_HUB_SSO_STATE_REQUIRED"] = "false" + + from sqlalchemy import select + + from app import hubconfig, models + from app.db import SessionLocal + + hubconfig.reload() + cfg = hubconfig.get() + started = dt.datetime.now() + + db = SessionLocal() + try: + person = db.execute( + select(models.User) + .where(models.User.hub_user_id.isnot(None)) + .where(models.User.status.in_(sorted(models.UserStatus.LOGIN_ALLOWED))) + .order_by(models.User.id) + .limit(1) + ).scalars().first() + finally: + db.close() + if person is None: + print("库里没有一个已认领 Hub 主键的账号,这一份验不了") + return 1 + hub_id, account = str(person.hub_user_id), str(person.account) + snapshot = {"last_login_at": person.last_login_at, "source": person.source, + "hub_user_id": person.hub_user_id, "hub_synced_at": person.hub_synced_at} + + from fastapi.testclient import TestClient + + from app.main import app + + client = TestClient(app) # 不进 with:不跑 startup,本进程不起调度线程 + verify_path = cfg.hub_path_ticket_verify + + def ticket(**over) -> dict: + data = {"active": True, "sub": hub_id, "account": account, + "display_name": person.display_name, "app_code": (cfg.hub_app_code or "oa").lower(), + "state": ""} + data.update(over) + return data + + def land(query: str): + """走一遍浏览器那一跳:GET 回调(不自动跟 302),交回 ``(状态, Location, Cookie)``。""" + response = client.get(f"/sso/hub?{query}", follow_redirects=False) + return response.status_code, response.headers.get("location") or "", response + + def exchange(response) -> tuple[int, dict]: + code = (response.headers.get("location") or "").split("#code=")[-1] + got = client.post("/api/v1/auth/sso/exchange", json={"code": code}, + headers={"Cookie": f"oa_sso_handoff={response.cookies.get('oa_sso_handoff', '')}"}) + try: + return got.status_code, (got.json() or {}).get("data") or {} + except ValueError: + return got.status_code, {} + + try: + # 1) 正常那一跳:待办深链一路带到前端 + hub.script = [envelope(**ticket())] + status, location, landed = land(f"ticket=T-LANDING-1&redirect={quote('/todo/task-9', safe='')}") + eq("回调 302", status, 302) + ok("落到前端落地页并带短码", location.startswith("/sso#code="), location) + ok("票据原值不进 302 地址", "T-LANDING-1" not in location, location) + ok("兑换串只走 HttpOnly Cookie", "oa_sso_handoff" in dict(landed.cookies), dict(landed.cookies)) + verifies = [row for row in hub.requests if row["path"] == verify_path] + eq("验票只问一次(不重试)", len(verifies), 1) + eq("验票用的是免登那把集成密钥", verifies[0]["key"], "landing-probe-key") + eq("验票只带票据,不带 app_code(文档 4.1)", verifies[0]["body"], {"ticket": "T-LANDING-1"}) + code, data = exchange(landed) + eq("兑换短码换到会话", code, 200) + eq("落点就是那条待办", data.get("redirect"), "/todo/task-9") + eq("这一趟算统一门户免登", data.get("via"), "hub_sso") + ok("会话令牌发齐了", bool(data.get("access_token")) and bool(data.get("refresh_token")), + list(data)) + again = client.post("/api/v1/auth/sso/exchange", json={"code": location.split("#code=")[-1]}, + headers={"Cookie": f"oa_sso_handoff={landed.cookies.get('oa_sso_handoff', '')}"}) + eq("同一条短码只能兑一次", again.status_code, 401) + + # 2) redirect 只认站内路径 + hub.script = [envelope(**ticket())] + status, location, landed = land(f"ticket=T-LANDING-2&redirect={quote('//evil.example.com/x', safe='')}") + eq("双斜杠的 redirect 照样落地", status, 302) + code, data = exchange(landed) + eq("外站 redirect 当没填", data.get("redirect"), "") + + # 3) 没带 redirect(纯文字提醒那类):会话照换,落点交给前端 + hub.script = [envelope(**ticket())] + status, location, landed = land("ticket=T-LANDING-3") + code, data = exchange(landed) + eq("没 redirect 也换得到会话", code, 200) + eq("落点留空由前端挑兜底页", data.get("redirect"), "") + + # 4) 票据无效:302 回落地页带原因码,不发会话(用库里没有的主键,别踢人下线) + hub.script = [envelope(**ticket(active=False, sub="999999999", + reason="ticket_invalid"))] + status, location, landed = land("ticket=T-LANDING-4") + eq("票据无效也是 302", status, 302) + ok("带着能翻成文案的原因码", "error=SSO_TICKET_INVALID" in location, location) + ok("这一趟没有短码", "#code=" not in location, location) + + # 5) 串号:别的应用的票据 + hub.script = [envelope(**ticket(app_code="crm"))] + status, location, landed = land("ticket=T-LANDING-5") + ok("应用编码不对就拒", "error=SSO_APP_MISMATCH" in location, location) + + # 6) 强制档:推送链路的票据不带 state,开了那一档就是进不来 + os.environ["OA_HUB_SSO_STATE_REQUIRED"] = "true" + hubconfig.reload() + hub.script = [envelope(**ticket())] + status, location, landed = land("ticket=T-LANDING-6") + ok("强制档挡下不带 state 的点击", "error=SSO_STATE_REJECTED" in location, location) + os.environ["OA_HUB_SSO_STATE_REQUIRED"] = "false" + hubconfig.reload() + finally: + cleanup = SessionLocal() + try: + cleanup.query(models.SsoHandoff).filter(models.SsoHandoff.create_time >= started).delete() + cleanup.query(models.RefreshToken).filter( + models.RefreshToken.person == str(person.id), + models.RefreshToken.create_time >= started).delete() + cleanup.query(models.OperationLog).filter( + models.OperationLog.action == "login", + models.OperationLog.target == account, + models.OperationLog.create_time >= started).delete() + row = cleanup.get(models.User, int(person.id)) + for key, value in snapshot.items(): + setattr(row, key, value) + cleanup.commit() + finally: + cleanup.close() + for key, value in saved.items(): + if value is None: + os.environ.pop(key, None) + else: + os.environ[key] = value + hubconfig.reload() + hub.close() + + for line in FAILS: + print(f"[FAIL] {line}") + if FAILS: + print(f"共 {len(FAILS)} 条不对") + return 1 + print("通过:待办深链一路带到前端、redirect 只认站内路径、没 redirect 也换得到会话、" + "票据不进 302 地址且验票只问一次不带 app_code、短码一次性、无效票与串号都带原因码落回登录页、" + "强制校验 state 时点卡片这一跳会被挡") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/backend/scripts/check_notify_wake.py b/backend/scripts/check_notify_wake.py new file mode 100644 index 0000000..e89b6e4 --- /dev/null +++ b/backend/scripts/check_notify_wake.py @@ -0,0 +1,256 @@ +#!/usr/bin/env python3 +"""渠道提醒 / 订阅事件什么时候真的发出去:入队提交当场叫醒,回滚不空叫。 + + cd backend && PYTHONPATH=. python3 scripts/check_notify_wake.py + +开发库上 ``oa_notify_delivery`` 的量法:一条企业微信推送从 ``create_time`` 到 +``sent_at`` 等了 **28 / 35 / 55 / 60 秒**,而 ``ms`` 那一格显示真发那一次只用 1 秒。 +慢的不是发送——是消息渠道与事件订阅入队时**没人叫醒**调度线程,只能干等下一个轮询 +周期(写回发件箱早就有叫醒,那两路没接上)。这几条把叫醒的时机钉住: + +1. **随事务提交当场叫**:``channels.enqueue_for`` 排上投递记录,提交那一刻叫醒; +2. **没提交不叫**:事务还没提交,那条记录对别的连接还不可见,叫了是跑一趟空; +3. **回滚不叫**:单没过,投递记录跟着一起回滚; +4. **没排上行不叫**:事件没渠道订阅 → 一条记录都没有 → 不空叫; +5. **订阅事件同一条通路**:``events.emit`` 入队也是提交即叫; +6. **人工重发也叫**:点「重发」的人就是想看结果。 + +渠道与订阅都指向 ``*.invalid``(DNS 必然失败),跑完把渠道、订阅、投递记录、事件删干净。 +""" + +from __future__ import annotations + +import pathlib +import sys +import time +from datetime import datetime, timedelta +from types import SimpleNamespace + +HERE = pathlib.Path(__file__).resolve().parent +sys.path.insert(0, str(HERE)) +sys.path.insert(0, str(HERE.parent)) + +from sqlalchemy import delete, or_, select # noqa: E402 + +from app import models # noqa: E402 +from app.db import SessionLocal # noqa: E402 +from app.service import channels, events, wake # noqa: E402 + +STAMP = int(time.time()) +CH = f"wk_ch_{STAMP}" +HOOK = f"wk_hook_{STAMP}" +JOB = f"wkwakejob{STAMP}" +#: 测试自己造的事件名,**不用 task / work.submitted**:开发库里躺着真的渠道与订阅, +#: 拿真事件名入队会给它们也排上一条,叫醒机制一生效就真的往企业微信发出去了。 +EVENT = f"wk_event_{STAMP}" +EVENT_NONE = f"wk_none_{STAMP}" +EVENT_OPEN = f"wk_open_{STAMP}" +EVENT_OPEN_NONE = f"wk_open_none_{STAMP}" +TITLE = f"[叫醒校验 {STAMP}]" + +FAILS: list[str] = [] +PASSED = 0 +WAKES: list[int] = [] +CREATED: dict = {} + +#: 把刚排上的记录推到将来,别让**同时在跑的那个后端进程**的调度线程抢发(它们会 +#: 真的去连 ``*.invalid``,多一条没意义的失败留痕;测的是"什么时候醒",不是发得成) +PARK_SECONDS = 600 + + +def check(label: str, condition, detail: str = "") -> None: + global PASSED + if condition: + PASSED += 1 + print(f"[通过] {label}") + else: + FAILS.append(label) + print(f"[FAIL] {label}{f' -> {detail}' if detail else ''}") + + +def park(db, rows) -> None: + moment = (datetime.now() + timedelta(seconds=PARK_SECONDS)).replace(microsecond=0) + for row in rows: + row.next_attempt_at = moment + db.flush() + db.commit() + + +def deliveries(db) -> list[models.NotifyDelivery]: + return list(db.execute( + select(models.NotifyDelivery).where(models.NotifyDelivery.channel == CH) + ).scalars().all()) + + +def build(db) -> str: + """一个真账号 + 一条 webhook 渠道 + 一条订阅,地址都指向打不通的域名。""" + person = db.execute( + select(models.User) + .where(models.User.status.in_(sorted(models.UserStatus.LOGIN_ALLOWED))) + .order_by(models.User.id) + .limit(1) + ).scalars().first() + if person is None: + raise SystemExit("[跳过] 库里没有一个可登录的账号,没法验收件人") + db.add(models.NotifyChannel( + code=CH, name=f"{TITLE} 渠道", kind=models.NotifyChannel.KIND_WEBHOOK, + enabled=True, events=[EVENT], config={"url": "https://robot.invalid/hook"}, + timeout_seconds=2, retries=1, + )) + db.add(models.OpenWebhook( + code=HOOK, name=f"{TITLE} 订阅", enabled=True, + url="https://sub.invalid/hook", events=[EVENT_OPEN], send_data=False, + timeout_seconds=2, retries=1, + )) + db.commit() + # presence 那一层可能还存着"这张表没有启用的行",本 Session 写过就该照实问库 + CREATED.update(channel=CH, hook=HOOK) + return str(person.account) + + +def fake_work() -> SimpleNamespace: + return SimpleNamespace(job=JOB, id=JOB, serial=f"WKWAKE{STAMP}", title="叫醒校验单", + status="running", process="", process_name="", creator="1", + creator_person="1", activity="n1", data={}) + + +def _run(db) -> None: + account = build(db) + wake.hook(lambda: WAKES.append(len(WAKES))) + check("渠道建好就能被投递侧看到(presence 没把'没有渠道'这个旧结论留住)", + any(row.code == CH for row in channels.channels_for(db, EVENT)), + [row.code for row in channels.channels_for(db, EVENT)]) + + # ---------------------------------------------- 1/2. 提交才算数,提交那一刻才叫 + rows = channels.enqueue_for(db, [account], event=EVENT, title=f"{TITLE} 待办", + body="验证入队叫醒", job=JOB) + db.flush() + check("排上了投递记录(收件人认得出、渠道订阅了这个事件)", rows >= 1, rows) + check("事务没提交时不叫醒(那条记录对别的连接还不可见,叫了是跑空)", not WAKES, WAKES) + db.commit() + check("投递记录随事务提交 → 当场叫醒投递线程", len(WAKES) == 1, WAKES) + park(db, deliveries(db)) + + # ---------------------------------------------- 3. 回滚不叫 + WAKES.clear() + before = len(deliveries(db)) + channels.enqueue_for(db, [account], event=EVENT, title=f"{TITLE} 回滚不算数", job=JOB) + db.flush() + db.rollback() + check("事务回滚了不叫醒(单没过,投递记录也跟着没了)", not WAKES, WAKES) + check("回滚之后库里没多出投递记录", len(deliveries(db)) == before, + (before, len(deliveries(db)))) + + # ---------------------------------------------- 4. 没排上行不空叫 + WAKES.clear() + rows = channels.enqueue_for(db, [account], event=EVENT_NONE, title=f"{TITLE} 没人订阅", job=JOB) + db.commit() + check("这个事件没渠道订阅:一条都不排,也不空叫一次", rows == 0 and not WAKES, (rows, WAKES)) + + # ---------------------------------------------- 5. 订阅事件走同一条通路 + WAKES.clear() + count = events.emit(db, fake_work(), EVENT_OPEN, activity_name="提交") + db.flush() + check("订阅入队时先不叫(等提交)", count >= 1 and not WAKES, (count, WAKES)) + db.commit() + check("事件订阅随事务提交 → 当场叫醒", len(WAKES) == 1, WAKES) + + WAKES.clear() + count = events.emit(db, fake_work(), EVENT_OPEN_NONE, activity_name="作废") + db.commit() + check("没人订阅这个事件:不排、不叫", count == 0 and not WAKES, (count, WAKES)) + + # ---------------------------------------------- 6. 人工重发也叫醒 + WAKES.clear() + rows = deliveries(db) + check("前面这几趟留下了可重发的投递记录", bool(rows), len(rows)) + if rows: + resent = channels.resend(db, rows[0].id) + check("人工重发:回到 pending 并当场叫醒(点重发的人就是想看结果)", + resent is not None and resent.status == models.NotifyDelivery.STATUS_PENDING + and len(WAKES) == 1, + (getattr(resent, "status", None), WAKES)) + if resent is not None: + park(db, [resent]) + + # ---------------------------------------------- 7. 叫醒只改"何时醒",不改跑什么 + from app import main as main_module + + stir, stop = main_module._scheduler_stir, main_module._scheduler_stop + saved_stop = stop.is_set() + stop.clear() + stir.clear() + started = time.monotonic() + main_module._wake_scheduler() + check("被叫醒时 _scheduler_sleep 立刻返回,且不退出线程", + main_module._scheduler_sleep(30) is False and time.monotonic() - started < 5, + f"等了 {time.monotonic() - started:.2f}s") + stop.set() + stir.clear() + started = time.monotonic() + main_module._wake_scheduler() + check("退出信号优先:睡里被叫醒也要认出该退出", + main_module._scheduler_sleep(30) is True and time.monotonic() - started < 5, + f"等了 {time.monotonic() - started:.2f}s") + if saved_stop: + stop.set() + else: + stop.clear() + stir.clear() + + # ---------------------------------------------- 8. 接线:调度线程真的在听这一层 + # 上面那几条验的是"入队 → 该叫",这一段验"叫了 → 线程真的醒": + # ``start_scheduler`` 里那句登记把 ``_wake_scheduler`` 接到本层。这里把 Thread 换成 + # 不起动的假类,只验接线,不在校验进程里真跑一轮调度(那会去抢租约、去发 parked 的行)。 + real_thread = main_module.threading.Thread + + class QuietThread(real_thread): + def __init__(self, *args, **kwargs): # 记下参数,但不起线程 + self.args, self.kwargs = args, kwargs + + def start(self): + return None + + main_module.threading.Thread = QuietThread + try: + main_module.start_scheduler() + finally: + main_module.threading.Thread = real_thread + check("start_scheduler 把调度线程登记成叫醒对象(渠道与事件共享写回那条通路)", + main_module._wake_scheduler in wake._hooks, len(wake._hooks)) + main_module._scheduler_stir.clear() + wake.now() + check("叫醒通路 → 调度线程那条睡真的被中断", main_module._scheduler_stir.is_set()) + main_module._scheduler_stir.clear() + + +def main() -> int: + db = SessionLocal() + try: + _run(db) + finally: + cleanup(db) + print() + if FAILS: + print(f"{len(FAILS)} 条没对上:") + for item in FAILS: + print(f" - {item}") + else: + print(f"全部 {PASSED} 条对上。") + return 1 if FAILS else 0 + + +def cleanup(db) -> None: + db.execute(delete(models.NotifyDelivery).where(or_( + models.NotifyDelivery.channel == CH, + models.NotifyDelivery.title.like(f"{TITLE}%")))) + db.execute(delete(models.OpenEvent).where(or_(models.OpenEvent.webhook == HOOK, + models.OpenEvent.job == JOB))) + db.execute(delete(models.OpenWebhook).where(models.OpenWebhook.code == HOOK)) + db.execute(delete(models.NotifyChannel).where(models.NotifyChannel.code == CH)) + db.commit() + print("[清理] 渠道、订阅、投递记录与事件已删干净") + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/backend/scripts/check_org_tree_managers.py b/backend/scripts/check_org_tree_managers.py index b67ca5d..5fae262 100644 --- a/backend/scripts/check_org_tree_managers.py +++ b/backend/scripts/check_org_tree_managers.py @@ -35,6 +35,9 @@ from app.service import org, personref FAILS: list[str] = [] PASSED = 0 +#: 脚本自己造的数据都带这个前缀,方便一眼认出是谁干的(跑完整体回滚,库里不留) +MARK = "zzorgtree-" + #: 数语句条数:这一层买的就是「少排几次队」,判据只看条数。 ROWS: list[str] = [] @@ -46,7 +49,12 @@ PARAMS: list[dict] = [] @event.listens_for(engine, "after_cursor_execute") def _count(conn, cursor, statement, parameters, context, many): # noqa: ANN001 ROWS.append(" ".join(statement.split())[:120]) - PARAMS.append(dict(parameters or {})) + if many: + # ORM 会把同类 UPDATE/INSERT 攒成 executemany,这时 parameters 是一串参数组; + # 直接 dict() 会炸("sequence element #0 has length 3"),摊开一条条记。 + PARAMS.extend(dict(row or {}) for row in parameters or []) + else: + PARAMS.append(dict(parameters or {})) def check(label: str, ok: bool, detail: str = "") -> None: @@ -157,8 +165,18 @@ def pick_admin(db): return deps.CurrentUser.resolve(db, row, personref.ref_of(row)) if row else None -def pick_restricted(db): - """一个数据范围真受限的人:不受限就量不出「负责人在范围外」那一条。""" +def pick_restricted(db, prefer=None): # noqa: ANN001 + """一个数据范围真受限的人:不受限就量不出「负责人在范围外」那一条。 + + ``prefer`` 是 :func:`seed_membership` 刚临时挂上部门的那个人:范围照他的部门算, + 最可能是这三条检查要的那个形状,先试他。 + """ + if prefer is not None: + guess = db.get(models.User, int(prefer)) + if guess is not None and guess.role != models.ROLE_ADMIN: + user = deps.CurrentUser.resolve(db, guess, personref.ref_of(guess)) + if not permissions.unrestricted(user) and permissions.scope_unit_ids(db, user): + return user rows = db.execute( select(models.User) .where(models.User.role != models.ROLE_ADMIN, @@ -186,15 +204,124 @@ def same_payload(db, user, label: str) -> int: return new_stmts - old_stmts +def seed_units(db) -> set[int]: # noqa: ANN001 + """库里一个部门都没有(刚清过测试数据):临时造一小棵树,跑完整体回滚。 + + 这个脚本量的是「部门树上那一格负责人姓名」,一个部门都没有就没得量:老版本直接取 + ``units[0]`` 当锚点,干净库上是一记 IndexError,看着像代码坏了,其实是库是空的。 + 一棵两层带一个旁支,旁支那一支正好给「负责人在范围外」当对照。 + """ + if db.execute(select(models.Unit.id).limit(1)).first() is not None: + return set() + root = models.Unit(name="临时根部门", code=f"{MARK}root", alias=f"{MARK}root", + path="临时根部门\\", status=models.UnitStatus.ACTIVE) + db.add(root) + db.flush() + child = models.Unit(name="临时子部门", code=f"{MARK}child", alias=f"{MARK}child", + parent_id=root.id, path=f"{root.path}临时子部门\\", + status=models.UnitStatus.ACTIVE) + side = models.Unit(name="临时旁支部门", code=f"{MARK}side", alias=f"{MARK}side", + path="临时旁支部门\\", status=models.UnitStatus.ACTIVE) + db.add_all([child, side]) + db.flush() + print("[提示] 这个库里一个部门都没有,临时建了 3 个(跑完整体回滚)") + return {root.id, child.id, side.id} + + +def visible_units(db, person) -> list[int]: # noqa: ANN001 + """这个人现在到底看得见哪几个部门(一个都看不见就量不到「范围外」那一条)。""" + user = deps.CurrentUser.resolve(db, person, personref.ref_of(person)) + if permissions.unrestricted(user): + return [] + return list(permissions.scope_unit_ids(db, user) or []) + + +def seed_membership(db): # noqa: ANN001 + """没有一个人挂在部门上、或者没人带部门范围的角色:临时补上,跑完整体回滚。 + + 数据范围是按部门算的。谁都不在部门里、或部门范围一类角色一个都没配,那个「非超管」 + 就一个部门也看不见,「负责人在范围外」这条根本量不到。回 (用来当样例的人, 临时角色 id)。 + """ + person = db.execute( + select(models.User) + .where(models.User.role != models.ROLE_ADMIN, + models.User.status == models.UserStatus.ACTIVE, + models.User.organization_id.is_not(None)) + .order_by(models.User.id) + ).scalars().first() + seeded_person_id = None + if person is None: + person = db.execute( + select(models.User) + .where(models.User.role != models.ROLE_ADMIN, + models.User.status == models.UserStatus.ACTIVE) + .order_by(models.User.id) + ).scalars().first() + unit = db.execute(select(models.Unit).order_by(models.Unit.id)).scalars().first() + if person is None or unit is None: + return None, None + person.organization_id = unit.id + db.flush() + print(f"[提示] 这个库里没有一个人挂在部门上,临时把 {person.account} 挂到 " + f"{unit.name}(跑完整体回滚)") + seeded_person_id = person.id + role_id = None + if not visible_units(db, person): + role = models.AuthRole(name=f"{MARK}scope", description="体检脚本临时建的", + permissions=[], data_scope="unit_and_below") + db.add(role) + db.flush() + db.add(models.PersonAuthRole(person_id=person.id, role_id=role.id)) + db.flush() + role_id = role.id + print(f"[提示] 这个库里没人带「本部门及下级」这类角色,临时给 {person.account} " + f"挂了一个(跑完整体回滚)") + return seeded_person_id, role_id + + +def seed_managers(db) -> set[int]: # noqa: ANN001 + """一个部门都没配过负责人的库:先自己挂两个,否则这脚本没法跑(整段在事务里,跑完回滚)。 + + 没有负责人时,「停用 / 系统账号 / 范围外三种照样写得出名字」那几条是空跑, + 而下面取锚点部门的 ``units[0]`` 会直接 IndexError 崩掉,看着像脚本坏了,其实是库太干净。 + """ + if db.execute( + select(models.Unit.id).where(models.Unit.manager_person_id.is_not(None)).limit(1) + ).first() is not None: + return set() + hosts = db.execute(select(models.Unit).order_by(models.Unit.id).limit(2)).scalars().all() + people = db.execute( + select(models.User) + .where(models.User.status == models.UserStatus.ACTIVE) + .order_by(models.User.id.desc()) + .limit(2) + ).scalars().all() + seeded: set[int] = set() + for host, person in zip(hosts, people): + host.manager_person_id = person.id + seeded.add(host.id) + db.flush() + if seeded: + print(f"[提示] 这个库里没有部门配过负责人,临时给 {len(seeded)} 个部门各挂一个(跑完回滚)") + return seeded + + def main() -> int: db = SessionLocal() try: - admin, scoped = pick_admin(db), pick_restricted(db) - check("样例账号在位:一个超管 + 一个数据范围真受限的人", - admin is not None and scoped is not None and admin.is_admin and not scoped.is_admin, + # 先补库:刚清过测试数据的库既没有部门、也没人挂在部门上,直接往下跑会当场崩 + seeded_units = seed_units(db) + seeded_person, seeded_role = seed_membership(db) + admin, scoped = pick_admin(db), pick_restricted(db, prefer=seeded_person) + check("样例账号在位:一个超管 + 一个看得见部门的非超管", + admin is not None and scoped is not None and admin.is_admin + and not scoped.is_admin and bool(permissions.scope_unit_ids(db, scoped)), f"admin={admin and admin.account} scoped={scoped and scoped.account}") # ---- 1 / 2:常态下报文相同、条数更少 -------------------------------- + # 先备好负责人:这两条量的是"负责人已经在内存里就别再问库", + # 一个负责人都没有就量不出差别(干净库上会假报"差 0 条") + seeded = seed_managers(db) delta_admin = same_payload(db, admin, "超管看全公司") delta_scoped = same_payload(db, scoped, "非超管按数据范围") check(f"超管:复用人员行确实少问库(差 {delta_admin} 条)", delta_admin < 0, f"{delta_admin}") @@ -221,6 +348,7 @@ def main() -> int: .order_by(models.User.id.desc()) ).scalars().first() check("找得到一个人可临时改成停用", victim is not None) + point = db.begin_nested() if victim is not None: anchor.manager_person_id = victim.id victim.status = models.UserStatus.DISABLED @@ -237,9 +365,13 @@ def main() -> int: f"实得「{manager_names(new_json)[str(unit_id)]}」期望「{victim.display_name}」") check(f"负责人停用:这一趟照样回库问({old_stmts} → {new_stmts} 条)", new_stmts == old_stmts, f"{old_stmts} → {new_stmts}") - db.rollback() + # 只退这一段:刚改的负责人与停用退回 SAVEPOINT,上面 seed 出来的还得留着 + point.rollback() + db.expire_all() + anchor = db.get(models.Unit, unit_id) # (b) 负责人是内置系统账号:树上剔掉了他,名字还得在 + point = db.begin_nested() db.refresh(anchor) system_person = db.execute( select(models.User).where(models.User.account.in_(org.system_account_names())) @@ -260,9 +392,11 @@ def main() -> int: and manager_names(new_json)[str(unit_id)] == system_person.display_name, f"实得「{manager_names(new_json)[str(unit_id)]}」" f"期望「{system_person.display_name}」") - db.rollback() + point.rollback() + db.expire_all() # (c) 负责人在本次数据范围之外:非超管看不见他,名字还得在 + point = db.begin_nested() db.refresh(anchor) outsider = db.execute( select(models.User) @@ -299,11 +433,16 @@ def main() -> int: f"期望「{outsider.display_name}」") check(f"负责人在范围外:这一趟照样回库问({old_stmts} → {new_stmts} 条)", new_stmts == old_stmts, f"{old_stmts} → {new_stmts}") - db.rollback() + point.rollback() + db.expire_all() finally: - db.rollback() + # 三段临时改动各自退回了自己的 SAVEPOINT,这里只把值读回来复核 + db.expire_all() back = db.execute(select(models.Unit.manager_person_id).where(models.Unit.id == unit_id)).scalar() - check("跑完库里负责人没被动过", back == original, f"{back} != {original}") + # 三段临时改动各退各的 SAVEPOINT,退完之后锚点必须回到它们开始之前的样子; + # 这个锚点本身是 seed_managers 挂的,那一份得活到脚本最后一次整体回滚才消失 + check("跑完三段临时改动各自退干净,锚点回到开始之前", + back == original, f"{back} != {original}") # ---- 4:没得复用的调用点(``/org/units``)口径不变 ------------------- rows = db.execute(select(models.Unit)).scalars().all() @@ -327,6 +466,7 @@ def main() -> int: if len(active) >= 2: holder, other_person = active[0], active[1] original_manager = anchor_unit.manager_person_id + point = db.begin_nested() try: anchor_unit.manager_person_id = holder.id db.flush() @@ -354,8 +494,33 @@ def main() -> int: other.manager_person_id = original_other db.flush() finally: - anchor_unit.manager_person_id = original_manager - db.rollback() + point.rollback() + db.expire_all() + + # 收尾:整个事务回滚,脚本临时造的部门、任职、角色必须一起消失 + db.rollback() + db.expire_all() + if seeded: + still = db.execute( + select(models.Unit.id).where(models.Unit.id.in_(seeded), + models.Unit.manager_person_id.is_not(None)) + ).scalars().all() + check("跑完临时挂的负责人也回滚干净", not still, f"{still}") + if seeded_units: + left = db.execute( + select(models.Unit.id).where(models.Unit.id.in_(seeded_units)) + ).scalars().all() + check("跑完临时部门已随事务一起回滚", not left, f"还剩 {left}") + if seeded_person is not None: + back_org = db.execute( + select(models.User.organization_id).where(models.User.id == seeded_person) + ).scalar() + check("跑完临时挂的任职也回滚干净", back_org is None, f"{back_org}") + if seeded_role is not None: + left_role = db.execute( + select(models.AuthRole.id).where(models.AuthRole.id == seeded_role) + ).scalars().all() + check("跑完临时权限角色也回滚干净", not left_role, f"{left_role}") return 1 if FAILS else 0 finally: as_new_style() diff --git a/backend/scripts/check_presence_guard.py b/backend/scripts/check_presence_guard.py index d32182e..cb33e73 100644 --- a/backend/scripts/check_presence_guard.py +++ b/backend/scripts/check_presence_guard.py @@ -303,20 +303,41 @@ def snapshot_reuse() -> None: def empty_fast_paths() -> None: - """一张表里确实没有可用行时,这四条路一条库都不许多问。""" + """这四条路省的是"存在性探针"那一次往返;表空时连行都不必读。 + + 判据分两种口径,因为**配了东西的部署里 0 次问库是不可能的**:``readcache`` 只活在 + 一个 Session 内(跨请求必须重读,否则改了渠道要等 TTL 才生效),所以表里有可用行时 + 每个新 Session 仍要读一次行,省下来的只有 :mod:`app.presence` 那一条探针。 + 表空才是"一条都不许多问"的那个场景。 + """ presence.clear() now = datetime.now() + #: 每条路的 ``(名字, 走一遍这条路, 它自己那一个存在性探针)``——判"表里有没有可用行" + #: 用的就是服务层那一个 loader,口径绝不会跟被检的那条路漂开 probes = [ - ("没有启用的代理就不问库", lambda db: org.apply_agents(db, "", ["某个人"], now)), - ("没有启用的渠道就不问库", lambda db: channels.channels_for(db, "task.created")), - ("没有启用的订阅就不问库", lambda db: events.subscriptions(db, "task.created")), - ("没有卡人的报文就不问库", lambda db: outbox.blocking(db, job="某个 job")), + ("没有启用的代理就不问库", lambda db: org.apply_agents(db, "", ["某个人"], now), + org.has_enabled_agent), + ("没有启用的渠道就不问库", lambda db: channels.channels_for(db, "task.created"), + channels.has_enabled_channel), + ("没有启用的订阅就不问库", lambda db: events.subscriptions(db, "task.created"), + events.has_enabled_webhook), + ("没有卡人的报文就不问库", lambda db: outbox.blocking(db, job="某个 job"), + outbox.has_blocking_candidate), ] - for label, call in probes: + for label, call, probe_loader in probes: + probe = SessionLocal() + try: + populated = bool(probe_loader(probe)) + finally: + probe.close() presence.clear() first_value, first = counted(lambda: call(SessionLocal())) # 探针问一次 second_value, second = counted(lambda: call(SessionLocal())) # 结论在进程里 - check(label, second == 0, f"第二趟 {second} 条") + if populated: + check(f"{label}(表里有可用行,只省探针)", second < first, + f"第一趟 {first} 条 / 第二趟 {second} 条") + else: + check(label, second == 0, f"第二趟 {second} 条") check(f"{label}(两趟答案一致)", repr(first_value) == repr(second_value)) diff --git a/backend/scripts/purge_test_data.py b/backend/scripts/purge_test_data.py index f23a62e..c1ab947 100644 --- a/backend/scripts/purge_test_data.py +++ b/backend/scripts/purge_test_data.py @@ -85,6 +85,13 @@ WORK_ACTIONS = frozenset({ "batch_execute_task", "goback_task", "add_task", "transfer_task", "cc_task", "share_work", "comment_work", "delete_comment", "handle_read", "reset_task", + # 这些是后来加的流程动作,target 同样只指向单据 / 待办 / 环节决定:漏在这儿, + # 全清之后库里就剩一地指向已删单据的悬空日志(界面上操作记录点开查无此单)。 + "work_start", "delete_job", "admin_transfer", "admin_suspend", "admin_resume", + "admin_move", + "admin_press_work", "node_decision_confirm", "node_decision_reject", + "external_check_submit", "external_check_pass", "external_check_withdraw", + "external_check_refresh", "admin_fix_data", "admin_transfer_work", }) #: 还原时的插回顺序:先单据与额度,再是挂在它们身上的行 diff --git a/deploy/k8s/README.md b/deploy/k8s/README.md index 17af581..6d2ec99 100644 --- a/deploy/k8s/README.md +++ b/deploy/k8s/README.md @@ -12,7 +12,7 @@ MinIO / 统一身份那套真值都在镜像里,**集群里一份配置都不 | --- | --- | | 仓库 | `docker.oa.unissense.tech/public/unis_oa`(Harbor,`public` 项目,匿名可拉) | | 架构 | `linux/amd64` | -| tag | 时间戳(当前 `202611041447`)+ `latest` | +| tag | 时间戳(当前 `202611051545`)+ `latest` | | 大小 | 压缩后约 96 MB | | 端口 | `8000`(后端 API 与前端静态页同源,一个容器全包) | | 配置 | 自带 `config.toml` + `config.prod.toml`(含密钥),不挂配置也能起 | diff --git a/deploy/k8s/unis-oa.yaml b/deploy/k8s/unis-oa.yaml index 9447f08..f7a7ec5 100644 --- a/deploy/k8s/unis-oa.yaml +++ b/deploy/k8s/unis-oa.yaml @@ -152,6 +152,48 @@ spec: containers: - name: unis-oa # 钉时间戳 tag:回滚才有得选。想用 latest 就把下面 imagePullPolicy 改成 Always + # 202611051355 起(已推 Harbor,digest sha256:52e9ef01…,linux/amd64):Hub 同步不再漏锁。 + # sync_users / _pull_changes 都是先拿锁、再写一条「进行中」记录,而写记录那一段在收尾 + # 那个 try **之外**:库断了、死锁、补列没跟上导致 INSERT 报错,异常直接从这段漏出去, + # finally 够不着,进程内那把 _run_lock 就永久扣着——症状是"明明没在同步,点立即同步 + # 一直回**已有同步任务正在执行,请稍后再试**",跨副本那把 Redis 锁最多一小时自己过期, + # 本进程这把只能等重启或有人按「终止」;调度线程每几十秒那趟增量撞的也是同一把锁, + # 整条组织同步一起停摆。现在建记录那一段自己负责把两把锁交还,异常照旧往外走。 + # 回归:backend/scripts/check_hub_sync_lock_leak.py 17 项(含「失败之后不做任何复位、 + # 紧接着再点一次进得来」与「正在跑的时候第二次拿锁仍被挡住」);口径见 + # docs/hub-integration.md。前端一行没动,产物与 202611051340 同一份。 + # ⚠️ 生产库要先补的列不变,仍是 202611051340 那条里写的 oa_notify_delivery.target_field + # 与 oa_hub_sync_run 那四列——补列没跟上恰恰就是这版会把锁扣住的那类 INSERT 报错。 + # 构建时把 backend/config.prod.toml 烤进镜像(21255 字节,含密钥)。 + # 手机上现在这一串是 202611051355(首屏问候语旁 / 「我的」最末尾)。 + # 202611051340 起(已推 Harbor,digest sha256:7b3bb883…,linux/amd64):流程明细导出 + # +企微推送改走统一身份+同步历史看得清。 + # 1) 侧栏新增「流程明细导出」(独立权限码 monitor:export,接口 /export/detail/*): + # 与流程监控共用同一份筛选口径取数、按流程分表出 CSV/Excel,「未操作者」分五类来源 + # (待办没办 / 待阅没打开 / 抄送需处理没回复 / 终止时被强行收尾 / 前置加签未激活), + # 值渲染与列表导出同一个 cell_text(service/detail_export.py、service/exportfmt.py, + # scripts/check_detail_export.py,口径见 docs/process-detail-export-design.md)。 + # 2) 消息通知多一种渠道 hub_wecom:企业微信应用消息交统一身份 Hub 代发,本系统不持有 + # 企微密钥,点卡片回来的免登走现成的 /api/v1/auth/sso/callback;「收件人按哪一列认」 + # (Hub 主键 / 登录账号)从写死在代码里提到渠道配置上,投递记录跟着记 target_field, + # 事后说得出这一串数字是谁的哪个号(scripts/check_notify_hub.py、 + # check_notify_hub_api.py、check_notify_landing.py、check_notify_wake.py)。 + # 3) 外发任务入队就把投递线程叫醒(service/wake.py,发件箱 / 消息渠道 / 事件订阅三条路 + # 共用):实测企微推送从入队到发出由 28~60 秒压到当下——慢的从来不是发送,是没人叫醒。 + # 4) Hub 同步历史不再只靠 message 那 2000 字:改名、僵尸账号让位、按「编码 + 名称」认回 + # 原部门各自成列,明细另存一份有界 JSON(oa_hub_sync_run 新增 renamed / reclaimed / + # units_rebound / details),配 scripts/check_hub_sync_*.py 五份对账。 + # 5) 免登那一跳不再多摆一屏「前往统一门户」(utils/ssoJump.ts):跳出去之前把来路存进 + # sessionStorage、落地接住,同一段时间最多自动跳两次,第三次起交回人自己点; + # 只在 sso 档自动跳,hybrid / local 那扇账号密码的门照旧留着。 + # ⚠️ 生产库先补列再换镜像:sql/upgrade/20261105_notify_receiver_field.sql 补 + # oa_notify_delivery.target_field;oa_hub_sync_run 那四列没有升级脚本, + # 跑一句 OA_ENV=prod PYTHONPATH=. python3 -c "from app.db import ensure_columns; print(ensure_columns())"。 + # 不补不会起不来,是同步历史与投递记录这两条路一路 500。 + # 构建时把 backend/config.prod.toml 烤进镜像(21255 字节,含密钥)。 + # 前端全量 122 文件 / 1363 条绿,vue-tsc / vite build 干净;后端 + # scripts/check_schema_snapshot.py 通过(65 张表,模型与快照一致)。 + # 那一版手机上那一串是 202611051340。 # 202611041447 起(已推 Harbor,digest sha256:21c627f3…,linux/amd64):手机上「表单内容」 # 那一屏能配了。前端 only,后端一行没动,下面那条 image 已升到这一版,集群重新导一次即生效。 # 原话:「表单内容里分费用报销基本信息、系统取数、完整单据,我就希望只有费用报销基本信息, @@ -790,7 +832,7 @@ spec: # 「服务器内部错误,请稍后重试(编号 xxxxxxxx)」) # 202610261047 起:镜像自带 backend/config.prod.toml(含密钥),且修了口令带 @ 时 # DSN 被撕成两个主机名的坑(backend/scripts/check_db_dsn.py 盯着) - image: docker.oa.unissense.tech/public/unis_oa:202611041447 + image: docker.oa.unissense.tech/public/unis_oa:202611051545 imagePullPolicy: IfNotPresent ports: - name: http diff --git a/docs/hub-integration.md b/docs/hub-integration.md index bf032c1..f44ec98 100644 --- a/docs/hub-integration.md +++ b/docs/hub-integration.md @@ -18,6 +18,7 @@ Hub、定时同步和「立即同步」分别做什么、哪些本地数据会 | 增量同步 | `OA_HUB_SYNC_CHANGES_ENABLED=true`(默认开) | 按游标轮询变更流水,几十秒内把人与部门的改动落到本地,排期那趟全量退成每日校对(见 8.1) | | 一键实时同步 | 人员管理页 / 系统设置页的「立即同步」按钮 | 走同一条同步逻辑,用于特殊情况实时补数据 | | 统一身份权限 | `OA_HUB_PERM_ENABLED=true`(默认关) | 角色、权限码与数据范围向 Hub 要口径;`shadow` 只对照、`enforce` 才参与判定(见 §9) | +| 企业微信消息推送 | 「消息通知」里建一个 `hub_wecom` 渠道(要 `OA_HUB_BASE_URL` + `OA_HUB_INTEGRATION_KEY`) | 待办 / 催办 / 办结这些提醒交给 Hub 代发成企业微信应用消息,卡片点开回到本系统那张单;**本系统不持有企微密钥**(见 §15) | | 本地会话空闲超时 | `OA_SESSION_IDLE_MINUTES=120`(默认 `0` = 不启用) | Hub 登出不会回收本系统的会话,这一段只能自己管:空闲到点就要求重新登录(见 5.3) | `OA_HUB_ENABLED` 是总闸,关掉以后登录、同步、页面入口全部回到接入前的样子。 @@ -25,8 +26,8 @@ Hub、定时同步和「立即同步」分别做什么、哪些本地数据会 上面这些开关都能在**系统设置 → 统一身份认证配置**里改,保存即生效,见 §3;下文的 环境变量是它们的默认值与兜底。 -Hub 要调的**接口路径一个都没写死在代码里**:登录这一层九条(验证码、登录、校验 token、 -当前用户、全量目录、变更流水、免登票据校验、可见应用列表、发起免登跳转)在 `config.toml` +Hub 要调的**接口路径一个都没写死在代码里**:登录这一层十条(验证码、登录、校验 token、 +当前用户、全量目录、变更流水、免登票据校验、可见应用列表、发起免登跳转、企业微信消息推送)在 `config.toml` 的 `[hub.api]`,权限那一层再加九条(`me/roles`、`me/permissions`、`me/data-scope`、 `directory/scoped` 与五条 `admin/*`)在 `[hub.perm.api]`。Hub 换前缀、挂网关反向代理、 改版换路径,改配置就行,见 §4 的两张「接口路径」表与 §3。 @@ -68,6 +69,7 @@ directory_changes = "/api/v1/auth/directory/changes" ticket_verify = "/api/v1/auth/tickets/verify" apps = "/api/v1/auth/apps" launch = "/api/v1/auth/apps/{code}/launch" +notify_wecom = "/api/v1/auth/notify/wecom/messages" # 企业微信推送(对接文档 9.6,见 §15) [hub.sync] enabled = true @@ -187,7 +189,7 @@ OA_HUB_INTEGRATION_KEY= | `OA_HUB_PORTAL_URL` | 空 | 统一门户首页:没登录时把用户送回哪里(对接指南要求回 Hub 站点首页)。留空用 `hub_base_url` | | `OA_HUB_SSO_STATE_REQUIRED` | `false` | 免登必须校验 `state`:默认只要求「带回来的 `state` 必须对上」;打开后连「门户压根没带回 `state`」也拒,而门户直点卡片正是没带回的那条路(见 5.2) | -接口路径(`config.toml` 的 `[hub.api]`,九个都不写死在代码里;只写路径部分,站点地址 +接口路径(`config.toml` 的 `[hub.api]`,十条都不写死在代码里;只写路径部分,站点地址 另配 `hub_base_url`;值不带开头的 `/` 会自动补上,写完整 URL、带空格或 `..` 会被挡): | 变量 | 配置文件里 | 默认值 | 干什么用 | @@ -202,8 +204,8 @@ OA_HUB_INTEGRATION_KEY= | `OA_HUB_PATH_APPS` | `[hub.api] apps` | `/api/v1/auth/apps` | 可见应用列表(门户落地页数据源,要用户登录态),本系统只用它在自检里验门户通不通 | | `OA_HUB_PATH_LAUNCH` | `[hub.api] launch` | `/api/v1/auth/apps/{code}/launch` | 发起免登跳转,`{code}` 调用时换成 `hub_app_code` | -这九个在「统一身份登录」配置组里叫「接口路径:xxx」,改完保存立刻生效; -`GET /api/v1/hub/status` 的 `api_paths` 会如实回显当前用的九个路径,连通性自检的 +这十条在「统一身份登录」配置组里叫「接口路径:xxx」,改完保存立刻生效; +`GET /api/v1/hub/status` 的 `api_paths` 会如实回显当前用的十个路径,连通性自检的 步骤名也带着路径,排查「到底在打哪个接口」时不用猜。免登跳转那一项带 `{code}` 占位符, 写坏了会退回出厂路径,不会因为一处笔误把免登整条通道弄哑。 @@ -232,6 +234,11 @@ OA_HUB_INTEGRATION_KEY= | `OA_HUB_SYNC_BIND_LOCAL_BY_CODE` | `true` | 本系统自己加的部门,组织编码跟 Hub 某个部门一样且这个编码本地只用过一次,就认成同一个部门(补 `hub_org_id`),不再另建重名部门。编码有歧义就跳过并写进同步记录 | | `OA_HUB_SYNC_INCLUDE_DISABLED_UNITS` | `true` | 带上 Hub 已停用的组织(`include_disabled=true`),否则整棵子树拿不到 | | `OA_HUB_SYNC_OFFBOARD` | `true` | Hub 里已消失的同步账号置为「已停用」,**只停用,不删除** | +| `OA_HUB_SYNC_OFFBOARD_GUARD_PERCENT` | `40` | **离职停用熔断**:一趟里等着停用的人超过本地同步账号总数的这个百分比、并且超过 `OA_HUB_SYNC_OFFBOARD_GUARD_MIN_PEOPLE` 人时,这一趟一个都不停用,只报数并把该趟标成 `partial`(见 6.1.1)。同一个百分比也管部门侧:要停用的部门超过 `max(OA_HUB_SYNC_UNIT_OFFBOARD_GUARD_MIN, 同步部门总数 × 百分比)` 时一个都不停(见 6.2)。取值 0–95,`0` = 关掉熔断 | +| `OA_HUB_SYNC_OFFBOARD_GUARD_MIN_PEOPLE` | `20` | 熔断线的**人数底线**:熔断线取「同步账号总数 × 百分比」与这个数里的较大者,所以几十人的小部署裁掉几个人不会被比例挡下来、天天弹熔断。取值 0–5000,`0` = 只看百分比。百分比本身设 `0` 时这一项不起作用 | +| `OA_HUB_SYNC_UNIT_OFFBOARD_GUARD_MIN` | `5` | **部门侧**熔断线的个数底线,口径同上。部门总数比人少一个量级,沿用人员那侧的 20 这条线永远不会触发,等于没有熔断。取值 0–5000 | +| `OA_HUB_SYNC_ROSTER_FLOOR_PERCENT` | `50` | **账号让位的清单人数下限**:Hub 这次回的人员数不足「可参照基准 × 这个百分比」时,认定目录正在被清空或重导,这一趟一个登录名都不让位(撞车照旧只报数)。实测 2026-11-05 测试站一天之内从 100 人掉到 1 人,靠这一条挡住了把上百个登录名刷成 `hub-lost-*`。取值 0–100,`0` = 不设下限 | +| `OA_HUB_SYNC_RECLAIM_LOST_ACCOUNTS` | `true` | **僵尸账号让位**:本地已停用、且这一趟完整清单里查无此人的同步账号,把登录名腾开(改成 `hub-lost--<原名>`),好让 Hub 的现任主人拿回账号名(见 6.1.1)。只在人数对得上的全量同步里生效,增量事件、被截断或突然缩水的清单一律不让位。关掉就退回「撞车只报数、永远不处理」 | | `OA_HUB_SYNC_SKIP_UNCHANGED` | `true` | `permission_version` 与上次一致时跳过写入(只作用于排期跑的那趟,手动同步永远强拉) | | `OA_HUB_SYNC_MEMBER_LIMIT` | `5000` | 单次导出人员上限,取值 1–5000。人比这多就调大,别靠截断结果跑同步 | | `OA_HUB_SYNC_EMAIL_DOMAIN` | 空 | 建号时按 `账号@域名` 补邮箱;Hub 的人员清单不带邮箱 | @@ -413,9 +420,25 @@ Hub 侧要先做的三件事:注册应用拿到 `code` 与密钥明文、`laun 前端只有两个页面参与: - 登录页 `frontend/src/views/auth/LoginView.vue`:`GET /api/v1/settings/public` 的 - `hub.sso_only` 为真时不再渲染账号密码表单,只留「前往统一门户」:点它,或停 4 秒之后自动 - 跳过去(跳之前先让后端写 `state`)。想留本地口令那扇门就访问 `/login?local=1`, - 自动跳转也就跟着取消 —— 应急用的内置超管不能被一次自动跳转抢在前面。 + `hub.sso_only` 为真时不再渲染账号密码表单,也**不摆一屏等人点按钮**:挂载完立刻让后端写好 + `state` 再整页跳去统一门户。这一屏从头到尾不会出现一张没人填的表单 —— 公开配置还没回来时 + 转圈配「正在确认你的统一门户身份」,人已经送出去时转圈配「正在前往统一门户」。 + 想留本地口令那扇门就访问 `/login?local=1` —— 那一档 `sso_only` 在页面上就当不成立, + 自动跳转根本不启动,应急用的内置超管不会被抢在门外。 + 只有门户连着把人原样退回来(自动跳的预算用完,见下条)才停在这一屏,把「前往统一门户」 + 那颗按钮交回给人自己点;这一屏也顺手不再去要那张用不上的验证码。 +- **无感跳转的三条护栏**(`frontend/src/utils/ssoJump.ts`,单测 `ssoJump.spec.ts`): + 1. **接住来路**:对接指南 1.4 写明门户不解析 `redirect` 之类的查询参数,绕门户一圈回来 + 地址上就没有它了。所以跳出去之前把想去的站内路径存进 `sessionStorage` + (`unisoa_sso_return`),落地页在没有 `redirect` 时取回来,取一次即清; + 后端回调带回来的 `session.redirect` 与地址栏上的 `redirect` 都排在它前面。 + 2. **数着跳**:同一浏览器标签页里 60 秒窗口内最多自动跳 2 次,第 3 次起停下让人自己点, + 免得「OA 把人送去门户 → 门户把人送回 OA → 又送去门户」来回打转;免登成功落地或人 + 自己点一次按钮都会把这份预算清零。 + 3. **只在这一档自动跳**:`sso` 档没有第二种登录方式,跳走不损失什么;`hybrid` / `local` + 还得给账号密码那扇门留位置,一律照旧停在登录页。 + 跳转本身失败(`POST /auth/sso/state` 挂了)也照样把人送出去 —— 这一趟的目的是让人出去, + 不是让人等在原地。 - 落地页 `frontend/src/views/auth/SsoCallbackView.vue`(`/sso`):认地址上那一样东西—— `?ticket=`(前端落地口径,交给 `POST /auth/sso/login`)、`#code=`(后端回调口径,交给 `POST /auth/sso/exchange`)、`?error=`(后端已经拒了,只照原因码说一句话,一次请求都不再发)—— @@ -503,7 +526,7 @@ Hub 侧要先做的三件事:注册应用拿到 `code` 与密钥明文、`laun | `users[].display_name` | `users.display_name` | 姓名,直接对齐 | | `users[].organization_id` | `users.organization_id` | 经 `oa_unit.hub_org_id` 换成部门主键;映射不到时保留原部门,不把人踢成无部门 | | `users[].mobile` | `users.mobile` | 手机号。**只有 Hub 这次确实带了号码才动这一列**:`mobile`/`phone`/`telephone`/`phone_number`/`phonenumber`/`mobile_number` 依次取第一个非空,洗成「可选 `+` 加 5~15 位数字」再写(全角转半角、去掉 `-`/`()`/空格;`010-62345678` 这种座机洗不出来)。洗不出来的人计数上报、本地值原样保留;Hub 压根没带这个字段时同样不碰本地值——这一列可能是 HR 自己录的,「没下发」绝不能被写成「清空」。同步记录里三个数分开:`mobile_returned`(清单里有多少个合法号码)、`mobile_updated`(本地刷了几条)、`mobile_invalid`(Hub 带了号码字段但不是号码) | -| `users[].wecom_userid` | `users.wecom_user_id` | 企业微信 UserID(企微工作通知的 `touser`)。**实测(2026-10-21,`member_limit=5000`):对方下发的键是 `wecom_userid`,100 人里 98 人带这一键**,5 个人的企微号和 `account` 并不相同(`chenhang → rdpnr_chenhang` 这种),是只有对方才有的信息。取字段**不赌拼写**:键名先去掉 `_`/`-`/空格再转小写比对,`wecom_userid`/`WecomUserID`/`wecomUserId`/`external_userid`/`external_id` 都算,`external_identities[]` 里 `provider` 是企微那一条的 `external_id` 也认(那里的 `user_id`/`id` 是这条映射记录或 Hub 人员主键,不收)。洗完只认企微自己那套字符集(字母、数字与 `.`/`-`/`_`/`@`,2~64 位,`0` 这种「没有」的写法不算号),洗不出来的记 `wecom_invalid`、本地原样保留。**「没号就不带键」是实测行为**:Hub 不会给一个空串,所以清空这一半按整趟清单判断——只要这趟清单里有人带过这个键,就说明这一列已下发,没带的那个人就是没企微号,本地跟着清空(`wecom_cleared`);整趟一个键都没出现过就是接口还没这一列,全员不动。企微 UserID 会被删掉再分配给另一名员工,只写不清等于把张三的待办推给拿走这个号的下一任。**增量事件不按这个口径**:实测最近 30 条 `source=wecom` 的用户事件里只有 3 条带这个键,一条补丁证明不了整个接口有没有这一列,所以补丁里没带就一律不动。一个号只认一个人:这个号已经挂在别的本地账号上就跳过并记 `wecom_conflicts`,宁可少发一条通知也不推错人 | +| `users[].wecom_userid` | `users.wecom_user_id` | 企业微信 UserID(企微工作通知的 `touser`)。**实测(2026-10-21,`member_limit=5000`):对方下发的键是 `wecom_userid`,100 人里 98 人带这一键**,5 个人的企微号和 `account` 并不相同(`chenhang → rdpnr_chenhang` 这种),是只有对方才有的信息。取字段**不赌拼写**:键名先去掉 `_`/`-`/空格再转小写比对,`wecom_userid`/`WecomUserID`/`wecomUserId`/`external_userid`/`external_id` 都算,`external_identities[]` 里 `provider` 是企微那一条的 `external_id` 也认(那里的 `user_id`/`id` 是这条映射记录或 Hub 人员主键,不收)。洗完只认企微自己那套字符集(字母、数字与 `.`/`-`/`_`/`@`,2~64 位,`0` 这种「没有」的写法不算号),洗不出来的记 `wecom_invalid`、本地原样保留。**「没号就不带键」是实测行为**:Hub 不会给一个空串,所以清空这一半按整趟清单判断——只要这趟清单里有人带过这个键,就说明这一列已下发,没带的那个人就是没企微号,本地跟着清空(`wecom_cleared`);整趟一个键都没出现过就是接口还没这一列,全员不动。企微 UserID 会被删掉再分配给另一名员工,只写不清等于把张三的待办推给拿走这个号的下一任。**增量事件不按这个口径**:实测最近 30 条 `source=wecom` 的用户事件里只有 3 条带这个键,一条补丁证明不了整个接口有没有这一列,所以补丁里没带就一律不动。**这一列照抄上游、不本地去重**:Hub 把同一个号同时发给几个人(2026-11-05 测试站实测 `user_id=1` 与 `user_id=455` 都带着 `chenhao2`),这几个人都挂着这个号,发给这个号会同时送达他们;同步只记 `wecom_conflicts` 报数,不替上游改数据。判撞号那一步**先 flush 再查库**:Session 是 `autoflush=False` 建的,同一批变更里前一条刚挂上的号还没落下去就查,会漏报。这句提示**一趟只写一次**、里面的人数按整趟累计:增量同步每条完整人员事件都要过同一套落库逻辑,提示统一放到收尾报(实测 2026-11-05 一趟变更同步把同两句提示重复写了 5 遍,数字还停在第一次的 1 人) | | `users[].status` | `users.status` | `1` → 正常;其余一律 → 已停用(Hub 只承诺「非 1 即停用/待审核」)。注意:**Hub 在 Hub 侧被停用的人不会出现在清单里**,停用实际表现为「不在清单」,走下面「不在清单里就停用」那条规则 | | `organizations[].organization_id` | `oa_unit.hub_org_id` | **组织归属的唯一依据**(唯一索引)。写上一律不清空:界面上改不动,Hub 里消失也只是停用不删除 | | `organizations[].code` | `oa_unit.code` | 组织编码。`alias` 只在新建部门时按编码起个头,之后归本地 | @@ -570,6 +593,68 @@ Hub 侧要先做的三件事:注册应用拿到 `code` 与密钥明文、`laun 只在本地主键为空时补绑,从不改写已有的 `hub_user_id`。账号改名留给定时同步做, 因为只有同步会连带把按账号存的审批引用一起搬走。 +#### 6.1.1 Hub 换了一套数据之后:账号让位与离职熔断 + +上面那条「不抢别人的账号」有一个盲区。**Hub 的变更流水只记 `upsert`、不记删除**(实测 +2026-11-04 测试站:346 条流水里 344 条来自企微同步、2 条来自 Hub,`op` 清一色 `upsert`, +而流水里出现过的 117 个账号名只剩 100 个还在目录里)。Hub 一合并人、一重导数据,账号名会 +挪到另一个 `user_id` 上,而被删掉的那个 `user_id` 本地永远不会知道。于是每一趟全量同步都 +在同一个地方撞车: + +- 活着的人(按主键命中)要把账号名改成 Hub 给的新值,可这个名字被一条**绑着已消失主键的 + 本地行**占着 → 判成「账号已属于另一个统一身份」跳过,而且下一趟、下下趟照样跳过; +- 占着名字的僵尸行则因为主键不在清单里被停用。 +- 界面上看到的就是同一个人两条:一条「正常」但登录名是上辈子别人的(`unishero` 挂着 + 潘朝钊、`zhoujin` 挂着潘远银),一条「已停用」占着正确的登录名。企业微信 UserID 同理, + 号压在僵尸行上,活人的待办一直推不到。测试库那次撞上 96 个这种死锁的改名 + 40 个企微号冲突。 + +两个口子都在 `service/hub_sync.py`: + +- **账号让位**(`_retire_lost_accounts`,`OA_HUB_SYNC_RECLAIM_LOST_ACCOUNTS`)。这一条动的 + 是别人的登录名,所以门槛叠了四层。**行本身**要同时满足:`source='hub'`、**本地已停用**、 + 这一趟**完整**清单里没有他的 `hub_user_id`、账号名不在应急名单里;**这一趟**还要 + ① 由调用方声明这是全量清单(`complete_roster=True`)、② 没被 `member_limit` 截断、 + ③ 清单人数对得上(`_roster_floor`:不少于「上一次同步记下来的人数」与「本地带 + `hub_user_id` 的账号数」里较小那个的 `OA_HUB_SYNC_ROSTER_FLOOR_PERCENT`(默认一半)。 + 实测 2026-11-05 测试站目录一天之内从 100 人掉到 1 人,少了这一条,那一趟会把 98 个登录名统统刷成 `hub-lost-*`)。让位只改账号名(`hub-lost--<原名>`):`users.id`、姓名、 + 状态、`hub_user_id` 全不动,按主键挂的权限照旧,按账号存的引用跟着这一行搬(`account_map` + 记「原名 → 让位名」,不接链)。腾开的账号名当趟就归回 Hub 的现任主人,企业微信 UserID + 也一并从僵尸行清空、当场写回 Hub 认定的现任号主。 + 要求「已停用」是有意的:这一趟刚发现查无此人时只停用,下一趟才动账号名,Hub 抖一下不至于 + 顺手把人改名。增量那条路(`_apply_user_event`)一次只搬来一个人,传默认的 + `complete_roster=False`,一个登录名都不许动 —— 否则一条企微同步事件就敢改全库的账号名。 + 改名与让位都计入该趟的 `updated`(`SyncStats.renamed_ids` + 让位人数),不然"这趟只改了 + 账号名"的同步在历史列表里会显示成「无变更」。 +- **离职停用熔断**(`_offboard_missing`,`OA_HUB_SYNC_OFFBOARD_GUARD_PERCENT`,默认 40)。 + 等着停用的人数(只数还没停用的)超过 + `max(OA_HUB_SYNC_OFFBOARD_GUARD_MIN_PEOPLE, 本地同步账号总数 × 百分比)`(默认 20 人)时,这一趟一个 + 都不停用,同步记录里报出「本该停用多少人」并把该趟标成 `partial`。判成离职不可自动挽回: + 下一趟同步只会把清单里的人重新启用,指错了 Hub 的那些人永远回不来。「清单为空就不写」 + 那道保险只管全空,挡不住「Hub 换了一套人也有一百人」。 + +「同步前体检」(`GET /api/v1/hub/preview`)与真跑共用同一套判据:会让位的账号不再算进 +`account_conflicts`,另给 `account_releases`;`offboard_pending` 是这一趟真会停用的人数, +`offboard_guard.tripped` 说明熔断会不会挡下来,`warning` 里写清怎么核对。测试 +`scripts/check_hub_sync_lost_account.py` 钉这二十三项。 + +#### 6.1.2 同步记录要能核对:三类动作成列,名单进 `details` + +一趟同步真正动过的人,以前只写在 `oa_hub_sync_run.message` 那段文本里,而那一列只留 2000 字: +测试站 2026-11-05 那趟让位 68 个账号、跟随 Hub 改名 14 人,同步历史里只看得见「更新 99 人」, +提示一多末尾还被裁掉半句,看完不知道该去核对谁。现在这三类会改到别人的动作各自成列, +名单与其余计数另存一份有界 JSON: + +| 字段 | 含义 | 为什么单独摆 | +| --- | --- | --- | +| `renamed` | 这一趟真正换掉登录名的人数 | 历史单据是按账号存的,改名前的单会从「我发起的」「我的待办」里查不到 | +| `reclaimed` | 已停用、Hub 又查无此人的账号让出登录名的个数 | 动的是别人的登录名,行本身不动 | +| `units_rebound` | Hub 换了 `organization_id` 之后按「编码 + 名称」认回原部门的个数 | 认错了就是两棵重名树,认对了才谈得上不裂树 | +| `details` | `account_renames` / `name_renames` / `reclaimed_accounts` / `rebound_units`(每类前 20 条)+ 各类**完整总数** + `counts` / `mobile` / `wecom` / `guards` + `notes`(提示按条原文) | 名单被上限裁掉时报得出「共 N 条」;`message` 裁掉后半句也不丢信息 | + +`unchanged`(界面上的「无变更」)把这三列一并算进去,只做了一次批量改名的那趟不再显示成没干活。 +名单条数上限 `DETAIL_ITEM_LIMIT` 只防一条 JSON 装下上千个名字,计数不受它影响;增量轮询每几十秒 +就记一行,所以这里只放小字段,不塞清单本身。测试 `scripts/check_hub_sync_details.py`。 + ### 6.2 Hub 管骨架,本地管扩展 组织同样是全量同步,但接管范围划得很清楚: @@ -589,6 +674,25 @@ Hub 侧要先做的三件事:注册应用拿到 `code` 与密钥明文、`laun 本地只用了这一次,就认成同一个部门(补写 `hub_org_id`),部门主键与它身上的流程权限 原样保留;编码撞车就不猜,按新部门建并记进同步记录。这一条由系统设置「组织人员同步」组里的 「按编码认领本地部门」(`OA_HUB_SYNC_BIND_LOCAL_BY_CODE`)控制。 +- **Hub 把 `organization_id` 整体换了号**(重导数据、合并组织,实测测试站 2026-11-04: + 25~36 变成 2~13):本地只按主键认部门,认不出来就会把整棵树再建一遍,界面上出现两个 + 「紫光汇智」,人搬去新行,而按 `oa_unit.id` 配的数据范围与审批规则留在老行上悄悄失效。 + 所以开了「按编码认领本地部门」时,**编码与名称都对得上、而原主键已经不在这趟清单里**的 + 老部门会被认回来(换新主键,本地 `oa_unit.id` 不动,子树与挂在这身上的配置都留在原地)。 + 编码或名称对不上就不认(不靠单一字段硬猜);这个编码名称已经被在职部门占了也不认 + (那已经是上一次换号留下的重复,再认就出第三个);同名同编码的壳子有好几具时看谁底下 + 还挂着人,只有一支住人就认那一支(口径同解绑撞车主键时的「留人多的那支」),分不出来就 + 不猜、按新部门建并写进同步记录。 + 已经裂开的树不会自己合上,`GET /api/v1/hub/preview` 用 `organizations.zombie_units` + 把壳子数量与样例报出来并写进 `warning`。以前只能一具一具「先解绑再删除」,现在 + `GET /api/v1/org/units/shells` 列出这些壳子并逐条说明删不掉的原因, + `POST /api/v1/org/units/shells/cleanup` 一键清掉删得掉的那几具(判据见 `find_shell_units`, + 删除前逐条重算,不认前端传来的旧名单)。验收见 `scripts/check_hub_sync_unit_reclaim.py`(21 项) + 与 `scripts/check_hub_sync_shell_units.py`(21 项)。 +- 一趟要停用的部门超过 `max(OA_HUB_SYNC_UNIT_OFFBOARD_GUARD_MIN, 同步部门总数 × OA_HUB_SYNC_OFFBOARD_GUARD_PERCENT)` 时 + **一个都不停**,只报数并把该趟标成 `partial`(`units_offboard_guarded`)。停一个部门等于 + 把它下面所有人的数据范围与按部门配的审批规则一起摘掉,错一批比少停几个代价大得多; + 底线默认 5 而不是人员那侧的 20,因为部门总数本来就比人少一个量级。 - 编码对不上又确实是同一个部门,用 `POST /org/units/{id}/hub-binding` 手工绑定 (一个 Hub 组织只能对一个部门),反过来 `DELETE` 同一个地址解绑。解绑是唯一会清空 `hub_org_id` 的入口,解绑后这个部门改由本地维护,Hub 那边那个组织会被当成没同步过的 @@ -748,7 +852,13 @@ id 路径(`/1/8/10/` 或 `1/8/10`,取末段按 `hub_org_id` 精确匹配, 或后端重启后 `running` 已是假、但最近那条记录还停在 `running`),页头与执行记录共用,免得两边口径不一。 - 接口:`POST /api/v1/hub/sync`(`org:person`)。跟定时任务同一条代码路径,只是 `trigger=manual`,因此**不受 `OA_HUB_SYNC_SKIP_UNCHANGED` 影响**,点了就真拉。 -- 并发保护:同一进程里同时只允许一个同步,重复点击回 `已有同步任务正在执行`。 +- 并发保护:同一进程里同时只允许一个同步,重复点击回 `已有同步任务正在执行`;跨副本那把 Redis 锁 + 挡下来时说的是另一句 `另一个副本(主机名:进程号)正在跑同步`。两句说的是不同的锁,报障时先分清是哪 + 一句。增量同步与手动全量共用同一把锁,所以后台每几十秒那趟撞上手动点击是正常现象,等几秒即可。 + **拿锁之后、进收尾 `try` 之前那一段(写游标 + 建「进行中」记录)自己负责交还锁**:这段漏出异常 + (库断、表结构落后报 `Unknown column`)会把本进程那把锁永久握着,症状就是"明明没同步、点立即同步 + 一直回已有同步任务正在执行",且历史里一条记录都没有。验收见 + `backend/scripts/check_hub_sync_lock_leak.py`。 - **「进行中」有两种卡法,各有各的出口**。一种是没人收尾的残留:后端被 kill、容器被驱逐时, `oa_hub_sync_run` 里那条 `status=running` 再也没人改它,同步历史一直显示「进行中」,页头那颗 按钮也跟着一直按住。`hub_sync.reap_stale_runs` 在后端启动时与 `GET /hub/status` 里各清一次, @@ -931,7 +1041,9 @@ Hub 的权限码与数据范围真的参与判定。两条硬保险: | `POST /api/v1/hub/changes/sync` | `org:person` | 手动拉一次变更流水,与定时跑同一条逻辑(见 8.1) | | `POST /api/v1/hub/sync` | `org:person` | 一键同步 | | `POST /api/v1/hub/sync/cancel` | `org:person` | 终止这趟同步:给真在跑的那一趟发停手信号(有就叫 `stopping=true`),把没人收尾的「进行中」记录标成「已终止」、强制放行同步锁,返回收尾了几条与两把锁的情况(见 8) | -| `GET /api/v1/hub/sync/runs` | `org:person` | 最近 N 次同步记录 | +| `GET /api/v1/hub/sync/runs` | `org:person` | 最近 N 次同步记录:除各类计数外还回 `renamed` / `reclaimed` / `units_rebound` 与 `details`(改名与让位的名单、熔断挡住了多少、按条原文的提示,见 6.1.2) | +| `GET /api/v1/org/units/shells` | `org:unit` | 列出 Hub 换过主键之后留下的空壳部门,逐条给出删不掉的原因(挂着人 / 有下级 / 被权限角色当数据范围)(见 6.2) | +| `POST /api/v1/org/units/shells/cleanup` | `org:unit` | 一键清理这些壳子:`{"ids": [], "dryRun": false}`,ids 留空 = 清掉全部符合条件的;删除前逐条重算判据,`dryRun` 一行都不动,真删时写一条操作日志(`org_unit_shell_cleanup`) | | `GET /api/v1/hub/directory/preview` | `org:person` | **只读体检**:拉一次全量做对比,给出本地会新增/认领/停用多少,不写库、不记同步记录 | | `POST /api/v1/hub/probe` | `system:setting` | 连通性自检:全量目录接口(用目录密钥拉一次)+ 密钥/同步凭证 + 登录验证码逐项体检;带 `{"values": {...}}` 就按这份**还没保存的草稿**测,不落库 | | `GET /api/v1/hub/config` | `system:setting` | 统一身份配置页数据源:生效值 `values`、每一项的完整元数据 `items`(含 `env` 名、范围、来源、`env_locked`)、中文名 `labels`、说明 `hints`、来源 `sources`、被环境变量钉住的 `env_locks`、密钥只给 `secret_set` 布尔,另有 `config_file` 指向库里那一行 | @@ -945,7 +1057,26 @@ Hub 的权限码与数据范围真的参与判定。两条硬保险: | `POST /api/v1/config/reload` | `system:setting` | 丢掉进程内取值快照立刻重读,多实例部署时想立刻对齐可以用它 | 「立即同步」按钮旁就是「同步前体检」与「拉取变更」:正式同步前先看规模和差异,尤其是 -`member_limit` 是否会把人员清单截断(`truncated=true` 时体检会把警告原样报出来)。 +`member_limit` 是否会把人员清单截断(`truncated=true` 时体检会把警告原样报出来)。体检对话框 +把**会动到什么**直接摆成数字格子:这趟真停用多少人/多少个部门(`offboard_pending`,被熔断 +挡下就是 0)、熔断线在哪(`offboard_guard`,写清百分比与"不少于 N"那条底线一起算出来的上限)、 +会有几个登录名跟着改名(`account_renames`)、几个僵尸账号让位(`account_releases`)、 +几个登录名撞车(`account_conflicts`)、几个重名壳子部门(`zombie_units`,点名到名字)。 +`account_releases_allowed=false` 时对话框里会说明为什么这趟一个登录名都不动。壳子那几具 +旁边直接给「清理 N 个空壳部门」:后端没回 `zombie_units_deletable`、或每一具都还挂着删不掉的 +原因(`zombie_unit_samples[].blockers`)时不摆这颗按钮 —— 不拿全部壳子去赌删除安全。删完当场重新体检。 + +「同步定时任务」页在排期与增量之外多了一段**同步落库口径**:同步部门、带上已停用的组织、 +按编码认领本地部门、离职停用、离职停用熔断(%)与它的**人数底线**、部门停用的**个数底线**、 +让已查无此人的账号腾出登录名、让位名单的**清单人数下限(%)**、版本没变就跳过、 +保护本地自建的管理员、单次导出人员上限、建号补全域名、统一身份的管理员账号。 +三条底线以前是代码里的常量(20 / 5 / 50%),几十人的团队和上千人的部署被同一条线拦着, +想调只能改代码发版;现在跟百分比一样是配置项,取值与出厂默认值是否走偏由 +`scripts/check_hub_sync_details.py` 钉住。这些配置项本来就在 +`PUT /api/v1/config/{组}` 里能改,只是界面上看不见——清过库或换过站点的人不知道自己站在 +"会停人、会改登录名"这一档上,下一趟全量就把人停掉了。标签与说明取自 `dbconfig`, +保存时按每一项自己所属的组分别提交(`hub_sync_include_disabled_units` 挂在 `hub` 组下, +混进 `hub_sync` 那一批会被后端按"不认识的配置项"整批打回)。 `GET /hub/status` 里的 `breaker` 是熔断与在飞闸门现在的样子:`cooling` / `secondsLeft` (是不是还在冷却、还剩几秒)、`inflight`(此刻几条线程卡在等 Hub)、`blockedTotal` / @@ -999,8 +1130,8 @@ Hub 的权限码与数据范围真的参与判定。两条硬保险: | 本地超管登录不上 | 内置超管不需要出现在「应急账号」名单里也能走本地口令,先确认登录用的账号名是不是库里 `system.admin_account` 记着的那个(改过名就用新名字),再确认口令 | | Hub 的 `admin` 同步不进来 / 认领不上 | 本地有个同名的内置超管挡着(应急通道 + 保护本地管理员两道护栏)。按 5.1 把内置超管改名成 `localadmin`,`admin` 就让出来了;同步记录里那句「跟本地应急账号同名」就是这个意思 | | 界面上存了配置像没生效 | 先看该项的来源标记:`env` = 被环境变量钉住了(界面上是灰的),`file` = 值传过 `null` 改回了出厂值,`database` 才是界面上存的那份。再看 `GET /hub/status` 的 `forced_off`(应急总闸开着时界面值一律让位,`forced_off_locked` 说明它是不是被环境变量钉住的) | -| Hub 挂在网关后面 / 换了路径前缀 | 登录那九个接口路径都是配置项:在「统一身份登录」里改「接口路径:xxx」保存即可(或改 `config.toml` 的 `[hub.api]` 再重启),不用改代码;权限那九条同理,见 §4 第二张路径表 | -| 自检里接口路径看着不对 | `GET /hub/status` 的 `api_paths` 是当前真正在用的登录九条路径,权限那九条在 `GET /hub/permissions/status` 的 `config.api_paths`;步骤名里也带着路径,对照一下就知道是站点地址错了还是路径错了 | +| Hub 挂在网关后面 / 换了路径前缀 | 登录那十个接口路径都是配置项:在「统一身份登录」里改「接口路径:xxx」保存即可(或改 `config.toml` 的 `[hub.api]` 再重启),不用改代码;权限那九条同理,见 §4 第二张路径表 | +| 自检里接口路径看着不对 | `GET /hub/status` 的 `api_paths` 是当前真正在用的登录十条路径,权限那九条在 `GET /hub/permissions/status` 的 `config.api_paths`;步骤名里也带着路径,对照一下就知道是站点地址错了还是路径错了 | | 改了 `config.toml` 没反应 | 出厂值只在启动时读一次,要重启;而且这一项如果在界面上保存过,库里那份一直压着它 —— 想听文件的先在界面上点「改回出厂值」 | | 另一台实例没跟上 | 每个进程各自缓存,最多 `OA_CONFIG_CACHE_SECONDS` 秒(默认 2)后自己跟上;要立刻对齐就 `POST /api/v1/config/reload` | | 保存完谁都登不进来 | 内置超管走本地口令进得来,在「系统设置 → 统一身份应急总闸」把开关打开保存,登录立刻回本地;连界面都进不去时才在服务器上设 `OA_HUB_DISABLED=true` 重启(效果一样,但界面上的开关会被它钉成灰的)。`OA_HUB_LOCAL_ACCOUNTS` 里的账号本来就不受影响 | @@ -1039,9 +1170,13 @@ Hub 的权限码与数据范围真的参与判定。两条硬保险: ## 13. 验收 > **先说一句现状**:下面这几条挂在 `backend/tests/` 上,那个目录已经不在了(2026-10 清掉的), -> 所以这一节目前**跑不起来**,留着是说明这一层原本验到哪。眼下真能跑的替身只有两条: -> `python3 scripts/check_hub_breaker.py`(熔断与在飞闸门,见 §14,不连库不碰真 Hub) +> 所以这一节目前**跑不起来**,留着是说明这一层原本验到哪。眼下真能跑的替身只有这几条: +> `python3 scripts/check_hub_breaker.py`(熔断与在飞闸门,见 §14,不连库不碰真 Hub)、 +> `python3 scripts/check_notify_hub.py`(企业微信推送那一层,见 §15,进程内起一台假 Hub, +> 预算、幂等键、逐人原因分档、请求级错误全在里面) > 与 `python3 scripts/check_binding.py`(取数与候选来源那套校验口径)。 +> 推送这一路还多一条连着开发库跑接口那一层的:`python3 scripts/check_notify_hub_api.py` +> (真 `TestClient` + 假 Hub,验 `notify/meta`、渠道保存校验、测试发送带深链、回查与补发)。 > 桩服务那一整套(登录、免登、回调、权限对接、配置分层)要恢复得先把测试脚手架补回来。 一条命令拉起 Hub 桩服务 + 一套临时库上的后端,跑完自己收干净(会自建自删 @@ -1076,7 +1211,7 @@ Hub 把票据校验接口按 401/403/404 拒掉时(密钥不对、应用没启 组织 `status`/`parent_id` 事件回全量、`source=hub` 与 `source=wecom` 两种键名、 删除事件软删、拉取失败退避与手动 `POST /hub/changes/sync`);一键同步的建部门/`code`+`status` 落列/认领同名账号/停用/ 下线不删行/Hub 删掉的部门被停用而本地自建部门不动/本地超管不受影响/截断时只写不撤; -九个接口路径全部来自配置:另起一台把接口挂在 `/gw/sso/*` 上的 Hub 桩,只靠配置文件的实例 +接口路径全部来自配置:另起一台把接口挂在 `/gw/sso/*` 上的 Hub 桩,只靠配置文件的实例 照样能登录与同步,把站点地址改回默认那套桩(路径不变)自检必须报打不到,再把路径改回 默认值立刻恢复,全程不重启;`GET /hub/status` 的 `api_paths` 如实回显,改过的路径来源 标成 `database`;目录密钥单独立一组用例:另起一台"目录接口必须带 `X-Directory-Key`"的桩 @@ -1138,3 +1273,189 @@ p95 也从 10 秒涨到 20 秒(排在别人后面,等于等了两轮超时 把「第一次照等、之后立刻回错、每 2 秒放一个探测、自检绕开、恢复即清零、被拒不算失联、 并发第一波最多陪葬 N 条线程、Hub 正常时并发全过、填 0 整层关掉」九条逐一验过, 不连库也不碰真 Hub,随时能跑。 + +## 15. 企业微信消息推送(Hub 代发) + +对接文档 9.6 那一套。本系统只负责说清"这句话该对谁说、点开该落到哪一页", +Hub 负责把它换成企业微信的应用消息投出去、认出点卡片的人、再签一张一次性票据把人送回来。 +**本系统不持有企业微信密钥,不实现企业微信授权,也不接触 `code` 与 `access_token`**, +与「企业微信只对接 Hub,下游不需要企微凭证」这条边界(`third-party-integration.md` §7)一致。 + +### 15.1 三件事各自落在哪 + +| 对接文档要求的事 | 本系统的落点 | +| --- | --- | +| 发通知时调一次 HTTP | 「消息通知 → 企业微信(经统一身份 Hub 推送)」渠道(`hub_wecom`)。写通知的入口还是 `engine.notify()`,入队与站内信同一事务,真发在后台调度线程里:`service/channels.py::_hub_send` → `POST {hub_base_url}{hub_path_notify_wecom}`,请求头 `X-Integration-Key` | +| 在**已有的**免登落地端点里读 `redirect` 并跳一下 | 不用新增端点:`GET /api/v1/auth/sso/callback`(别名 `/sso/hub`)本来就接 `redirect`,只放行站内路径(`sso_handoff.safe_path`),验完票发一次性短码 302 回 `/sso#code=…`,前端换会话后照 `redirect` 落页。推送链路与门户免登只差这一个参数,`state` 为空是正常的(见 5.2) | +| 保存 Hub 回传的逐人投递结果,留作自己的重试队列 | `oa_notify_delivery` **每个收件人一行**,本身就是退避重试队列(60s / 5min / 30min,用满进死信);Hub 那份逐人明细原样存在 `response.hub` 里,界面上看得见原因、企微号与那条永久链接;「回查送达」按钮走 `POST /notify/deliveries/{id}/recheck` → `GET {hub}{path}/{msg_key}`(9.6.7,只读、可反复点) | + +### 15.2 渠道要配的东西少到只有四格 + +站点地址与应用密钥**不在渠道上**,跟着「系统设置 → 统一身份」走,与免登换票、目录导出 +共用同一把(`hub_integration_key`)——一把密钥冒充不了另一个系统发消息。渠道上只有: + +| 配置 | 默认 | 说明 | +| --- | --- | --- | +| `msgtype` | `textcard` | `textcard` 是卡片 + 可点链接,`markdown` 是纯文字提醒。没有单据可指的事件(会议提醒)会自动退成 `markdown`,免得发一张点开没反应的卡片 | +| `with_link` | `true` | 关掉就是纯提醒:不带 `target_path`,Hub 那边不生成链接、也不占用深链 | +| `title_limit` | `64` | 留给自己的标题额度。Hub 会在标题前强制加 `【应用名称】`,两边合计 ≤128 字符,**超长是 400 整条被拒**(不是替你截断)。本系统不知道自己在 Hub 上叫什么,所以默认只敢用一半 | +| `receiver` | `["user_id","account"]` | **按哪一列认人**,顺序即优先级,见 15.3。Hub 只认 `user_id`(本地 `users.hub_user_id`)与 `account`(本地 `users.account`)两种标识,写第三种保存时就挡下 | + +`markdown` 有一个只能靠人记住的脾气:**它在企业微信微工作台里不展示**(对接文档 9.6.9 +自查清单那一条)。会话里照样收得到,但人想"事后翻出来再看一眼"时在工作台里找不到它。 +所以要留痕、能回看的(办结、超时、待办)用 `textcard`,只图一眼可见的瞬时提醒才换 +`markdown`——这一条本系统查不了,也没法替谁兜住。 + +事件订阅(待办 / 催办 / 阅件 / 办结 / 超时 / 会议)与其它渠道同一套勾选,收件人也不单独配: +**站内信发给谁,这一路就发给谁**。 + +### 15.3 收件人:按哪一列认人是渠道上可配的一项 + +**发给谁**不用配:站内信发给谁这一路就发给谁(`engine.notify()` 传的那串人员引用就是 +登录账号,口径见 `service/personref.py`)。要配的只有**用哪一列向 Hub 要到这个人**—— +渠道上 `config.receiver` 那根数组,顺序即优先级: + +| 取值 | 本地列 | 脾气 | +| --- | --- | --- | +| `user_id` | `users.hub_user_id`(目录接口的 `entity_id`) | Hub 的人员主键。账号能被别人注册走、姓名会改、登录名也会在 Hub 侧改,只有它从头到尾指向同一个人,所以默认押它 | +| `account` | `users.account` | 区分大小写的精确匹配,2026-10-20 起还会随企业微信「Hub账号」扩展属性被同步改写(9.5),押它迟早对不上;但主键没同步过来的环境只有这一条路 | + +界面上给四档(`channels.HUB_RECEIVER_PRESETS`):`Hub 用户 ID 优先`(默认, +`["user_id","account"]`)、`登录账号优先`、`只认 Hub 用户 ID`、`只认登录账号`。 +**只勾一种就不退回另一种**——那是管理员明确说过"只按这一列发",宁可把这个人跳过并在 +投递记录里写明"按渠道配的收件人标识(…)取不到值",也别悄悄换成另一列把消息送错人。 +认不出的取值保存时就 400 挡下(写错一个字母的代价本来是"这个人静默收不到")。 + +**要加一种标识只需三行**:`HUB_RECEIVER_FIELDS`(名字与本地列)、`HUB_RECEIVER_VALUES` +(怎么取值)、`HUB_RECEIVER_SQL`(覆盖数怎么统计)。渠道配置、入队、发送、回查、 +界面清单都跟着认它,Hub 那边多认一种标识时不用改别的。 + +落库与排查跟着这一档走: + +* `oa_notify_delivery.target_field` 记 `target` 那一串是按哪一列取的(`user_id` / + `account`,其它渠道留空)。一串 `10086` 分不清是 Hub 主键还是某个人的登录名,而这两件事 + 的排查方向完全不同;升级前的老记录这一列为空,读的一路按值猜(纯数字只可能是主键), + 口径与改造前一字不差。 +* **发送这一刻重认一次**(`hub_target_for`):入队之后又跑了一趟组织人员同步、或者管理员 + 刚把这一档换掉,排队里的记录就按新的口径发;发出去后把真正用的那一对标识写回记录, + 「回查送达」才有得对(它拿 `target` 去比 Hub 回显的 `receiver`)。人查不到(账号被删) + 才回落到记录里那一对。 +* 渠道列表带一份 `hubCoverage`:在职账号里每一种标识各能覆盖多少人、几种都试一遍能发到 + 多少人、**怎么配都发不到的有几个**。换档之前先在编辑框里看见这几个数,比投出一堆 + `skipped` 再回头查便宜。 + +### 15.4 `msg_key`:跨重试不变,人工补发才换世代 + +`msg_key = oa-<渠道编码>-<投递记录 id>`。投递记录的 id 天生满足文档 9.6.4 那句话—— +超时、进程重启、退避重发,键都不变,Hub 三选一(已投过回缓存 / 整批没投过重发 / +还在发回 409),本系统不需要判断"到底投没投出去"再决定换不换键。 + +只有一种情况要换:**已经投出去过的那一条被人工重发**。同键只会命中 Hub 的幂等缓存, +一个人也不会多收到,但界面会显示"已重发",运维以为发了其实没发。所以 `resend()` 检测到 +`response.hub.status` 是 `sent` / `partial` 时把世代号加一,键变成 `…-r2`、`…-r3`。 + +### 15.5 逐人结果分档:Hub 的 `reason` → 本系统的状态 + +HTTP 200 + `code=="200"` 只代表 Hub 听懂了,**收到没有看 `recipients[].status`**。 +一个人失败不带走同批其他人,而每条记录只有一个收件人,所以 Hub 的整体 `status` 在这里 +不会见到 `partial`(真见到也按这个人自己那条算)。 + +| Hub 的 `reason` | 落成 | 为什么 | +| --- | --- | --- | +| `rate_limited`、`api_error`、表外的未知原因 | `failed`(按退避同键重发) | 稍后再试有可能成,宁可多试三轮 | +| `user_not_found`、`user_disabled`、`wecom_not_bound`、`wecom_rejected`、`unlicensed` | `skipped` | **这个人现在收不到,但不是故障**:没认领、没绑企微、不在可见范围、缺许可。和"这个账号没有邮箱"是同一档,与失败分开统计,补完就地重发 | +| `invalid_message`、`quota_exceeded`、`daily_limit_exceeded` | `dead` | 重试一百次也不会成:正文/链接太长、当日配额用尽(次日重发)、这个人今天收满了 | +| 请求级 `401` / `403` / `400` | `dead` | 密钥不对、开关没开、参数不合法,改完才谈得上重发(`400` 说"应用未登记首页地址"时文案会点名 `home_url`) | +| 请求级 `409` / `500` / `503`、连不上 | `failed` | 409 是并发保护、5xx 与网络是 Hub 的事,同键稍后重发是安全的 | + +限流类原因是 Hub 在调企业微信**之前**拦下的(企业微信对超频消息静默丢弃不报错), +所以这些人是真没收到,同键整体重发不会让他们收到两条。 + +失败原因后面还会附一句企业微信自己说的话(`wecom_errcode` / `wecom_errmsg`),只在失败时 +附一次。逐人 `reason` 说的是"哪一类",企微那句才是"具体哪一处"——真环境撞到的 +`81013 user & party & tag all invalid` 就是这个人不在应用可见范围(或成员已离职), +拿那个码去企微 devtool 一查到底,比照着"通常是可见范围问题"猜快。 + +### 15.6 深链:只发相对路径,域名由 Hub 现拼 + +`target_path` 发的是站内相对路径:待办 / 催办 / 超时发 `/todo/`(审批人自己的 +页面,点开就能同意/退回),其余发 `/work/`,没有单据就不带。**绝不拼 +`site_front_url`**:Hub 按本系统登记的 `home_url` 在点击时刻现拼绝对地址(9.6.6), +本系统写死域名等于把域名焊进一条永久有效的链接里,以后换域名历史消息全成死链。 + +`/todo/` 还多一道按人的闸:`engine.notify()` 对整批收件人只传一个 `task=`, +而那是**个人页面**,所以一人一条入队时 (`channels.hub_task_links`) 会核一下这条待办 +到底是不是这个人的——不是(例如"外部审批那一环超时"同时知会兜底管理员,或那条待办 +已经被办掉了)就把 task 抹掉,深链退回 `/work/`。少这一道,管理员点开的是 +"不是我的那条待办":审批页只读、按钮全灰。 + +链接本身不是凭据,是"应用 + 深链"的路由:同一张单据推十次用的是同一条链接,每次点击 +现签一次性票据。转给同事点开是同事自己的身份,本系统的权限判定照旧——Hub 不管这个人 +能不能看这条单据。 + +**Hub 拼不出深链时不丢消息**:本应用没登记 `home_url`(15.7)时,带 `target_path` 的 +请求是请求级 `400`、整批一个人都不投。`_hub_send` 认出这一种就摘掉深链、换成 +`msg_key` 的 `-nolink` 变体再发一次纯文字提醒(文档 9.6.2:`target_path` 留空就是 +不带链接的提醒),记录里留 `hub.degraded=hub_no_home`,投递列表那格直接说人话。 +管理员补上 `home_url` 之后新消息自动带回深链,不用重推历史。认不出来的 `400` +(标题超长那类)照旧判死、照旧只打一次——降级只多花一次调用,不会把一条真错的消息 +反复重投。`markdown` 在微工作台不展示(15.2),所以降级这一条是"知道有单子"而不是 +"事后还能翻到",`home_url` 该补还是得补。 + +Hub 用 Go 写时间,`sent_at` 没赋值时回的是零值 `0001-01-01T00:00:00Z` 而不是缺字段, +`channels.hub_time()` 一律当没填:投递记录里那句"发送于 0001-01-01"是假时间, +本系统自己那列 `sent_at` 用的是本地投递时刻。 + +### 15.7 Hub 侧的前提(本系统查不了,只能对着看) + +`GET /api/v1/notify/meta` 会回 `hub.ready` / `hub.missing`,渠道页顶部就照着说; +下面这几条在 Hub 侧,任一没做,Hub 直接拒(投递记录里能看见原话): + +- 全局推送开关 + 本应用 `notify_enabled` 都开通(关一个就是 `403`;`PUT` 是整体覆盖, + 编辑应用时漏传等于关掉); +- `home_url` 已登记且**不是站点根级文件**(`https://oa.example.com/index.html` 这种 + 会让深链拼成 `/index.html/todo/xxx`,点开必打不开); +- `launch_url` 指向 `/api/v1/auth/sso/callback`(或别名 `/sso/hub`); +- 企业可信 IP 放行了 Hub 出口 IP、可信域名 = Hub 站点 origin 且不带端口、 + 应用可见范围覆盖全部收件人、成员基础接口许可齐(缺一类就是某几个人逐人失败); +- 上线前请 Hub 管理员用「应用接入 → 企业微信推送 → 发送测试消息」验一遍: + 那是唯一不依赖本系统就能验通上面四类前提的手段。 + +### 15.8 排障与验收 + +`python3 scripts/check_notify_hub.py`(不连库、不碰真 Hub,进程内一台假 Hub)钉住: +收件人优先 Hub 主键、幂等键跨重试稳定而人工补发换世代、深链是站内相对路径、 +待办深链只发给这条待办的持有人(同批旁人落 `/work/`)、 +标题/正文/markdown 字节三档预算、逐人原因分档、请求级 401/403/400 判死与 409/5xx 退避、 +`duplicate` 算成功、回查按 `receiver` 回显对齐到人、入队一人一条、 +以及免登落地那一半只认站内 `redirect`。 + +接口那一层由 `python3 scripts/check_notify_hub_api.py` 钉(连开发库 + 真 `TestClient`, +把 Hub 指到进程内那台假 Hub,自建的数据用完删掉):`notify/meta` 报得清底细、 +保存时校验消息形态与标题额度、换种类不留上一档的 `url`/`secret`、测试发送真发给本人 +且带 `/todo` 深链、回查打的是 `GET {推送路径}/{msg_key}`、非 Hub 记录回查给 400。 + +点开那一跳的落地侧由 `python3 scripts/check_notify_landing.py` 钉(真路由 + 假 Hub 的 +`POST /tickets/verify`):`/sso/hub?ticket=…&redirect=/todo/…` 验完票 302 回 +`/sso#code=…` 且票据原值不出现在地址里、验票只问一次不带 `app_code` 用的是免登那把密钥、 +短码只能用第二次就废、`redirect` 一路带到前端且只认站内路径(`//evil.example.com` 当没填)、 +不带 `redirect` 照样换得到会话、`active:false` 与应用串号各回一个稳定原因码。 +它顺带钉住一条给运维的提醒:**推送链路的票据天生不带 `state`(9.6.5)**,所以「免登必须 +校验 state」打开成强制档时,从企业微信点卡片这一跳会被 `SSO_STATE_REJECTED` 挡在门外。 + +最后半米(会话换到手之后人站在哪一页)由 `frontend/src/views/auth/SsoCallbackView.landing.spec.ts` +钉:`#code=…` 与 `?ticket=…&redirect=…` 两种落地形态都要把人直接送到那条待办或那张单 +面前;`redirect` 写成 `//evil.example.com` 时一律不进,落回系统自己的第一屏;后端拒票 +那一屏只说一句话、一次登录请求都不许多发(开了强制 `state` 校验时企微点开就是这个样子)。 + +**401 有两种,别一上来就换密钥**。Hub 自己答的 401 是带信封的 +`401 {"code":"401001","message":"集成密钥无效"}` —— 那才是密钥不对;而它前面的网关对 +**这条路径压根没注册**(Hub 版本没上 §9.6、或网关没放行)回的是一句裸 +`401 {"error":"unauthorized"}`,跟乱敲一个不存在的地址回的报文一模一样。分辨的办法不用猜: +拿同一把密钥敲一个肯定存在的路径(`POST {hub}/api/v1/auth/tickets/verify`),它回 +`401001` 说明密钥没问题、推送那条是路不通;它连这个都回裸 `error`,才轮到怀疑密钥与站点。 +投递记录里这两种的话分开写着,裸 `error` 那一档会把推送路径一起念出来。 + +真机验收清单(企微里点一次就知道):卡片点开不出现登录页 → 一屏「正在打开 …」→ +落到该单的审批页;点开别人的单据能看不能批;`redirect` 被改成 `//evil.example.com` +时落默认页不出站;落地页刷新不会把用户卡在 `ticket_invalid`(票据只能用一次)。 diff --git a/docs/mobile-approval-layout.md b/docs/mobile-approval-layout.md index 826e7e0..74d25e6 100644 --- a/docs/mobile-approval-layout.md +++ b/docs/mobile-approval-layout.md @@ -24,7 +24,8 @@ 现在的结构下,桌面每补一条判据,这一页自动跟着。 代价只有一处,写在桌面上:`submit` / `confirmGoBack` / `confirmPeople` / `confirmDecision` -多收一个可选的 `done` 回调。桌面不传,办完仍按老路子跳「已办」;手机版传的是「跳下一条待办」。 +多收一个可选的 `done` 回调。桌面不传,办完仍按老路子跳「已办」;手机版传的是「关掉这一张,回待办列表」 +(加签例外:单子还在自己手里,那一档就地 `reload` 一次,不把人送走)。 ## 1. 三档判定,各管各的 @@ -112,8 +113,10 @@ | 字段 | 手机上怎么摆 | | --- | --- | | 空值 | 不渲染,也不给占一行 | -| money | 最多两条上浮到抬头,先让人看到钱 | +| money / number | 最多两条金额上浮到抬头,先让人看到钱;写法全按格子上配的格式走(`formatNumber`),金额没配单位也补一个「元」 | | auto(系统取数) | 合并成一行折叠起来——发起人是谁、哪个部门,抬头已经有了 | +| dept(部门) | 只念部门名,也就是组织路径的末段(`紫光汇智\软件开发事业部` → `软件开发事业部`),与桌面只读态同一个口径 | +| week / months / location | 星期几念「周一、周三」、多月念「2026年10-11月」、定位念「地址(经度, 纬度)」,读的都是桌面只读态那三份(`utils/formRuntime`),手机上不再看到 `1-7`、`['2026-10']` 这类库里的码 | | table(明细) | 收成一行「明细 12 条 · 合计 7,181.00」,点开才是逐条 | | attachment / image | 缩略图横滑,不占字段行 | | tabs(标签页) | 那一页的名字就是分节标题;外部页面那一页整节换成一张「打开」卡片 | @@ -123,11 +126,34 @@ 明细点开是一条两行:第一行「第几条 · 花在什么上 · 多少钱」,第二行日子与备注。日期不当标题, 扫明细的人是先看这笔钱花在什么上的。四列摊成一条四行的话十二行就是两屏半,划完手都酸了。 +**部门那一格念的是部门名,不是整条组织路径。**库里存的是路径(`紫光汇智\软件开发事业部`), +桌面上这一格取的是部门下拉候选项的 label,那本来就是末段那个名字(`utils/deptOptions`); +手机上从前把这一格和选人格子共用一套读法,于是部门路径被当人员引用报给 `/org/persons/label`, +后端对认不出的字符串照字面给个名字(`app/service/org.py:_ref_missing`),前端再拼成 +`姓名(账号)`——手机上念出来是「紫光汇智\软件开发事业部(紫光汇智\软件开发事业部)」, +同一条路径摊三行,还把要看的那 7 个字挤到第二行。现在 `fieldText` 里 `dept` 单独一条口径 +(`deptText`:取路径末段,物件取名字,尾部那个反斜杠不算一层),摘要与「完整单据」两屏一起修好。 + +顺带把同一家族的另外几类补齐了,原则只有一条:**手机上念一句人话的那份口径,与桌面只读态是同一份**。 + +| 那一格 | 从前在手机上 | 现在 | +| --- | --- | --- | +| `week`(星期几,库里 1-7) | 落到最后的兜底那句 → **念出来是空的** | 「周一、周三」(`formRuntime.weekText`,已从桌面控件提到这一层,两边共用) | +| `months`(多选月份) | 同上,空的 | 「2026年10-11月」(`monthsText`) | +| `location`(定位) | 同上,空的 | 「地址(经度, 纬度)」(`locationText`) | +| `money` / `number` | 自己按两位小数写,单位只在配了才写:电脑「12.00 元」、手机「12.00」 | 读 `formatNumber`(千分位 / 小数位 / 货币全按格子上的配置),单位口径照桌面那句——金额没配单位也补「元」 | +| 明细里的金额列 | 库里那个 `1129` 原样摊出来 | 按那一列配的格式写「1,129.00」,合计同理 | +| `daterange` / `timerange` | 自己拼 ` ~ `(碰巧一样) | 直接读 `rangeText`,不再各拼一遍 | + **分节先认页签,再认分隔条**。原先这一层只认 `divider`,而生产上那张费用报销单是靠一张 「标签页」分两页的(`tabsMode: collapse`),于是三十几格全挤进一节「表单内容」, 段名一个字都不见——配表的人分好的两页,手机上等于没分。现在读的是同一份 `utils/tabPages`(`tabsFieldOf` / `tabsOf` / `tabKeyOf` / `isEmbedTab`),与桌面、与后端一字不差, -只是把「哪一页」搬到段名上:**页签在前、分隔条在后**,两者都没有才回落 `表单内容`。 +只是把「哪一页」搬到段名上:**页签在前、分隔条在后**,两者都没有才回落 `表单内容`。回落出来的那三个字标在 +`PlanGroup.generic` / `ReaderSection.generic` 上,**整屏只有这一节的时候连标题行一起不摆**: +上面那排页签已经写着「表单内容」,同一句话不该在 390 的屏上占两行,还搭上「N 项」和一颗没用的 +折叠箭头。起了名字的节(页签名、分隔条、手机端配置里的节名)照旧摆;好几节的时候兜底那节也照摆, +那时候节名是把正文分开的记号,撤了反而读不出哪段是哪段。 压在「外部页面」那一页上的格子也不在摘要里出现——桌面上它们本来就不显示, 手机上跟着摆只会让人以为那一格丢了。 @@ -239,8 +265,12 @@ - 多出口先选一条再写意见,**每条出口上写着它去哪儿**(`同意 → 财务复核`),不用点了才知道; 适用条件不成立的那几条当场标黄说为什么走不了(手机上没有悬停,等人次点完再吃一句提示是白费一次拇指), 点了也带不走——挡回来的是桌面那份 `pickRoute`,手机版式没有第二条闸; -- 同意那一屏只有「说一句 + 提交」:五句常用意见点一下就填进框,主按钮是「提交,看下一条」—— - 手上通常不止一条,办完不停在原地; +- 同意那一屏只有「说一句 + 提交」:五句常用意见点一下就填进框,主按钮是「提交,回待办」—— + 批完这张就把它关掉,落回待办列表;退回、转办同一口径。这一档原先是「自动去下一条」, + 省一次拇指,代价是批完的人看不见「这条真走了、还剩几条」,而且两个 id 之间 + `TaskDetailView` 不重新挂载,抬头那一屏还是上一张单子的内容;列表本来就自己取数, + 剩下几条摆在眼前,下一条点不点由人决定(`TaskDetailView` 也补了 `watch(taskId, load)`, + 直达链接、前进后退换单子时不会再拿旧数据糊在新的 URL 上); - 退回带目标环节 + 逐级/直退 + 意见,加签带前后/并行串行,抄送带要不要对方处理, 与桌面那几个弹窗的选项一一对上,一样不少; - 更多操作:加签、转办、抄送、分享、完整单据、看电脑版,末尾三档字号。手机上不给「打印审批单」 @@ -359,14 +389,14 @@ cd frontend && pnpm dev 自动化那一头:`MobileTaskView.spec.ts`(12 条)盯的是「什么摆在哪儿」,包括必填没填时不给点同意、 两条出口要先挑一条、走不通的出口当场说为什么且点不走、意见 chips 真能填进框、 -提交整个交给桌面那份逻辑、不归他办时操作位不说谎;`useFormPlan.spec.ts`(20 条)盯归置口径,含页签分节、外部页面那一页的格子不摆、`mobileHidden` 单独计一笔, -以及 `readerSections` 那套「空值也留一行」的读法;`MobileFormReader.spec.ts`(6 条)盯 §4.3 那一屏: +提交整个交给桌面那份逻辑、不归他办时操作位不说谎;`useFormPlan.spec.ts`(40 条)盯归置口径,含页签分节、外部页面那一页的格子不摆、`mobileHidden` 单独计一笔, +以及 `readerSections` 那套「空值也留一行」的读法;`MobileFormReader.spec.ts`(7 条)盯 §4.3 那一屏: 按页签分节、外部页面给卡片并带上 `标签页key#页签key` 那个回写分区键、手机上不展示的那格哪儿都不出现还要报数、 空值留一行破折号、环节权限藏起来的不出现。`ExternalCheckPanel.spec.ts`(3 条)盯 §4.4 那三条: 没配闸门不摆、配了就摆、闸门撤了但有结论仍然摆。设计器那一档由 `FieldInspector.newTypes.spec.ts`(18 条)里那四条盯:普通格子有「手机上不展示」且勾得进字段、 「标签页」那一格不给这一档而「默认隐藏」还在、排版件两档都没有、框选一次收一片而排版件不参与。 -`MobileFormSummary.spec.ts`(4 条)盯「一节最多六行、剩下收成一颗『展开更早 N 条』、换一张单子不把上一张摊开的状态带过来」;`MobileFlow.spec.ts`(5 条)盯这条时间线的三条底线:默认只有最近三步、发起那一行不许被收掉、「等谁处理」和单号还在;`MobileTopBar.spec.ts`(3 条)盯那条细栏只写页名与返回;`AppLayout.spec.ts`(6 条)里四条盯的就是「手机上整条顶栏不挂、抽屉不挂、细栏只挂在子页面、桌面照旧」;`MobileHome.spec.ts`(8 条)盯五张卡片的顺序、地址、权限过滤,以及上面那张口径表——数字来源写死在断言里,谁换成自己另算一份就红,另有一条盯抬头那颗铃铛与它那张弹层;`MobileTabBar.spec.ts`(5 条)盯底部栏只有三格、以及钉在电脑版时那口回去的井;`useMobileFeed.spec.ts`(5 条)盯攒页不重不漏、回第 1 页清干净;`ReadListView.spec.ts`(3 条)盯 `?tab=done` 落地就在已阅、切档位把档位写回地址。 +`MobileFormSummary.spec.ts`(15 条)盯「一节最多六行、剩下收成一颗『展开更早 N 条』、换一张单子不把上一张摊开的状态带过来、节名是兜底来的那一节不摆标题行」;`MobileFlow.spec.ts`(5 条)盯这条时间线的三条底线:默认只有最近三步、发起那一行不许被收掉、「等谁处理」和单号还在;`MobileTopBar.spec.ts`(3 条)盯那条细栏只写页名与返回;`AppLayout.spec.ts`(6 条)里四条盯的就是「手机上整条顶栏不挂、抽屉不挂、细栏只挂在子页面、桌面照旧」;`MobileHome.spec.ts`(8 条)盯五张卡片的顺序、地址、权限过滤,以及上面那张口径表——数字来源写死在断言里,谁换成自己另算一份就红,另有一条盯抬头那颗铃铛与它那张弹层;`MobileTabBar.spec.ts`(5 条)盯底部栏只有三格、以及钉在电脑版时那口回去的井;`useMobileFeed.spec.ts`(5 条)盯攒页不重不漏、回第 1 页清干净;`ReadListView.spec.ts`(3 条)盯 `?tab=done` 落地就在已阅、切档位把档位写回地址。 `MobileWorkView.spec.ts`(12 条)盯 §4.2 那一屏:抬头不重复流程名与发起时间、整页没有「刷新」也没有 打印审批单、没有画布、切页签才出时间线且单号在末尾、办得动才挂吸底那一行、终止走下推层并把意见抛出去、 没权限时 `···` 里不摆那两颗、挂起与被锁各自说一句,还有一条盯下拉这一把真的把 refresh 抛出去、给了取数那条路就走它且胶囊等到取完; @@ -375,5 +405,5 @@ cd frontend && pnpm dev 手机上整页换掉且判据原样递下去、电脑宽度一格都没少。 `returnPath.spec.ts`(6 条)盯手机上落地那一屏:有工作台落那五张卡片、没有工作台落待办、桌面落门户、 站外地址不被带出去——它原先写死落 `/home`,而且没有 `work:workbench` 的人会被守卫打回门户新闻页。 -全量 `npx vitest run` 1184 条绿,`npx vue-tsc --noEmit` 与 eslint 干净,`vite build` 通过 +全量 `npx vitest run` 1363 条绿,`npx vue-tsc --noEmit` 与 eslint 干净,`vite build` 通过 (预览台两个 html 不在产物里:rollup 只有一个入口 `index.html`)。真机那几件(企微内置浏览器、iOS 安全区、软键盘顶页面)还得在手机上过一遍。 diff --git a/docs/mobile-form-layout-config.md b/docs/mobile-form-layout-config.md index 8859ddd..fbabe6f 100644 --- a/docs/mobile-form-layout-config.md +++ b/docs/mobile-form-layout-config.md @@ -12,7 +12,7 @@ | 要做的事 | 配在哪儿 | 生效范围 | | --- | --- | --- | | 手机上那一屏只出一节 | 表单设计器 → 工具栏「**手机端**」→ 勾「按这份配置展示」 | 只影响手机版式(待办详情 + 单据详情) | -| 那一节叫什么 | 同一面板 → 「这一节的名字」(留空取第一个页签名,再没有写「表单内容」) | 同上 | +| 那一节叫什么 | 同一面板 → 「这一节的名字」(留空取第一个页签名;既没配也没页签就**不摆标题行**,那一节从头到尾就是正文) | 同上 | | 摆哪几格、什么顺序 | 同一面板 → 那张清单,从上到下就是手机上从上到下,两颗粒子改一格 | 同上 | | 某一格上不上屏 | 清单上那颗「展示 / 不展示」,或属性面板那颗「**手机上不展示**」(**同一个键**) | 同上 | | 那一格怎么摆(一行 / 整段 / 置顶 / 缩略图 / 收成一行 / 逐条展开) | 清单上那一格右侧的下拉(可选项按字段类型给,选不出摆不出来的组合) | 同上 | @@ -100,6 +100,15 @@ if (mobile) return planByMobileLayout(mobile) 格子却因为没值自己消失,他就得先猜"是没填,还是被我配丢了"。摘要那版反过来—— 四十几格里挑能看的,空的不占行。两处口径不一样是各自要答的问题不一样,不是漂移。 +**节名没配就不摆那一行标题**。`planForm` 给每一节标一个 `generic`:名字是配表的人起的 +(面板上那一栏)或表单上现成的(第一个页签名)就算名字,`generic: false`;两头都没有、 +由代码补一句「表单内容」的算兜底,`generic: true`。`MobileFormSummary.vue` 与 +`MobileFormReader.vue` 在这种节上把 `title` 传空串(条件是「整屏只有这一节」),`MobileFold` +没有标题就把标题行、条数、折叠箭头一起不摆,内容直接摊开——上面那排页签已经写着「表单内容」, +同一句话不该在 390 的屏上占两行。内容一行不少,顺序也照配置;好几节的时候(「完整单据」里 +连着「系统取数」那一节就是这种)兜底那节照旧摆标题,那时候节名是把正文分开的记号。 +预览台 `form=custom&title=none` 摆的就是这一档。 + **「置顶」那几格不住在这一节里**:它摆到抬头那一排大字(`plan.floats`,`MOBILE_FLOAT_MAX = 3`), 超出三格的回到节里按顺序摆,不丢。抬头本来就在讲"这单大概是什么",摆四五个数就成了报表。 @@ -158,20 +167,24 @@ if (mobile) return planByMobileLayout(mobile) ```bash cd frontend && pnpm dev # 配过的样子:http://localhost:3000/preview-mobile.html?screen=detail&form=custom +# 节名留空(整屏就这一节,那一行标题不摆):http://localhost:3000/preview-mobile.html?screen=detail&form=custom&title=none # 没配的样子(对照):http://localhost:3000/preview-mobile.html?screen=detail&form=tabs # 面板本身:http://localhost:3000/preview-mobile.html?screen=panel ``` +`title=none` 这一档看的是「配了开关但没起名字」:节名回落到第一个页签名(那张假单子有页签, +所以标题行照摆),部门那一格念的是路径末段 `软件开发事业部`,不是整条 `紫光汇智\软件开发事业部`。 + 预览台是 dev only 的(`src/dev/mobilePreview.ts`),吃真的版式组件、真的词条、真的 Tailwind, 数据用 `mobileFixtures.ts` 那份假报销单——**不打后端、不碰数据库**。 -测试(`cd frontend && npx vitest run`,全套 1294 条): +测试(`cd frontend && npx vitest run`,全套 1363 条): | 文件 | 盯什么 | | --- | --- | | `utils/mobileLayout.spec.ts` | 配置读不读得出来、清单顺序、摆法回落、删格补格对账、外部页面那一格的键与开关 | -| `components/oa/mobile/useFormPlan.spec.ts` | 只出一节、系统取数不再并走、空值照样摆、四道闸、置顶上限、明细两档、入口开关、外部页面那张卡片与它的两道闸 | -| `components/oa/mobile/MobileFormSummary.spec.ts` | 屏幕上真是那样:不折叠、`—`、明细逐条、缩略图、卡片带对 `job`/`activity`/`slotKey`、开关没开时还是从前那版 | +| `components/oa/mobile/useFormPlan.spec.ts` | 只出一节、系统取数不再并走、空值照样摆、四道闸、置顶上限、明细两档、入口开关、外部页面那张卡片与它的两道闸、节名是配置起的还是兜底的、部门那一格只念部门名 | +| `components/oa/mobile/MobileFormSummary.spec.ts` | 屏幕上真是那样:不折叠、`—`、明细逐条、缩略图、卡片带对 `job`/`activity`/`slotKey`、开关没开时还是从前那版、节名没配就不摆那一行标题 | | `components/oa/design/MobileLayoutPanel.spec.ts` | 清单对得上现在这张表、改动当场 emit、上不上屏写的是 `mobileHidden`(外部页面那一行例外,写配置的 `hidden`) | | `views/oa/design/FormDesignerView.mobile.spec.ts` | 配完存得出去(`content.layout.mobile`)、重开读得回来、进撤销栈与未保存、删掉的格子不留死配置 | diff --git a/docs/notification-channels-design.md b/docs/notification-channels-design.md index 1904a58..3b2c94f 100644 --- a/docs/notification-channels-design.md +++ b/docs/notification-channels-design.md @@ -15,9 +15,13 @@ 配置面压到三格:**发到哪**(SMTP 账号或机器人地址)、**发什么事**(勾事件)、**以什么身份发**(口令 / 加签密钥)。 没有第四格,因为第四格通常是"收件人规则",而那一格一旦开放就会出现"配了渠道却不知道发给谁"。 +唯一的例外是 `hub_wecom` 那一格的**收件人标识**:它不改"发给谁"(还是站内信那批人), +只说"向统一身份要到这个人时按哪一列报名字"。这不是收件人规则,是寻址方式, +所以开放它不会长出"配了渠道却不知道发给谁"那张脸。 + ## 1. 支持哪些渠道 -`models.NotifyChannel.KINDS`,界面上是五个选项: +`models.NotifyChannel.KINDS`,界面上是六个选项: | 种类 | 传输 | 要填的东西 | 典型用法 | | --- | --- | --- | --- | @@ -26,12 +30,26 @@ | `feishu` 飞书群机器人 | 群机器人 Webhook | 地址 + 加签密钥 | 同上 | | `wecom` 企业微信群机器人 | 群机器人 Webhook | 地址 | 同上 | | `webhook` 自定义 HTTP | POST JSON | 地址 + 签名密钥 | 自建企业微信应用、内部短信网关、值班系统 | +| `hub_wecom` 企业微信应用消息 | 交给统一身份 Hub 代发 | 形态(卡片 / 纯文字)、标题额度、收件人标识(按哪一列认人) | **推到个人手机 + 点开直接批那张单** | -**第五种是留的口子,不是凑数**:企业微信"工作通知"(发到个人)和内部短信网关都需要企业级凭证与 -各自的 token 换取流程,把它们各做成一种内置渠道,等于把五套外部账号体系搬进配置页。 +**第五种是留的口子,不是凑数**:内部短信网关这类需要企业级凭证与各自的 token 换取流程, +把它们各做成一种内置渠道,等于把几套外部账号体系搬进配置页。 `webhook` 渠道发出去的是一封结构固定的 JSON(`event` / `title` / `body` / `person` / `job` / `url`), 中间转换交给对方那半公里。 +**第六种是"转发型"渠道,跟前五条不一样**:前三条群机器人只能发到群里(谁都能看见、也 +可以谁都不理),"工作通知"要发到个人手机上还得点开就是自己那条待办,这需要企微应用凭证、 +`access_token`、可信 IP 一整套。这一套统一身份 Hub 已经替所有下游系统做了,所以本系统 +**不再持有第二把企微密钥**,只调 Hub 一次 HTTP;点开那张卡片回到的是已经跑通的免登回调。 +口径、逐人失败语义与前提清单见 `docs/hub-integration.md` §15(对接文档 9.6), +方案沿革见 `docs/wecom-app-notification-plan.md`。 + +Hub 只认两种收件人标识:`user_id`(`users.hub_user_id`,人员主键)与 `account` +(`users.account`,登录账号)。**用哪一种、按什么顺序退回,是渠道上的 `config.receiver`**, +界面上是四档并排的选择,旁边写着每一档能覆盖多少个在职账号;投递记录用 +`oa_notify_delivery.target_field` 记住每一串标识是按哪一列取的。口径见 +`docs/hub-integration.md` §15.3。 + ## 2. 事件 `channels.EVENTS` 六项,**取值与 `oa_notification.type` 完全一致**——同一个"新的待办"在站内信和 @@ -56,12 +74,28 @@ 被抄送的人),渠道就发给同一批人: * 邮件:从用户账号上取 `email`,格式不对当没有; -* 群机器人:发往渠道自己填的那个地址。 +* 群机器人:发往渠道自己填的那个地址; +* Hub 企业微信:按渠道上 `config.receiver` 给的顺序认人——默认先取 `users.hub_user_id` + (统一身份的人员主键),取不到退回 `users.account`;一种都取不到才落 `skipped`。 + 押账号上是会坏事的——账号会被企业微信那边同步改写,所以它只配当退路;但主键不可信的 + 环境(同步回来的 id 与目录对不上、账号全是本地自建)可以把它调成主位,甚至只认账号。 + 顺序是渠道上可配的一格,四档与覆盖人数见 `docs/hub-integration.md` §15.3。 拿不到收件人不静默丢,落一条 `skipped` 并写明原因("这个账号没有邮箱,去「组织人员」里补上之后可以重发")。 这条与失败分开统计——**没邮箱不是系统坏了**,混在失败里会让运维天天去看根本不存在的故障。 补完邮箱之后那条记录还能就地重发。 +### Hub 企业微信一人一条 + +`hub_wecom` 不进上面那段合并:卡片点开是"我的那条待办",收件人必须在一条消息里唯一确定, +而且**逐人失败原因(谁没绑企微、谁不在可见范围)得有个地方记**,合并成一条就没处记了, +自动补发也就无从谈起。三个人的会签 = 三条独立卡片 + 三行投递记录。 + +顺带一件同样只有"一人一条"才做得了的事:`/todo/` 只发给这条待办的**持有人**。 +`notify()` 对整批收件人只传一个 `task=`("外部审批那一环超时"会连兜底管理员一起知会), +合并成一条时这种差别根本没法落进链接;一人一条之后入队时按人核一次归属 +(`channels.hub_task_links`),不是持有人的就把 task 抹掉,深链退回 `/work/`。 + ### 群机器人一批发一条 `notify()` 一次可能带三个处理人(会签)。一人一条发到群里 = 群里三条一模一样的"您有一张待办", @@ -74,6 +108,7 @@ ``` engine.notify() ──同一事务──▶ oa_notification(站内信) └▶ oa_notify_delivery(pending,每人 × 每渠道一行) + └─提交那一刻─▶ 叫醒调度线程(service/wake.py,跨副本发一条 Redis 广播) 后台调度线程 ──▶ claim() 认领 ──▶ 真发 ──▶ success / failed(退避) / dead(喊人) ``` @@ -88,8 +123,16 @@ engine.notify() ──同一事务──▶ oa_notification(站内信) * **可重试与不可重试分得很清**:连不上、超时、5xx 算可重试;SMTP 口令被拒、收件人被拒、 机器人返回业务错误码(钉钉/飞书/企微连不上时报的往往是 **HTTP 200 + errcode≠0**)直接进死信—— 重试一百次也不会变成成功,只会把日志刷满; +* **入队当场发,不等轮询**:投递记录随 `notify()` 那次事务提交,提交的那一刻由 `service/wake.py` + 把调度线程叫醒(写回、渠道、事件三条路共用;跨副本走同一条 Redis 广播)。这一条是**必需的**而不是 + 锦上添花——叫醒原本只有写回发件箱有,本部署 `oa_notify_delivery` 上量得出来:一条企微推送从 + `create_time` 到 `sent_at` 等了 **28 / 35 / 55 / 60 秒**,而 `ms` 那一格写着真发只用了 1 秒。 + 轮询(下一条)退回"叫不醒也要发出去"的兜底,钉住它的是 `scripts/check_notify_wake.py`; * **调度周期自适应**:`main.py::_scheduler_tick_seconds()` 发现发件箱 / 渠道 / 事件队列里有到点的 - 活,就把 60 秒收紧到 15 秒;没活时不空转。 + 活,就把 60 秒收紧到 15 秒;没活时不空转; +* **一轮有 20 秒的时间预算**:`channels.run_due()` 发满就收工,剩下没认领的行状态一动没动, + 下一轮(或被新消息叫醒的那一轮)接着发。否则一个慢 SMTP 网关把 40 条各顶满超时,刚排上的那条 + 提醒就算被叫醒也要排在别人后面等完。 每条记录都留 `attempts` / `response` / `ms` / `last_error`。"消息丢了"必须看得见, 排错时第一个问题永远是"到底发出去没有、对方说了什么"。 @@ -109,20 +152,65 @@ engine.notify() ──同一事务──▶ oa_notification(站内信) * 改渠道要 `system:notify`,**看投递记录也要**——那里面有收件人邮箱; * **测试发送只发给点按钮的人自己**:邮件发到他自己邮箱,群里发一条明写「测试」的消息。 配渠道的人必须先在自己身上验过,而不是配完等用户来报"没收到"。他自己没邮箱就当场直说。 + Hub 那一路额外带一条 `target_path=/todo` 的深链——点开那一跳(Hub 认人 + `redirect`) + 是这条链路上最容易配错的一段,测试发送得一起验掉; +* **`hub_wecom` 的密钥不在渠道上**:它跟「系统设置 → 统一身份」的 `hub_integration_key` + 是同一把,与免登换票、目录导出共用。渠道上没有可泄露的东西,`scrub_config` 那套 + "只进不出"对它不适用(它压根没有密钥格)。 ## 7. 明确不做 -* **消息卡片与"在群里直接同意"**:要企业应用回调 + 对方平台后台配置 + 一套身份回查, - 属于"接进企业微信/钉钉工作台"那一档工程,不是消息渠道该顺手做的; +* **"在群里直接同意"**:要企业应用回调 + 对方平台后台配置 + 一套身份回查, + 属于"接进企业微信/钉钉工作台"那一档工程,不是消息渠道该顺手做的。 + ("卡片 + 点开直达待办"这一半已经随 `hub_wecom` 做了:卡片上没有按钮, + 同意/退回在点开之后的页面里做,`docs/wecom-app-notification-plan.md` §10.4 说的是同一件事;) * **个人级消息偏好**(我自己只要邮件不要群消息):等有真实诉求再加,先让管理员统一配, 避免"渠道配了但每个人都能关"这种排查噩梦; * **免打扰时段 / 摘要合并**:`expire` 与 `press` 的量都很小,先不上; * **短信渠道**:走 `webhook` 那一条接内部短信网关; * **回执(已读 / 送达)**:邮件与机器人给不了可信回执,不假装能。 + `hub_wecom` 是个例外的一半:Hub 给的是**逐人投递结果**(送到企微了没有)而不是已读, + 界面上有个「回查送达」按钮按 `msg_key` 去问一次,仍然不承诺"他看过了"。 ## 8. 验收 -`backend/tests/oa_platform.py` 在**唯一的开发库**上跑,进程内起 SMTP 桩与机器人桩,覆盖: -事件订阅过滤、没邮箱落 `skipped` 并说明原因、钉钉加签可复算、HTTP 200 + `errcode` 非 0 算失败、 -退避重试、重试用满进死信、人工重发、卡住回收、`claim()` 多进程互斥、测试发送的收件人、 -权限拦截,以及**同一批收件人只发一条群消息**。 +原本挂在 `backend/tests/oa_platform.py` 的那一整套(SMTP 桩 + 机器人桩)随测试目录一起 +在 2026-10 清掉了,留着是说明这一层原本验到哪:事件订阅过滤、没邮箱落 `skipped` 并说明原因、 +钉钉加签可复算、HTTP 200 + `errcode` 非 0 算失败、退避重试、重试用满进死信、人工重发、 +卡住回收、`claim()` 多进程互斥、测试发送的收件人、权限拦截,以及**同一批收件人只发一条群消息**。 + +眼下真能跑的是 `backend/scripts/check_notify_hub.py`:进程内起一台假 Hub,不连库、 +不碰真 Hub,把 `hub_wecom` 这一路钉住——收件人标识按渠道配的那一列认(默认主键优先、 +只勾一种就不退回、串和列表都洗成一种写法、人没了才回落记录里 `target_field` 那一列)、`msg_key` 跨重试稳定而 +人工补发换世代、深链只发站内相对路径、标题/正文/markdown 三档字节预算、逐人原因分档 +(重试 / 跳过 / 死信)、请求级 401/403/400 判死与 409/5xx 退避、`duplicate` 算成功、 +回查按 `receiver` 回显对齐到人、入队一人一条且待办深链只给持有人、免登落地只认站内 `redirect`、 +Hub 缺 `home_url` 时摘掉深链降级成纯提醒而其它 `400` 不瞎降级、Hub 的零值 `sent_at` 不当发送时间。 + +接口那一层另有一条 `check_notify_hub_api.py`:连开发库、起真 `TestClient`,只把 Hub +指到进程内那台假 Hub,验 `notify/meta` 报底细、保存校验形态与额度、换种类不留上一档参数、 +收件人标识的四种写法与非法值、覆盖人数随渠道列表回一份、测试发送真发给本人并带 `/todo` 深链、 +回查与补发的键怎么算、投递记录的权限收口。 + +界面那一半由 `frontend/src/views/oa/NotifyChannelView.receiver.spec.ts` 钉:列表说得出 +当前按哪一列认人、编辑框摊开四档并选中库里那一档、每一档带覆盖人数、换档保存出去的是 +`config.receiver` 那根数组、投递记录里的标识带着它是哪一列取的。 + +投递记录的分页由 `frontend/src/views/oa/NotifyChannelView.pagination.spec.ts` 钉。 +这一屏以前是 `GET /notify/deliveries?limit=80` 一刀切:跳过和失败动辄几百行堆在这儿, +第 81 条往后压根翻不到,而"上周那批为什么没发出去"恰恰在第 81 条往后。现在和待办、 +操作日志一个口径——`page` / `page_size` 进,`total` / `pages` 出(`serializers.page`)。 +钉住的是:分页器念得出后端给的总数、点第几页就带 `page=几` 去要(不是把到手的一页切一切)、 +换任何筛选(状态 / 渠道 / 关键词)都回第 1 页、每页条数换档传的是 `page_size`、 +补发之后仍留在当前这一页。顺带修掉「全部」那一格永远是 0:它读的是 `counts` 里 `''` +那一项——当前筛选下的总数,`counts` 跟着渠道 / 类型 / 关键词走,但不跟着状态走, +否则选中的那一档永远等于「全部」。 + +点卡片回来的落地那一跳由 `check_notify_landing.py`(后端:真路由 + 假 Hub 的验票接口) +与 `frontend/src/views/auth/SsoCallbackView.landing.spec.ts`(前端:换到会话之后落哪一页) +一家一半钉住,口径见 `docs/hub-integration.md` §15。 + +```bash +cd backend && PYTHONPATH=. python3 scripts/check_notify_hub.py +cd backend && PYTHONPATH=. python3 scripts/check_notify_hub_api.py # 这条要连开发库 +``` diff --git a/docs/process-detail-export-design.md b/docs/process-detail-export-design.md new file mode 100644 index 0000000..4626e55 --- /dev/null +++ b/docs/process-detail-export-design.md @@ -0,0 +1,437 @@ +# 流程明细导出:把监控里的数据按勾的字段落成一张表 + +它是一条**独立菜单**,位置排在流程监控那条的下面紧邻(不是流程监控页里的一个页签, +路径也不挂在 `/monitor/` 下面)。一句话说清它凭什么单开一页:财务和审计要的不是 +「屏幕上这些行的快照」,而是一张横跨几条流程、只要那十几格、还能按「谁还没动」筛出来 +的明细表——**一次导出一个文件,勾了几条流程就按流程分几张表**。 + +下面给的是落实方案:权限怎么单给、截图红框那七项各自的死口径(尤其「未操作者」到底 +算哪几类人)、自选流程与字段的接口形状、落到哪个文件哪一层、怎么验。口径全部对着 +现库与现有代码写。 + +## 1. 与现成导出口的分工 + +`backend/app/api/export.py` 已经有两条监控侧导出口(`/export/works?scope=admin`、 +`/export/tasks?scope=admin`),列是写死的 `WORK_COLUMNS` / `TASK_COLUMNS`,表单字段只在 +「整批是同一张表单」时才摊开。它服务的是流程监控页那句「屏上就是这些行」,这个定位不动。 + +| | 流程监控导出(已有) | 流程明细导出(本模块) | +| --- | --- | --- | +| 入口 | 监控页右上角 | 独立菜单,权限单给 | +| 流程范围 | 当前筛选下的行 | 用户勾哪几条,一条流程一张表;合并模式下混排,第一列「流程」分行 | +| 列 | 写死;同表单才摊字段 | 每条流程自己勾字段 | +| 筛选 | 关键字 / 流程 / 状态 / 发起日期 / 超时 / 挂起 | 红框七项,含未操作者与归档日期 | +| 未操作者 | 只有 `manual_identity_text` 那一串人名 | 五类来源,含待阅与需处理抄送 | +| 产物 | CSV(列写死) | XLSX **按流程分 sheet**(也可切成合并成一张表);CSV 走合并表头 | + +两处的**单元格口径必须一样**:值怎么渲染只在 `export.cell_text` 一处(选项翻标签、签名 +只留「已签名」、附件留文件名、级联用 ` / `、月份念成「2026年10-11月」、区间念成 +「起 ~ 止」、金额带大写)。本模块用它,不另写一份,否则同一个字段在两张表里长得不一样。 +分层上把 `cell_text` / `_scalar_text` / `_table_text` / `_relation_ids` / `_dt` / +`_status_label` / `_duration_text` 这七个纯值渲染函数挪进 `service/exportfmt.py`, +`api/export.py` 原样 re-import 回来——`api/export.py` 里的名字与 +`scripts/check_completed_dedup.py` 那句 `from app.api.export import export_tasks` 都不动, +而 service 层也不用反过来 import api 层(新模块要的正是这一层)。 + +## 2. 要求一:单独授权 —— 新增 `monitor:export` + +落点在 `backend/app/permissions.py` 的 `CATALOG`,system 组紧跟 `monitor:work` 之后: + +```python +*_group("system", ("monitor:work", "monitor:export", "statistics:view", "log:view", + "system:setting", "system:notify")), +``` + +三条决定,逐条说为什么: + +- **不复用 `monitor:work`。** 那一码管的是「看着单子并伸手干预」。明细导出是另一只手: + 它把全公司的报销单连金额、审批意见一起拽出系统。要导出的人(财务专员、审计)和要 + 干预的人(流程管理员)常常不是同一批,一码两用就只能给大。 +- **两码互不为前置。** 只给 `monitor:export` 的人能进这一页、调这一组接口,看不到流程 + 监控菜单;只给 `monitor:work` 的人照旧用监控页那颗导出。判据只出现在 + `Depends(require_permission("monitor:export"))` 与路由 `meta.permission` 两处,代码里 + 不写 `can("monitor:work") or can("monitor:export")` 这种混判。 + 这与 `docs/process-intervention-design.md` §5 刻意不加 `monitor:intervene` 并不矛盾: + 那次怕的是「能看不能动」的静默降级;这一档新开的是**一个页面**,没授权就是菜单里没有, + 不会有人对着灰掉的按钮猜。 +- **内置角色一个都不给**(含部门负责人)。库里已有角色的行为一字不变,新权就在 + 「权限角色」页勾给需要的那一个角色。`GET /auth-roles/catalog` 直接读 `CATALOG`, + 权限矩阵里自动多出一格,前端 `constants/permissions.ts` 补文案键即可。 + +菜单独立,权限码却仍留在 `monitor:` 这一族里、不另起 `export:`:这一档的数据范围口径、 +判据来源和监控页本来就是同一套,权限矩阵里紧跟 `monitor:work` 摆着,给权限的人一眼比得出 +两档差别;为一条独立菜单新开一个分组,只是让矩阵多一行分组标题。 + +数据范围不参与这次改动:取数仍走 `permissions.scope_person_refs` + `permissions.scoped`, +与 `_monitor_work_part` 同一把尺。**能给哪些人的单子由数据范围决定,能导哪几条流程由 +清单决定**,两件事正交。所以「单独授权一个财务专员」的典型配置是 +`monitor:export` + 数据范围=全部(或自定义勾中报销相关的几个部门)。 + +改动清单: + +| 文件 | 改什么 | +| --- | --- | +| `backend/app/permissions.py` | `CATALOG` 加一码;`BUILTIN_ROLES` 不动 | +| `frontend/src/constants/permissions.ts` | system 组加 `{ code: 'monitor:export', labelKey: 'perm.monitorExport' }` | +| `frontend/src/i18n/locales/zh.ts` / `en.ts` | `perm.monitorExport` 与整节 `detailExport.*` | +| `frontend/src/router/index.ts` | 新增**独立**路由 `export/detail`(不嵌在 `/monitor/` 下),`meta.permission = 'monitor:export'` | +| `frontend/src/components/layout/AppSidebar.vue` | admin 组里紧跟 `/monitor` 之后插一条「流程明细导出」。路径与 `/monitor` 没有前缀关系,`isActive` 那句 `startsWith` 不用改,两条菜单各亮各的 | +| `frontend/src/views/oa/ProfileView.vue` | 个人页那份入口同步加一条 | +| `README.md` | §权限角色 的权限码表加一行;§自检 挂上新脚本名 | + +## 3. 要求三:红框那七项,逐项给死口径 + +界面上从左到右按截图排。日期一律复用 `_parse_date`(结束日按 `add_day=True` 取右开 +区间,所以「到 10-31」含 31 号一整天)。 + +| 界面项 | 控件 | 操作符 | 后端参数 | SQL 落点 | 边界 | +| --- | --- | --- | --- | --- | --- | +| 创建人 | `PeoplePicker` / 部门树 | 属于(部门,含下级)· 等于(指定人)· 包含(姓名或账号模糊) | `creator_mode` + `creators` / `creator_unit_ids` | `creator_identity IN (...)` | 部门那条先 `org.descendant_unit_ids` 再 `org.identities_for_unit` 换成账号清单,**不用 `LIKE` 前缀**——部门改名会把老单子的 DN 全筛没,这是 `scope_person_refs` 换账号口径时踩过的同一个坑 | +| 创建日期 | `DateRangePicker` + 预设(今天 / 近 7 天 / 本月 / 上月 / 自定义) | 区间 | `create_start` / `create_end` | 在途 `oa_work.start_time`;归档 `oa_work_completed.start_time` | 归档表也存了 `start_time`,两边并起来查不用特殊处理 | +| 工作流 | 流程多选(分类分组 + 搜索) | 属于 | `processes[]` | `process IN (...)` | 不在红框,但它是这一页的主条件:勾哪几条流程决定这张表里出现哪些行、表头并到哪些列 | +| 未操作者 | `PeoplePicker`(多选)+ 口径勾选 | 包含任一 · 包含全部 · 不包含 | `unoperator.*`(见 §4) | `EXISTS` 子查询 | 本模块最厚的一块 | +| 流程状态 | 多选:在途 / 已挂起 / 办结 / 已终止 / 已作废 | 属于 | `statuses[]` + `paused` | 在途走 `oa_work`,其余走 `oa_work_completed.status` | 沿用 `_status_filter`(逗号分隔多选)与 `_monitor_work_part` 里「状态不落在这张表就是查不到」的并页写法;挂起仍按现规则只对在途生效 | +| 归档日期 | `DateRangePicker` + 预设 | 区间 | `archive_start` / `archive_end` | `oa_work_completed.finish_time` | 本平台「办结 / 终止 / 作废那一刻整行搬进归档表」(`engine._finish_work`),所以归档日期就是 `finish_time`,不另设一列。在途单没有归档日期:填了这一段而状态里又含在途,在途那一半直接给 `literal(False)`(与 `paused` 处理缺列的写法同构),界面同时提示「在途单不参与归档日期」 | +| 相关核算项目名称 | 文本 + 等于/包含 | 等于 · 包含 | `project_name` | 表单 JSON,见 §5 | 名称先翻成编码再比 | +| 相关核算项目编码 | 文本 + 等于/包含 | 等于 · 包含 | `project_code` | 表单 JSON,见 §5 | 与名称同时给时取交集 | + +红框外那三项(主题、工作流、当前节点)里,**工作流**按上面收进来了,主题就是现有的 +`keyword`(标题/单号/流程名/发起人),当前节点留到 P2,理由见 §12。 + +## 4. 「未操作者」:什么叫该动没动 + +截图里这一项的操作符是「包含」,人也是选人框,说明它问的是**这张单子上还有谁欠着一个 +动作没做**。本平台的待办、待阅、需处理抄送是三套独立的账,归档时各有各的搬法,所以 +「未操作」不能只盯着 `oa_task`。完整口径是下面五类,界面上就是五个勾,默认全开: + +| 勾选项 | 命中条件(按 `job` 关联到本行单据) | 为什么算 | +| --- | --- | --- | +| 待办未处理 | `oa_task` 有该人的行,且 `add_task_from <> 'before_pending'` | 待办行只在本人表态时消失(`_complete_task`);`expired=True` 的那几条再单列成「已超时」 | +| 待阅未打开 | `oa_read` 有该人的行、`requires_action = false`、`view_time IS NULL` | 用户点名的那一条:**没看过就算没动**。打开单据页会顺带登记不需处理的待阅(`mark_reads_for_work`),所以 `view_time IS NULL` 是真的没打开过,不是漏打卡 | +| 需处理抄送未回复 | `oa_read` 有该人的行、`requires_action = true`、`handle_time IS NULL` | 「抄送需处理」只有填了处理意见才算完(`mark_read` 里没有 `handling=True` 直接抛错)。**点开看过一眼仍旧算未操作** | +| 终止收尾 | `oa_task_completed.processing_type = 'terminate'` 且是该人的行 | 终止那一刻还挂着的待办被强行结掉,行仍留在原持有人名下、`operator` 写的是按终止的人(`engine.terminate` → `_complete_task`)。这批人从头到尾没表过态,而单子已经归档、`oa_task` 里的行已经删掉,只能从已办台账里认 | +| 加签未激活 | `oa_task` 有该人的行且 `add_task_from = 'before_pending'` | 前置加签在被激活前是挂起态、还没真正到人手上,默认**不算**(与本人待办列表 `_task_conditions`、监控待办 `_admin_task_stmt` 同口径);勾上才计入 | + +四条配套的读法与边界,都得出接口才说得清: + +- **归档的单也要算。** 单据落定那一刻,**没打开过的待阅不搬进已阅档**,行留在 `oa_read` + 只打 `completed = true`(`_finish_work` 里那段注释就是为这件事写的)。所以「单子办完了 + 但有人压根没看过」这一审计现场,只有把 `oa_read` 一起查才捞得出来——这一条正是 + 本模块相对现有导出最有用的地方。 +- **一个人可能占两类、也可能一个岗位几个人。** 会签 / 并行是每人一条待办行,输出就出两列: + 「未操作者」按人去重后的姓名串,「未操作条数」给真实行数;筛选按人,不去重。 +- **「没结果」有两种,必须分开。** 一种是所有人都办完了,另一种是单子停在自动 / 汇聚 / + 延时环节上、压根没人有待办,还有一种是被管理员挂起。多给一列 `停等类型`: + `有人未操作` / `无人待处理(自动·汇聚·延时)` / `挂起中(原因…)` / `已归档`。 + 少这一列,导出表里那片空格会被读成「都办完了」。 +- **谁的锅也要能看出来。** 转办、委托代理派下去的待办,行上 `identity` 是现在的持有人、 + `empower_from_identity` 是被委托的那位(`engine.transfer` 与 `org.apply_agents` 都是这个 + 写法);外部表态环节(`config.openApprove` + `oaLock`)的待办照旧躺在 `oa_task` 里, + 但按钮在第三方手上。所以每条未操作都带一个来源标签:`本人` / `转办自 X` / `代理自 X` / + `等待外部系统`,并给「包含委托方」和「排除外部锁定环节」两个开关。默认计入——那一环 + 确实还没走完,只是不该算这个人拖延。 + +SQL 形状(写在新模块 `service/detail_export.py`,注释里点名这五类,别让人重新推一遍): + +```python +def unoperator_exists(model, refs: list[str], kinds: set[str]): + """所选的人里有没有人是这一单的未操作者:命中任意一类就算这一行入选。""" + parts = [] + if "task" in kinds: + cond = [models.Task.job == model.job, models.Task.identity.in_(refs)] + if "addPending" not in kinds: + cond.append(models.Task.add_task_from != "before_pending") + parts.append(select(models.Task.id).where(*cond).exists()) + if "readPlain" in kinds or "readAction" in kinds: + cond = [models.Read.job == model.job, models.Read.identity.in_(refs)] + branch = [] + if "readPlain" in kinds: + branch.append(and_(models.Read.requires_action.is_(False), models.Read.view_time.is_(None))) + if "readAction" in kinds: + branch.append(and_(models.Read.requires_action.is_(True), models.Read.handle_time.is_(None))) + parts.append(select(models.Read.id).where(*cond, or_(*branch)).exists()) + if "terminate" in kinds: + parts.append(select(models.TaskCompleted.id).where( + models.TaskCompleted.job == model.job, + models.TaskCompleted.identity.in_(refs), + models.TaskCompleted.processing_type == "terminate").exists()) + return or_(*parts) +``` + +必须按 `job` 关联到本行——写成 `job IN (子查询)` 再取反,SQLAlchemy 会把条件铺成笛卡尔积, +`_monitor_work_part` 里「超时」那条已经栽过一次,注释就在那儿。 + +上面这个函数是「包含任一」。另外两个操作符在同一处换皮,不另开一条路:「包含全部」把 +每个人各调一次这一份再 `and_`,「不包含」对整份取 `~`;勾掉「加签未激活」就是上面 +`addPending not in kinds` 那一支自己走掉。三种模式共用同一份判据,筛出来的人才可能是 +同一批人。 + +选人框传进来的可能是人员 id,先过 `personref.account_of` 归一成账号再比(与 +`_admin_task_stmt` 处理 `identity` 那一句同一个写法);认不出来就原样比,让「筛出来是空」 +这件事留在调用方看得懂的地方。 + +**取数不逐行问库。** 筛选用 `EXISTS` 留在数据库里;本页拿到 `job` 清单之后,输出列要的那 +三份(谁、哪一类、等了多久、超没超时、催了几次)按 `job IN (...)` 一次查回 `oa_task` / +`oa_read` / `oa_task_completed`,在 Python 里分组拼列。一条 `perf_guard.py` 的语句数就能 +看出有没有退化。 + +## 5. 相关核算项目:一条表单字段驱动的条件 + +现网实况:费用报销单上这一格是 `accountProject`,`select`,字典 `pms_project`,**库里存 +的是编码,界面上念的是名称**(见 `docs/expense-thirdparty-field-update.md` 那张字段表)。 +它不是单据固有列,而是表单 JSON 里的一格,所以这一条筛选项得先解决「哪一格是它」。 + +- **定位**:`catalog` 接口按流程回 `projectField`——在该流程用过的表单里找 `key = + accountProject`,找不到再退到 `label` 命中「相关核算项目」的 `select` / `picker` 字段。 + 回得到就带 `{ process, key, dictCode }`,回不到就给空;前端把「项目」那两个筛选控件对 + 没有这一格的流程标灰并写明原因,而不是默默筛出一张空表。 +- **名称 → 编码**:`dicts.items_of(db, dictCode)` 取字典项,按 `label` 等于(或包含) + 命中值翻成 `value` 集合,再拿去比 JSON;同时把**名称本身也留在候选里**——历史上有人 + 直接往这格写过名称,只比编码会漏。名称查询命中的编码集合同时用于全部选中流程里 + 出现过的每一个 `projectField.key`。 +- **SQL**:照 `service/quota_source.py` 已有的那一句写,不发明新写法: + +```python +extracted = func.json_unquote(func.json_extract(model.data, f"$.{key}")) +clause = extracted.in_(candidates) | func.json_contains(model.data, json_string(...), f"$.{key}") +``` + + 后半个 `json_contains` 兜的是多选那类数组值;单选时它退化成一次等值比较,既不漏也不报错。 + 两个条件用 `|` 连起来,不要写成两条 `where`——那样等于要求同一格既是标量又是数组。 +- **性能现实**:`data` 是 JSON 列,MySQL 上没有函数索引。执行顺序让 流程 / 创建日期 / + 归档日期 / 创建人 先把候选压小(`idx_oa_work_process_start`、 + `idx_oa_work_completed_creator` 都在),JSON 那条排在最后再筛。真嫌慢了再谈生成列 + + 索引,那一刀要动表结构,先不为一把筛选项动。 + +## 6. 要求二:自选流程 + 自选该流程表单里的字段 + +列目录三层来源,`catalog` 一次回全: + +1. **固有列**(所有流程共用一套):单号、标题、流程、分类、状态(含「已挂起」)、发起人、 + 发起部门、创建日期、归档日期、耗时、当前环节、当前处理人、结果与终止原因(`result` / + `result_opinion`)、父单号。 +2. **表单字段**:该流程 `latest_form` 与各环节 `Activity.form` 用过的表单**字段并集**—— + 发起一张表、审批换一张表是常态,只读 `latest_form` 会漏掉审批环节改过的那几格。 + 走 `formruntime.fields_of` + `fillable`,明细表字段(`type=table`)用 `columns_of` 展开子列, + 版面格(group / tabs 这类压根没值的)标灰。 +3. **未操作者那一组**:未操作者、未操作条数、未操作来源、最长等待、超时候办数、停等类型, + 口径见 §4。 + +选择交互:左侧流程清单按分类分组 + 搜索 + 「已选 N 条」,右侧字段清单,顶部常驻一条 +「本次表头 · 预计 1,842 行 · 6 条流程」,点开就是**将要导出的那几份表头**——分表模式给每条 +流程各自的表头,合并模式给归并后的那一份。人真正要确认的一直是「最后那张表长什么样」, +不是「每条流程各勾了些什么」。三处省手:勾一个表单字段时,所有含这个 `key` 的已选流程一起 +生效(行上标「已同步 3 条流程」);进页面带一套常用列(出厂那套是固有列 12 个 + 未操作者 +4 列),不用从空表开始;常用列还能自己存——勾好一套点「设为常用列」,落在浏览器本地 +(`export.detail.commonColumns`,含环节列),之后「恢复常用列」和下次进页面都按这一套来, +没存过才回出厂那套。那颗按钮跟着状态走:没存过是「设为常用列」,存过且勾法不一样是 +「更新常用列」,勾得跟它一模一样就是「取消常用列」。「恢复常用列」只带回当前所选流程 +真有的格子,被落下的报一句「有 N 列不在所选流程里」,不悄悄少出列。 + +列 id 带前缀防撞名:`base.serial` / `form.accountProject` / `table.expenseItems.amount`。 +请求里的列是一条**扁平清单**,每条流程实际出哪些列由后端按目录取交集,合并模式由后端做归并; +这一列只想给某一条流程用,加一个可选 `only`: + +```jsonc +{ "processes": ["91d4...", "…"], + "layout": "perProcess", // perProcess=按流程分 sheet / merged=合并一张表 + "columns": ["base.serial", "base.title", "base.status", "base.start_time", + "base.unoperators", "base.unoperator_kinds", + "form.accountProject", "form.reimbursement_date", "form.checkTotal"], + "columnsOnly": { "form.checkTotal": ["91d4..."] } } +``` + +## 7. 产物:按流程分 sheet,也能合并成一张表 + +**默认按流程分 sheet**(`layout=perProcess`):勾几条流程就有几个 sheet,顺序跟左侧流程 +清单一致,sheet 名就是流程名。每条流程的表单本来就不一样,各写各的表头最省心,也最像财务 +手上那摞按月存的台账。 + +- 每个 sheet 的表头 = 本次勾的列 ∩ 这条流程有的列。这条流程压根没有的格子,在它自己的 + sheet 里**不出现**,不留一列空着会让人以为数据丢了。合并模式反过来:勾了一整批表单字段 + 却在这几条流程里一个都没落上,直接报清楚是哪几列,而不是悄悄出一张只有固有列的表—— + 界面是按目录勾的,交不出这种报文,会交出来的只有手拼接口的人与字段被改过之后存下的老方案。 +- 固有列与未操作者那一组每条流程都出;表单字段按 `key` 对号入座。 +- sheet 名:截到 31 字符、去掉 `[]:*?/\`、重名补 `-2`。流程改过名时老单据的 `process_name` + 还是旧名,sheet 名一律取目录里**当前**的流程名,`count` 与预览也按同一个名字分组。 +- 只勾一条流程时天然就是一张表,不用特殊分支。 +- 勾了却一条单子都没命中的流程**也留一张只有表头的空表**。界面上说了「将出 N 张表」, + 文件里就得是 N 张:静默少一张,财务只会读成"导出漏了这条流程",不会想到是筛没了。 +- 可选「附一张汇总表」,**默认关**:放在第一个位置,只出固有列那几格。关着是刻意的—— + 多一张表就多一处和明细对不上的地方,真要一眼扫全部再勾。两种分表方式都认这个勾:合并模式 + 下它照样排在最前面,按下过的键不该因为换了另一种形态就悄悄失灵。 + +**合并成一张表**(`layout=merged`)是给跨流程做透视、对账用的第二种形态:所有行按创建日期 +倒序混排,第一列是「流程」,表头由勾的列归并出来。归并规则: + +- 同一个字段 `key` 在几条流程里都有,就是**同一列**。列名取目录里第一个出现的 label,表头 + tooltip 写明「字段 `accountProject` | 费用报销流程、借款流程」。同 label 不同 `key` 的各占 + 一列——猜它们是一个意思,比多一列危险得多。 +- 某条流程没这一格,那一行这一列就是**真空**,不填 0 也不填「—」,列名也不挂流程后缀, + 否则表头会被拉宽到没人看得下去。 +- 列顺序固定:固有列 → 未操作者那一组 → 表单字段(按首次进入目录的顺序,不按勾选顺序)→ + 审批环节列。未操作者那一组紧跟固有列,是因为拿着这张表去催办的人,视线本来就停在 + 「谁卡在哪儿」那一段,隔着一整排业务字段去够它不顺手。同一份勾法每次导出必须是同一张表, + 否则周与周之间的台账叠不上。 + +**CSV 只走合并那一种表头**:一个文件一张表是 CSV 的物理限制。界面选 CSV 时把「按流程分表」 +置灰并写明原因,要分流程就导 XLSX(多份 CSV 打 zip 那套先不做,见 §12)。 + +其余几件: + +- **XLSX(默认)**:`openpyxl` 以 `write_only` 流式写,每个 sheet 冻结首行并开自动筛选 + (依赖已在 `backend/requirements.txt`,目前只有 `storage/preview.py` 用过,同样延迟导入)。 + 文件名 `流程明细导出_20261104_1530.xlsx`。 +- **单元格文本**:`service/exportfmt.cell_text`(由 `api/export.py` re-export,两边同源,见 §1)。 +- **上限**:一次总量 50000 行,注册成 `dbconfig` 的 `export_detail_max_rows`;超了直接报错 + 要求收窄,不静默截断。分表模式下 `count` 按流程分开报,一眼看出该收哪一条。 +- **审批环节列(可选,默认关)**:按环节顺序给每一环配「处理人 / 完成时间 / 意见」三列, + 最多 12 环,超出折成「更多环节见单据详情」。分表模式下它天经地义——每条流程各按自己的 + 环节顺序出列;合并模式下取所选流程环节的并集,最容易把表头拉爆,勾上时界面给一句列数预估。 + +## 8. 后端结构与接口 + +新增 `backend/app/service/detail_export.py`(列目录、筛选条件、未操作者五类来源、workbook +组装),路由挂在 `backend/app/api/export.py` 里新开一段 `prefix="/export/detail"`(这个文件 +现在 400 行,加进去仍在读得动的长度;再长就该拆 `api/export_detail.py`,先不拆)。 + +```text +GET /api/v1/export/detail/catalog 可选流程清单 + 每条流程的字段目录 + projectField +POST /api/v1/export/detail/count 按当前筛选估行数(分流程),导出前先知道多大 +POST /api/v1/export/detail/preview 取前 20 行:分表模式按流程给表头与行,合并模式给归并表头 +POST /api/v1/export/detail/download 出文件(xlsx / csv) +``` + +四条全部 `Depends(require_permission("monitor:export"))`,`check_route_guards.py` 认这个形状。 +筛选、列与 `layout` 走 `schemas.py` 新加一个 body 模型(camelCase → snake_case 沿用现有约定), +不走一长串 query 参数——列清单加筛选条件是一棵树,URL 装不下也不该装。 + +**取数必须与流程监控共用一份条件。** 做法是给 `runtime._monitor_work_part` / +`_admin_work_page` 补几个可选参数:`processes`(多选 IN)、`creator_refs`、 +`archive_start` / `archive_end`、`extra_clause`(未操作者与项目条件由本模块算好塞进来)。 +默认值下行为一字不变,监控页照旧。理由和 `_created_clause` 摆出来给两个消费者共用是同一条: +**同一套条件写两遍,迟早漂开,漂开的结果是屏上有的单导不出来。** + +留痕走 `api/runtime.py` 里现成的 `_log_operation(db, user, action, target, detail, request)`, +动作名 `export_detail`,target 记流程名串、detail 记「N 列 / 筛选摘要 / M 行」。导出的 +是一次离开系统的一批数据,这事得查得出来;有 `log:view` 的人去操作日志页看。 + +再说归档日期那条为什么写成 `literal(False)`:`oa_work` 上其实**有** `finish_time` 列, +只是在途单那一刻还没人给它写值。所以「在途 + 归档日期」真按列去比会得到一片 +`NULL` 比较出的假空集,报错方向还指着日期格式;直接给 `literal(False)` 是把这个 +「在途单没有归档日期可筛」的事实写在 SQL 里,与 `_monitor_work_part` 处理挂起缺列那一句 +同构,界面上再补一句人话提示。 + +## 9. 前端 + +`frontend/src/views/oa/ProcessDetailExportView.vue` 是一个独立菜单页。它刻意没用 +`TablePageLayout`——那一版把内容按屏高塞成三段,这一页的筛选区 + 双栏选择器 + 表头条 + +预览塞不进去,宁可让它顺着页面自然往下滚。从上到下四块: + +- 页头:一句说明 + 「刷新流程目录」+ XLSX/CSV 分段 + 「导出」。 +- 筛选卡:按截图顺序排(关键字 / 创建日期 / 归档日期 / 流程状态 / 创建人 / 项目名称 / + 项目编码 / 匹配方式 / 未操作者),复用 `PeoplePicker`、`Select`(`multiple`)、 + `DateRangePicker`。创建人给「按人员 / 按部门 / 按姓名」三种口径;未操作者那一整块单独 + 占一段——人员多选、任一/全部/不含、五类口径勾选(默认四类,「加签未激活」要手勾)、 + 两条开关(算上转办委托方、排除外部表态锁)、只看超时,口径规则写在旁边的 `HelpTooltip` + 里,尤其「待阅没打开也算未操作」这一条。 +- 双栏「选流程 | 选字段」:流程按分类分组、可搜索、显示每条命中条数;字段侧同名的 + 字段勾一次就给所有已选流程加上,纯版面的格子标灰不可勾,环节列单独一组。 +- 「本次表头」条:常驻「将出 N 张表 · 列数 · 预计 M 行」,列数超上限就地标红;分表/合并 + 做成一颗分段控件(选 CSV 时把分表那档置灰并写明原因),旁边一颗「附一张汇总表」、 + 「看表头」「算一下行数」。 +- 预览:分表模式带流程页签(含 0 行的那张),合并模式就是跨流程混排的那一份列, + `DataTable` + `Pagination` 取 20 行。勾完防抖 550ms 自动刷一次预览,不用每改一下 + 手点一次。预览与文件共用同一份列拼装函数,所见即所得不靠两边各写一遍再对。 + +`api/exportDetail.ts` 装类型与 `catalog` / `count` / `preview` / `download` 四个方法; +`api/client.ts` 原来的 `http.download` 只发 GET,补一个 `postDownload(url, body)`, +`Content-Disposition` 那套文件名解析(`filename*=UTF-8''`)原样复用。上一次勾的流程与字段 +存 `localStorage`(键 `export.detail.prefs`),够用于「下周还要同一张表」;这份偏好只在进 +页面时回收一次,之后手点「刷新流程目录」不会把当前勾法冲掉。 + +## 10. 表结构要不要动 + +P1 **不动表**:筛选条件、字段选择都在报文里,留痕进现成的 `oa_operation_log`,配置进 +`oa_system_setting` 那套运行配置。 + +P2 如果要把「导出方案」做成可共享的(财务做成一张标准台账给别人用),再开 +`oa_export_preset`(`id / name / owner / shared / processes / columns / filters / sort / +create_time`),跟着走 `db.ensure_columns` + `scripts/dump_schema.py` 重导 +`sql/schema.sql` + `sql/upgrade/` 一条脚本那套完整流程。没这个需求之前不先建表。 + +## 11. 实施顺序 + +1. 权限码 + 菜单 + 空页面(先让人能勾、能进来看见一句空态); +2. `catalog` 接口(流程清单 + 字段目录 + `projectField`)与前端选择器,含归并表头预览; +3. `_monitor_work_part` / `_admin_work_page` 扩参数,`count` / `preview` 通了; +4. 未操作者五类来源(`service/detail_export.py`)+ `check_detail_export.py`; +5. XLSX writer(按流程多 sheet + 合并单表两种形态)与 CSV、`download`,留痕; +6. 上限、配置项、README 与本文对齐。 + +第 3、4 步是这个模块真正的难点,也是最值得先跑脚本再写接口的两步。 + +## 12. 还没做,以及为什么先不做 + +- **当前节点 / 主题两个筛选项**(截图里有、没在红框):`keyword` 已经能按标题与单号捞, + 当前节点要按环节名匹配「此刻停在哪」,得先定「环节改过名的老单子按哪个名字算」。 + 这一条想清楚再放,别先摆一个口径含糊的框。 +- **明细表按行展开**:`type=table` 的字段默认压进一格(与 `export._table_text` 一致)。 + 摊开会让「一行一张单」变成「一行一条明细」,行数、合计与对账口径一起变, + 单表模式下等于换了一张表的意思,得整页一起重做。 +- **异步导出与下载中心**:本仓没有任务队列,导一张五万行的表等三十秒,比「稍后到通知里取」 + 更容易核对。真到需要时再做。 +- **定时导出发邮箱**:`service/channels.py` 的 SMTP / 群机器人是现成的,但定时导出要连 + 「方案存服务端 + 收件人配置」一起做,那是 §10 的 P2 表结构。 +- **导出时补外部字段**(PMS 的项目全称、预算余额):`service/sqlsource.py` 能连,但逐行 + 外呼会把导出一张表变成一次慢查询集合,先不进。 +- **多份 CSV 打 zip**:分流程 CSV 的真实需求是「每个流程发给不同的人」,那不如直接导 XLSX + 拆 sheet;zip 又叠一层编码与解压问题,先不做,界面上把原因写在置灰的分表选项里。 +- **只读监控角色**:`monitor:work` 拆「看 / 动」那件事仍然欠着,见 + `docs/process-intervention-design.md` §9,本模块不动它。 + +## 13. 怎么验 + +`backend/scripts/check_detail_export.py` 已落地,86 条断言,全程在未提交事务里跑、收尾 +`rollback`(照 `check_completed_dedup.py` 那套;只有 `download` 那一条照例 `commit` 留痕, +所以收尾配了一段显式清理)。它不只跑 service 层:`catalog` / `count` / `preview` / `download` +四条接口的真函数也各调一遍,报文怎么挡、表头怎么拼、文件名与编码对不对都在脚本里。 +跑法 `PYTHONPATH=. python3 scripts/check_detail_export.py`。原先列的十条: + +1. 只给 `monitor:export` 的人能导,没这个码的人 403;只给 `monitor:work` 的人调这一组接口也 403; +2. 数据范围=本部门的人导不出别的部门的单,与监控页同一批 job; +3. 待办未处理命中「待办未处理」,办完即不再命中; +4. 待阅未打开命中「待阅未打开」;打开单据页后不再命中,而需处理抄送**打开后仍命中**,填了意见才不命中; +5. 单子办结归档后,那条没打开过的待阅仍旧命中(`oa_read` 里 `completed=true` 的行还在); +6. 终止的单命中「终止收尾」,且带的是被强行结掉那条待办的持有人,不是按终止的人; +7. 前置加签未激活默认不命中,勾上「含未激活加签」才命中; +8. 归档日期只作用在归档表那一半,状态含在途时在途行不给结果且不报错; +9. 「相关核算项目名称」与「编码」两种写法命中同一批单,名称走字典翻编码、库里存名称的老数据也命中; +10. 分表模式:勾两条流程出两个 sheet,名字与顺序跟页面上的流程清单一致,某流程没有的字段 + 在它自己那个 sheet 里不出现;合并模式:同 `key` 的字段**只归并成一列**,没这一格的行留空 + 而不是补 0,「流程」不论勾没勾都排第一列;两种模式的行数都与 `count` 一致,超上限报错 + 而不是截断。 + +跑脚本时另外撞出来五件事,都已改: + +- **创建人留空当成"谁都不要"**:`creator_whitelist` 在没勾人时回的是空清单,而空清单在 SQL + 里是恒假条件——不填创建人这一条,整张表一条都导不出来。留空一律回 `None`(不限)。 +- **合并模式把「附一张汇总表」吞了**:那条分支早于汇总表的拼装就 `return`,勾了没反应。 +- **未操作者查姓名调了个不存在的函数**:`org.person_name` 压根没有,只有待办被转办过才走得到 + 这一行,冒烟数据一直照不到它。换成 `org.display_names` 一次批量翻,别逐行问库。 +- **分表模式把空流程丢了**:`build_sheets` 里一句 `if not bucket: continue`,于是页面上写着 + 「将出 4 张表」而文件里只有 3 张。见 §7,现在每条选中的流程都留一张表。 +- **只授权这一个码的角色登录后没第一屏**:`utils/returnPath.ts` 那两张落地表里没一条命中, + 兜到 `/home` 又被守卫弹回登录页,看着像密码错了。两张表末尾各加一条 + `['monitor:export', '/export/detail']`,排在原有几档之后不抢前面; + `returnPath.spec.ts` 补了用例,真浏览器(桌面 1440 / 手机 390)各跑一遍确认落在导出页。 + +前端跑 `pnpm typecheck`、`pnpm lint:check`、`pnpm build`;`check_globals.py` 与 +`check_route_guards.py` 每条改动都顺手跑。手测路径:用一个有 `org:authrole` 的账号在 +「权限角色」页新建一个测试角色,只勾 `monitor:export` + 数据范围=全部(`GET +/auth-roles/catalog` 本身就挂 `org:authrole`,这一步换不了人)→ 用测试角色登录 → +侧栏里只看得见「流程明细导出」这一条菜单(流程监控不亮),且它与流程监控那条不相干地 +各自高亮 → 选两条流程 → 勾金额、项目、未操作者 → 预览 → 导出 XLSX,在 Excel 里核对两个 +sheet 的名字、顺序、各自表头与行数,再切「合并成一张表」导一次,核对表头与页面上那条提示 +一致、两条流程的行混在一起而第一列分得清、同 `key` 字段只出一列、未操作者那几列与预览 +逐行对得上。 diff --git a/docs/wecom-app-notification-plan.md b/docs/wecom-app-notification-plan.md index 2c2e0e2..8a6c8b2 100644 --- a/docs/wecom-app-notification-plan.md +++ b/docs/wecom-app-notification-plan.md @@ -1,12 +1,26 @@ # 企业微信工作通知:推到个人 + 点开即批(完整方案) -版本 v6.1 状态:待评审,**不含任何代码改动** +版本 v7 状态:**已按 Hub 代发落地**(`hub_wecom` 渠道,见开头状态更新与 +`docs/hub-integration.md` §15);下面的 A 方案(OA 直连自建应用)保留为备胎施工手册 适用前提:OA 已接入统一认证(Hub),Hub 已对接企业微信(通讯录同步、扫码登录、企业内免登 Hub) --- ## 0. 结论速览 +> **v7 状态更新(2026-11-04):Hub 把代发接口做出来了,本文的主案已按 §4 H1 落地为 +> `hub_wecom` 渠道,"一期走 A(OA 直连自建应用)"不再是必经之路。** +> Hub 的新接口与本文 §4 H1 那份契约有出入(路径是 `/api/v1/auth/notify/wecom/messages`、 +> 幂等键叫 `msg_key`、收件人叫 `receivers`、深链叫 `target_path` 且链接由 Hub 生成永久链接), +> 本系统按 **Hub 实际的接口**实现,逐人结果与失败原因比原设想更细。 +> 落地口径、逐人原因分档与前提清单见 `docs/hub-integration.md` §15, +> 验收 `backend/scripts/check_notify_hub.py`。因此本文这几件事全部作废: +> 企微自建应用与通讯录只读权限(前提第 1 步)、`users.wecom_userid` 那列的兜底匹配任务 +> (映射由 Hub 的「Hub账号」扩展属性与目录同步负责,本系统 `users.wecom_user_id` 仍在, +> 只是这一路不再需要它)、`service/wecom.py` 的 token 与错误码治理、可信 IP 配在 OA 这一侧。 +> **A 方案没被否定,它现在是备胎**:Hub 哪天不代发了,`channels.deliver()` 加一条发送分支 +> 就切回去,业务代码与投递记录都不用动。 + **最终推荐:三条腿分开走,各自选当前最省的那条。** | 腿 | 走法 | 状态 | @@ -698,7 +712,10 @@ secret 沿用现成的"留空 = 不改"。 ## 变更记录 -- v3:确认 Hub 已具备通讯录同步、扫码登录与企业内免登,身份映射整块移出 OA; +- v7:**Hub 代发(本文的 B1 / §4 H1)真的做出来了**,落地为 `hub_wecom` 渠道, + 三条腿合并成一条腿 + 一段已有的免登链路。契约与 §4 H1 的差异、作废项与"直连自建应用 + 降为备胎"的理由见开头那段状态更新;细节写在 `docs/hub-integration.md` §15。 + 本文其余部分按"方案史 + 备胎施工手册"读,别当 TODO 清单。确认 Hub 已具备通讯录同步、扫码登录与企业内免登,身份映射整块移出 OA; H2 由"新增接口"降级为"确认现成能力";开发阶段简化 `sub` 为空的处置并记债; 补上线/灰度/回滚、最小披露口径、无 `job` 事件的处理。 - v2:确定走 Hub 代发(B1),映射改为 Hub 的责任 + 接口契约;查明 `state` 不能承载业务参数。 diff --git a/docs/wecom-work-notification-spec.md b/docs/wecom-work-notification-spec.md index 06d8721..22f4b55 100644 --- a/docs/wecom-work-notification-spec.md +++ b/docs/wecom-work-notification-spec.md @@ -148,7 +148,7 @@ ### 4.1 数据层 ``` -users.wecom_userid VARCHAR(190) NULL -- 企业微信 UserID;一人一个,不参与任何现有判定 +users.wecom_userid VARCHAR(190) NULL -- 企业微信 UserID;不参与任何现有判定 ``` > **落地口径(2026-10-21 实测后定稿)**:这一列已经落地,列名是 **`users.wecom_user_id`** @@ -159,12 +159,14 @@ users.wecom_userid VARCHAR(190) NULL -- 企业微信 UserID;一人一个 > 归一化后同一个键)。**C9 那条「`hub_sync` 不写这一列」随之下线**,本文 §4.6 的通讯录任务 > 从此是兜底:它接上时只能补 Hub 没给的人,并且要认同一件事——Hub 是「没号就不带键」, > 所以人员同步每轮会按整趟清单把"这列已下发、这个人没带"的本地值清空(`wecom_cleared`), -> 兜底任务写进去的号也一样会被这轮清掉,别把它当持久映射存。一号一人的查重在同步侧做 -> (`wecom_conflicts`)。完整口径见 `docs/hub-integration.md` §6 字段映射表。 +> 兜底任务写进去的号也一样会被这轮清掉,别把它当持久映射存。**这一列照抄上游**:Hub 把 +> 同一个号同时发给几个人时(2026-11-05 测试站实测 `user_id=1` 与 `user_id=455` 都带着 +> `chenhao2`),几个人都挂着这个号,同步只在记录里报 `wecom_conflicts`,不再让后到的那个人 +> 空着。完整口径见 `docs/hub-integration.md` §6 字段映射表。 不建新表(v1 方案里的 `oa_wecom_binding` 作废,映射寄生在 `users` 上更贴合现状: -`hub_user_id` 已经是同一个套路)。唯一性靠写入前两行查重,不加数据库唯一索引, -避免与 `ensure_columns` 的加列路径纠缠,也避免历史脏数据把启动卡住。 +`hub_user_id` 已经是同一个套路)。不加数据库唯一索引:这一列是 Hub 那份通讯录的镜像, +上游自己就可能把一个号发给几个人,加唯一约束等于让本地替上游兜脏数据、还会让同步写不进去。 ### 4.2 发送出口:一个 sender,两个实现 diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts index 99d7500..3597fe5 100644 --- a/frontend/src/api/client.ts +++ b/frontend/src/api/client.ts @@ -226,6 +226,16 @@ export const http = { const response = await apiClient.get(url, { params, responseType: 'blob' }) return { blob: response.data, filename: filenameOfDisposition(response.headers?.['content-disposition']) } }, + /** + * POST 出去换一个二进制文件:明细导出那种「筛选条件写在报文里」的下载走这条。 + * + * 筛选条件动辄几十个字段,塞进 query string 又丑又容易撞上 URL 长度上限, + * 而且后端读的是同一个报文结构——预览和下载共用一份 body,两边不可能对不上。 + */ + postDownload: async (url: string, body?: unknown): Promise => { + const response = await apiClient.post(url, body ?? {}, { responseType: 'blob' }) + return { blob: response.data, filename: filenameOfDisposition(response.headers?.['content-disposition']) } + }, /** * 存一个文件到本地(网盘、附件都是这一条)。 * diff --git a/frontend/src/api/exportDetail.ts b/frontend/src/api/exportDetail.ts new file mode 100644 index 0000000..a4adb3f --- /dev/null +++ b/frontend/src/api/exportDetail.ts @@ -0,0 +1,176 @@ +/** + * 流程明细导出的前端接口层:目录、估算行数、预览、下载四条。 + * + * 四条接口挂的是独立权限码 `monitor:export`(侧栏那条「流程明细导出」菜单本身也按它显隐), + * 与流程监控的 `monitor:work` 互不为前置——设计稿 `docs/process-detail-export-design.md` §2。 + * 报文一律驼峰,后端 CamelModel 两种写法都收,这里统一一种,别在一页里混着来。 + */ +import { http, saveBlob, type DownloadResult } from './client' + +/** 一列的候选。`layoutOnly` 是纯版面格(分隔线、标题),导出来必然空。 */ +export interface DetailColumnOption { + id: string + label: string + type?: string + fillable?: boolean + layoutOnly?: boolean +} + +/** 这条流程的「相关核算项目」在哪一格;没有这格就是 null。 */ +export interface ProjectFieldInfo { + key: string + label: string + dictCode: string + multiple: boolean +} + +export interface CatalogActivity { + id: string + name: string + orderNumber: number +} + +export interface CatalogProcess { + id: string + name: string + alias: string + category: string + categoryName: string + enabled: boolean + columns: DetailColumnOption[] + projectField: ProjectFieldInfo | null + activities: CatalogActivity[] +} + +/** 未操作者的一类来源。`default` 为假的那类(加签未激活)要用户自己勾。 */ +export interface UnoperatorKind { + id: string + label: string + default: boolean +} + +export interface DetailCatalog { + processes: CatalogProcess[] + baseColumns: Array<{ id: string; label: string }> + unoperatorColumns: Array<{ id: string; label: string }> + defaultColumns: string[] + unoperatorKinds: UnoperatorKind[] + layouts: Array<'perProcess' | 'merged'> + formats: Array<'xlsx' | 'csv'> + maxRows: number + maxColumns: number + maxProcesses: number + maxActivityColumns: number +} + +export interface UnoperatorFilter { + /** any=包含任一 / all=包含全部 / not=不包含 */ + mode: 'any' | 'all' | 'not' + persons: string[] + kinds?: string[] | null + includePrincipal: boolean + excludeLocked: boolean +} + +export interface DetailFilters { + keyword: string + processes: string[] + /** ''=不限 / person=按人 / unit=按部门 / keyword=按发起人姓名关键字 */ + creatorMode: '' | 'person' | 'unit' | 'keyword' + creators: string[] + creatorUnitIds: string[] + creatorUnitSub: boolean + creatorKeyword: string + createStart: string + createEnd: string + archiveStart: string + archiveEnd: string + statuses: string[] + paused: string + expired: string + unoperator: UnoperatorFilter + projectName: string + projectCode: string + projectOp: 'eq' | 'contains' +} + +export interface DetailBody { + filters: DetailFilters + columns: string[] + /** 某几列只想给指定流程填值:{ 'form.checkTotal': ['流程 id'] } */ + columnsOnly: Record + activities: string[] + layout: 'perProcess' | 'merged' + summary: boolean + fmt: 'xlsx' | 'csv' + page?: number + pageSize?: number +} + +export interface CountResult { + total: number + limit: number + exceeded: boolean + byProcess: Array<{ process: string; name: string; count: number }> +} + +/** 一张成品表:表头 + 若干行,预览与下载用的是同一份结构。 */ +export interface DetailSheet { + name: string + headers: string[] + lines: string[][] +} + +export interface PreviewResult { + total: number + page: number + pageSize: number + sheets: DetailSheet[] +} + +export function emptyFilters(): DetailFilters { + return { + keyword: '', + processes: [], + creatorMode: '', + creators: [], + creatorUnitIds: [], + creatorUnitSub: true, + creatorKeyword: '', + createStart: '', + createEnd: '', + archiveStart: '', + archiveEnd: '', + statuses: [], + paused: '', + expired: '', + unoperator: { mode: 'any', persons: [], kinds: null, includePrincipal: false, excludeLocked: false }, + projectName: '', + projectCode: '', + projectOp: 'eq' + } +} + +export function catalog(): Promise { + return http.get('/export/detail/catalog') +} + +export function count(body: DetailBody): Promise { + return http.post('/export/detail/count', body) +} + +export function preview(body: DetailBody): Promise { + return http.post('/export/detail/preview', body) +} + +export function download(body: DetailBody): Promise { + return http.postDownload('/export/detail/download', body) +} + +/** 取回来顺手落地,回给调用方真实文件名,好在那句提示里念出来。 */ +export async function downloadDetail(body: DetailBody): Promise { + const result = await download(body) + const filename = result.filename || `流程明细导出.${body.fmt === 'csv' ? 'csv' : 'xlsx'}` + saveBlob(result.blob, filename) + return filename +} diff --git a/frontend/src/api/hub.ts b/frontend/src/api/hub.ts index 50b36af..dc67871 100644 --- a/frontend/src/api/hub.ts +++ b/frontend/src/api/hub.ts @@ -34,6 +34,42 @@ export interface HubSyncRun { /** 增量轮询专用:这批处理完停在哪个游标、落了几条变更 */ cursor_seq?: number changes_applied?: number + /** 这一趟真正换掉登录名的人数(Hub 改账号名,历史单据不会跟着搬) */ + renamed?: number + /** 已停用、Hub 又查无此人的同步账号让出登录名的个数 */ + reclaimed?: number + /** Hub 换过 organization_id 之后按「编码 + 名称」认回原部门的个数 */ + units_rebound?: number + /** 有界明细:改名对照、让位账号、认回部门、熔断计数、提示原文(旧记录可能没有) */ + details?: HubSyncRunDetails +} + +/** ``oa_hub_sync_run.details``:这一趟"到底动了谁"的名单级明细。 */ +export interface HubSyncRunDetails { + /** 登录账号改名前后对照(``旧账号 → 新账号``) */ + account_renames?: string[] + /** 姓名改名前后对照 */ + name_renames?: string[] + /** 让出登录名的僵尸同步账号(``原账号 → hub-lost-…``) */ + reclaimed_accounts?: string[] + /** 按「编码 + 名称」认回原部门的部门名 */ + rebound_units?: string[] + renamed?: number + reclaimed?: number + units_rebound?: number + name_renamed?: number + counts?: Record + mobile?: { returned?: number; updated?: number; invalid?: number } + wecom?: { + returned?: number + updated?: number + cleared?: number + invalid?: number + conflicts?: number + released?: number + } + guards?: { people?: number; units?: number } + notes?: string[] } export interface HubStatus { @@ -263,6 +299,16 @@ export interface HubProbe { message: string } +/** + * 停用熔断的口径:这趟等着停用的一旦超过 `ceiling`,就一个都不停、只报数, + * 并把那一趟标成「部分完成」。`percent` 是配置里的百分比,0 = 熔断关掉。 + */ +export interface HubOffboardGuard { + percent: number + ceiling: number + tripped: boolean +} + /** `GET /hub/directory/preview`:只读体检,真同步前先看清会动多少。 */ export interface HubDirectoryPreview { credential: string @@ -272,7 +318,34 @@ export interface HubDirectoryPreview { returned_users: number member_limit: number truncated: boolean - organizations: { total: number; new: number; known: number; disabled: number; offboard_candidates: number } + organizations: { + total: number + new: number + known: number + disabled: number + /** Hub 清单里没有、本地还绑着的部门(停用的候选,熔断可能挡下) */ + offboard_candidates: number + /** 熔断不挡的话这趟真会停用的部门数 */ + offboard_pending: number + offboard_guard: HubOffboardGuard & { min_units: number } + /** + * Hub 换过 `organization_id` 留下的重名壳子:编码与名称都已被在职部门占用, + * 同步既不会再认它们也不会自动合并,只能在部门里解绑再删除。 + */ + zombie_units: number + /** 能一键删掉的那几具(其余要先挪人、删下级或改角色的数据范围) */ + zombie_units_deletable?: number + zombie_unit_samples: Array<{ id: number; name: string; code: string; blockers?: string[] }> + /** 名称 / 上级会跟着 Hub 改的部门数 */ + renamed: number + moved: number + /** 本系统自己加的部门:同步一律不碰,只报规模 */ + local_units: number + /** 编码对得上、这趟会被认领下来的本地自建部门 */ + claimable_by_code: number + /** 挂在 Hub 已消失/停用部门下面的本地部门(得手工挪走) */ + local_hanging_units: number + } users: { new: number adopt_candidates: number @@ -280,12 +353,44 @@ export interface HubDirectoryPreview { unassigned: number protected_admins: number offboard_candidates: number + /** 熔断不挡的话这趟真会停用的人数 */ + offboard_pending: number + offboard_guard: HubOffboardGuard & { min_people: number } + /** Hub 没带 user_id / 没带账号,按主键认不出人 */ + no_hub_id: number + /** 账号名本地已属于另一个统一身份,这趟跳过没覆盖 */ + account_conflicts: number + /** 会把登录名让出来的僵尸同步账号(Hub 查无此人 + 本地已停用) */ + account_releases: number + /** 这趟到底让不让位:清单人数不足时后端会否掉,登录名原地留着 */ + account_releases_allowed: boolean + /** 让位的最低清单人数:低于这个数就不认"Hub 查无此人" */ + account_release_floor: number + /** 登录名会跟着 Hub 改名的人数(按账号存的引用跟着搬) */ + account_renames: number + /** 姓名会跟着 Hub 改的人数 */ + name_renames: number + /** 本地还没绑统一身份主键、这趟会补上的人 */ + unbound: number /** Hub 这次带下来多少个合法手机号;0 = 目录接口压根没下发这一列 */ with_mobile: number /** 带了号码字段但洗不出合法号码的人数 */ mobile_invalid: number /** 这一列接下来会怎么被写,后端已经说清楚了 */ mobile_note: string + /** 目录接口只回启用的人:inactive 恒为 0,Hub 侧停用会落在 offboard_candidates */ + directory_hides_disabled_users?: boolean + disabled_note?: string + } + /** 改名会牵动的"按字符串存的"配置(审批岗位、共享名单…) */ + impact?: { + renamed_units: number + moved_units: number + renamed_accounts: number + renamed_people: number + refs_at_risk: number + samples: Array> + note: string } offboard_accounts: string[] organization_sample: Array<{ diff --git a/frontend/src/api/index.ts b/frontend/src/api/index.ts index caa52d7..d81f2ee 100644 --- a/frontend/src/api/index.ts +++ b/frontend/src/api/index.ts @@ -16,5 +16,6 @@ export * as portalAPI from './portal' export * as hubAPI from './hub' export * as configAPI from './config' export * as exportAPI from './export' +export * as exportDetailAPI from './exportDetail' export * as checkAPI from './externalCheck' export { http, apiClient, onUnauthorized, saveBlob } from './client' diff --git a/frontend/src/api/notify.ts b/frontend/src/api/notify.ts index 44fbdb3..40f6bb4 100644 --- a/frontend/src/api/notify.ts +++ b/frontend/src/api/notify.ts @@ -1,5 +1,13 @@ import { http } from './client' -import type { NotifyChannel, NotifyDelivery, NotifyList, NotifyMeta } from '@/types' +import type { + BasePaginationResponse, + FetchOptions, + NotifyChannel, + NotifyDelivery, + NotifyList, + NotifyMeta, + NotifyReceiverCoverage +} from '@/types' /** * 消息渠道接口。 @@ -13,7 +21,10 @@ export function notifyMeta(): Promise { return http.get('/notify/meta') } -export interface ChannelList extends NotifyList {} +export interface ChannelList extends NotifyList { + /** 有 Hub 渠道时后端顺带算的一份收件人标识覆盖情况;没有就是 null */ + hubCoverage?: NotifyReceiverCoverage | null +} export function listChannels(): Promise { return http.get('/notify/channels') @@ -42,13 +53,18 @@ export interface DeliveryQuery { status?: string type?: string keyword?: string - limit?: number + page?: number + page_size?: number } -export interface DeliveryList extends NotifyList {} +/** + * 投递记录是分页的:``total`` / ``pages`` 给分页器,``counts`` 是各状态在当前筛选 + * (渠道 / 消息类型 / 关键词,不含状态本身)下各有多少条,``''`` 那一项是「全部」。 + */ +export interface DeliveryList extends NotifyList, BasePaginationResponse {} -export function listDeliveries(query: DeliveryQuery = {}): Promise { - return http.get('/notify/deliveries', { limit: 80, ...query }) +export function listDeliveries(query: DeliveryQuery = {}, options?: FetchOptions): Promise { + return http.get('/notify/deliveries', { page: 1, page_size: 20, ...query }, options) } /** 对方修好了:重新排队,下一轮调度再发。 */ @@ -56,6 +72,11 @@ export function resendDelivery(id: string): Promise { return http.post(`/notify/deliveries/${encodeURIComponent(id)}/resend`) } +/** 找 Hub 回查这一条的逐人送达结果,按对方口径改写本地记录(只读,可反复点)。 */ +export function recheckDelivery(id: string): Promise { + return http.post(`/notify/deliveries/${encodeURIComponent(id)}/recheck`) +} + /** 不等下一轮调度,当场再发一次。 */ export function sendDeliveryNow(id: string): Promise { return http.post(`/notify/deliveries/${encodeURIComponent(id)}/send-now`) diff --git a/frontend/src/api/org.ts b/frontend/src/api/org.ts index 6df9221..e532c4e 100644 --- a/frontend/src/api/org.ts +++ b/frontend/src/api/org.ts @@ -47,6 +47,43 @@ export function unbindUnitHub(id: string): Promise { return http.del(`/org/units/${id}/hub-binding`) } +/** Hub 换过主键之后留下的空壳部门:停用的旧身子,身份已被同名同码的在职部门接走。 */ +export interface ShellUnit { + id: string + name: string + code: string + hub_org_id: string + status: number + /** 非空 = 这一具删不掉,逐条写着原因(还有人 / 有下级 / 被角色当数据范围) */ + blockers: string[] +} + +export interface ShellUnitList { + total: number + /** 能一键删掉的那几具 */ + deletable: number + items: ShellUnit[] +} + +export interface ShellCleanupResult { + dry_run: boolean + deleted: Array<{ id: string; name: string; code: string; hub_org_id: string }> + skipped: ShellUnit[] +} + +/** 列出空壳部门(判据与「同步前体检」共用后端同一个函数)。 */ +export function listShellUnits(): Promise { + return http.get('/org/units/shells') +} + +/** 一键清理空壳部门;``ids`` 留空 = 清掉所有符合条件的,``dryRun`` 一行都不动。 */ +export function cleanupShellUnits(payload: { ids?: string[]; dryRun?: boolean } = {}): Promise { + return http.post('/org/units/shells/cleanup', { + ids: payload.ids ?? [], + dry_run: payload.dryRun ?? false + }) +} + export interface PersonQuery { keyword?: string organization_id?: string diff --git a/frontend/src/components/layout/AppHeader.vue b/frontend/src/components/layout/AppHeader.vue index 3173eba..1765471 100644 --- a/frontend/src/components/layout/AppHeader.vue +++ b/frontend/src/components/layout/AppHeader.vue @@ -220,14 +220,48 @@ function onDocumentClick(event: MouseEvent) { } } +/** + * 铃铛的刷新节奏。原来是一条 60 秒的定时器,每一拍都把列表和未读数一起拉回来—— + * 用户说的"消息推送有延迟"有一半落在这里:后端那一条消息早就写好了,小红点还要 + * 等最多一分钟才动。现在拆成两件事:未读数每 15 秒问一次(一条 COUNT,比原来那一页 + * 轻得多,所以敢问得更勤),列表只在**数字变了**或**面板正开着**时才问。 + * 切回这个标签页也立刻补一次——人刚回来就看见新消息,不该去等下一条定时器。 + */ +const POLL_MS = 15000 + let timer: number | undefined +let polling = false + +async function pollUnread() { + // 标签页在背后就不问:没人看着,省下的这一趟和回来时补的那一次正好抵消 + if (polling || document.hidden) return + polling = true + try { + const { count } = await supportAPI.unreadCount() + if (count !== unread.value || notificationOpen.value) await loadNotifications() + else unread.value = count + } catch { + // 角标问不到就当没变,下一拍再问;这一份是提示,不该弹红条 + } finally { + polling = false + } +} + +function onBackAgain() { + if (!document.hidden) void pollUnread() +} + onMounted(() => { document.addEventListener('click', onDocumentClick) + document.addEventListener('visibilitychange', onBackAgain) + window.addEventListener('focus', onBackAgain) loadNotifications() - timer = window.setInterval(loadNotifications, 60000) + timer = window.setInterval(() => void pollUnread(), POLL_MS) }) onUnmounted(() => { document.removeEventListener('click', onDocumentClick) + document.removeEventListener('visibilitychange', onBackAgain) + window.removeEventListener('focus', onBackAgain) if (timer) window.clearInterval(timer) }) diff --git a/frontend/src/components/layout/AppSidebar.vue b/frontend/src/components/layout/AppSidebar.vue index 14aab5a..eaa91b8 100644 --- a/frontend/src/components/layout/AppSidebar.vue +++ b/frontend/src/components/layout/AppSidebar.vue @@ -141,6 +141,7 @@ const sections = computed(() => { { path: '/org/roles', label: t('nav.role'), permission: 'org:role', icon: 'shield' }, { path: '/org/auth-roles', label: t('nav.authRole'), permission: 'org:authrole', icon: 'key' }, { path: '/monitor', label: t('monitor.title'), permission: 'monitor:work', icon: 'eye' }, + { path: '/export/detail', label: t('detailExport.title'), permission: 'monitor:export', icon: 'download' }, { path: '/statistics', label: t('nav.statistics'), permission: 'statistics:view', icon: 'chartBar' }, { path: '/logs', label: t('nav.operationLogs'), permission: 'log:view', icon: 'terminal' }, { path: '/settings', label: t('nav.systemSettings'), permission: 'system:setting', icon: 'cog', exact: true }, diff --git a/frontend/src/components/oa/FormFieldControl.vue b/frontend/src/components/oa/FormFieldControl.vue index 3faad54..b649d84 100644 --- a/frontend/src/components/oa/FormFieldControl.vue +++ b/frontend/src/components/oa/FormFieldControl.vue @@ -327,7 +327,7 @@ import LocationField from './LocationField.vue' import MarkdownBlock from './MarkdownBlock.vue' import RichTextEditor from './RichTextEditor.vue' import { htmlInputType } from '@/utils/formLayout' -import { WEEK_DAY_VALUES, acceptOf, displayUnit, formatNumber, locationText, monthsStyleOf, monthsText, rangeText } from '@/utils/formRuntime' +import { acceptOf, displayUnit, formatNumber, locationText, monthsStyleOf, monthsText, rangeText, weekText } from '@/utils/formRuntime' import { hasOptions } from '@/utils/formLinkage' import { carriesOptionSource, holdsListValue, pickerStyleOf, sourceKindOf } from '@/utils/optionSource' import type { DeptOption } from '@/utils/deptOptions' @@ -459,7 +459,7 @@ const display = computed(() => { if (field.type === 'daterange') return toArray(raw).filter(Boolean).join(' ~ ') if (field.type === 'timerange') return rangeText(raw) // 星期几库里存的是 1-7,念的时候要换成「周一、周三」 - if (field.type === 'week') return weekText(raw) + if (field.type === 'week') return weekText(raw, (day) => t(`form.weekday${day}`)) // 多选月份存的是 YYYY-MM 数组,念的时候要并成「2026年10-11月」这样的区间 if (field.type === 'months') return monthsText(raw) // 定位那格是物件(经纬度 + 地址),只读态念成「地址(经度, 纬度)」 @@ -523,10 +523,4 @@ function yearValue(raw: string): number | string { return Math.trunc(parsed) } -function weekText(value: unknown): string { - return toArray(value) - .filter((item) => WEEK_DAY_VALUES.includes(item)) - .map((item) => t(`form.weekday${item}`)) - .join('、') -} diff --git a/frontend/src/components/oa/HubSyncButton.preview.spec.ts b/frontend/src/components/oa/HubSyncButton.preview.spec.ts new file mode 100644 index 0000000..a5f1a26 --- /dev/null +++ b/frontend/src/components/oa/HubSyncButton.preview.spec.ts @@ -0,0 +1,254 @@ +// @vitest-environment jsdom +/** + * 「同步前体检」必须把**会动到什么**摆到台面上:熔断线、账号让位、换主键留下的壳子。 + * + * 这几条是同步侧最贵的几种动作(停人、改登录名、部门裂成两棵树),只在出事那一趟 + * 才说一句不够——按「立即同步」之前就得看得见这趟离被熔断挡下还差多少、 + * 会不会有人被改名。少摆一个数字,人就只能事后翻同步记录。 + */ +import { beforeEach, describe, expect, it, vi } from 'vitest' +import { flushPromises, mount } from '@vue/test-utils' +import { createI18n } from 'vue-i18n' +import zh from '@/i18n/locales/zh' +import HubSyncButton from './HubSyncButton.vue' + +const api = vi.hoisted(() => ({ + getStatus: vi.fn(), + syncNow: vi.fn(), + syncRuns: vi.fn(), + syncChanges: vi.fn(), + preview: vi.fn(), + cancelSync: vi.fn() +})) + +const orgApi = vi.hoisted(() => ({ cleanupShellUnits: vi.fn(), listShellUnits: vi.fn() })) + +const stores = vi.hoisted(() => ({ success: vi.fn(), error: vi.fn(), can: vi.fn(() => true) })) + +vi.mock('@/api', () => ({ hubAPI: api, orgAPI: orgApi })) +vi.mock('@/stores/app', () => ({ useAppStore: () => ({ success: stores.success, error: stores.error }) })) +vi.mock('@/stores/auth', () => ({ + useAuthStore: () => ({ user: { display_name: '管理员', account: 'admin' }, isAdmin: true, can: stores.can }) +})) + +function previewOf(patch: Record = {}) { + return { + credential: 'directory_key', + credential_label: '目录密钥(X-Directory-Key)', + permission_version: 74, + total_users: 99, + returned_users: 99, + member_limit: 5000, + truncated: false, + organizations: { + total: 14, + new: 0, + known: 14, + disabled: 0, + offboard_candidates: 1, + offboard_pending: 1, + offboard_guard: { percent: 40, ceiling: 5, min_units: 5, tripped: false }, + zombie_units: 2, + zombie_units_deletable: 2, + zombie_unit_samples: [{ id: 203, name: '紫光汇智', code: '1001', blockers: [] }], + renamed: 1, + moved: 0, + local_units: 3, + claimable_by_code: 0, + local_hanging_units: 0, + ...patch + }, + users: { + new: 0, + adopt_candidates: 0, + inactive: 0, + unassigned: 0, + protected_admins: 1, + offboard_candidates: 30, + offboard_pending: 30, + offboard_guard: { percent: 40, ceiling: 39, min_people: 20, tripped: false }, + no_hub_id: 0, + account_conflicts: 2, + account_releases: 4, + account_releases_allowed: true, + account_release_floor: 49, + account_renames: 3, + name_renames: 5, + unbound: 0, + with_mobile: 0, + mobile_invalid: 0, + mobile_note: '', + ...(patch as Record) + }, + offboard_accounts: [], + organization_sample: [], + warning: '' + } +} + +function statusOf(patch: Record = {}) { + return { + enabled: true, + configured: true, + base_url: 'https://hub.example', + login_mode: 'hub', + login_enabled: true, + auto_provision: true, + verify_token: true, + sync_enabled: true, + member_limit: 5000, + credential: 'directory_key', + credential_label: '目录密钥(X-Directory-Key)', + running: false, + last_run: null, + changes: { enabled: false }, + ...patch + } +} + +function mountButton() { + const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh } }) + return mount(HubSyncButton, { + global: { + plugins: [i18n], + stubs: { + RouterLink: true, + // 体检结果就在这个对话框里,stub 成透传容器才看得见内容 + BaseDialog: { template: '
' } + } + } + }) +} + +/** 把「标签 -> 数字」这两行凑成一张表,断言时按标签取值,不靠整页文本猜。 */ +function cellsOf(wrapper: ReturnType): Record { + const out: Record = {} + wrapper.findAll('div.rounded-xl').forEach((cell) => { + const [label, value] = cell.findAll('p') + if (label && value) out[label.text()] = value.text() + }) + return out +} + +async function openPreview(patch: Record = {}) { + api.getStatus.mockResolvedValue(statusOf()) + api.syncRuns.mockResolvedValue([]) + api.preview.mockResolvedValue(previewOf(patch)) + const wrapper = mountButton() + await flushPromises() + const button = wrapper.findAll('button').find((entry) => entry.text().includes('体检')) + await button!.trigger('click') + await flushPromises() + return wrapper +} + +async function clickButton(wrapper: ReturnType, label: string) { + const button = wrapper.findAll('button').find((entry) => entry.text().includes(label)) + await button!.trigger('click') + await flushPromises() +} + +beforeEach(() => { + api.getStatus.mockReset() + orgApi.cleanupShellUnits.mockReset() + orgApi.listShellUnits.mockReset() + api.syncRuns.mockReset() + api.preview.mockReset() + stores.success.mockReset() + stores.error.mockReset() + stores.can.mockReset() + stores.can.mockReturnValue(true) +}) + +describe('同步前体检里的风险数字', () => { + it('熔断上限没跨过也摆出来:这一趟离挡下还差多少', async () => { + const wrapper = await openPreview() + const text = wrapper.text() + // 光说"40%"不够:人数少的库里上限是被那个"不少于 N"的底线抬起来的, + // 管理员照百分比自己算会算出一个更小的数,然后奇怪为什么没被挡下 + expect(text).toContain('离职停用熔断:40%(且不少于 20 人),这趟最多停 39 人;预计停用 30 人') + expect(text).toContain('部门停用熔断:40%(且不少于 5 个),这趟最多停 5 个;预计停用 1 个') + }) + + it('真会停用多少人、让出几个登录名,逐个数字摆在格子里', async () => { + const cells = cellsOf(await openPreview()) + expect(cells['这趟真停用']).toBeDefined() + expect(cells['僵尸账号让位']).toBe('4') + expect(cells['登录名改名']).toBe('3') + expect(cells['姓名改名']).toBe('5') + expect(cells['登录名冲突']).toBe('2') + expect(cells['受保护跳过']).toBe('1') + expect(cells['重名壳子部门']).toBe('2') + expect(cells['本地自建部门']).toBe('3') + }) + + it('壳子部门要点名到是谁:那是要人自己去解绑删除的', async () => { + const wrapper = await openPreview() + expect(wrapper.text()).toContain('重名壳子:') + expect(wrapper.text()).toContain('紫光汇智') + }) + + it('清单人数不够时讲清楚为什么这趟不动登录名', async () => { + const wrapper = await openPreview({ account_releases_allowed: false, account_release_floor: 49 }) + expect(wrapper.text()).toContain('这一趟不会动任何人的登录名') + expect(wrapper.text()).toContain('49') + }) + + it('有空壳可删时给出一键清理,删完重新体检', async () => { + const confirm = vi.spyOn(window, 'confirm').mockReturnValue(true) + orgApi.cleanupShellUnits.mockResolvedValue({ + dry_run: false, + deleted: [{ id: '203', name: '紫光汇智', code: '1001', hub_org_id: '88' }], + skipped: [] + }) + const wrapper = await openPreview() + expect(wrapper.text()).toContain('清理 2 个空壳部门') + await clickButton(wrapper, '清理 2 个空壳部门') + expect(orgApi.cleanupShellUnits).toHaveBeenCalled() + expect(stores.success).toHaveBeenCalledWith(expect.stringContaining('已删除 1 个空壳部门')) + // 删完必须重新体检:壳子那几格与「这趟会不会停部门」都跟着变了 + expect(api.preview.mock.calls.length).toBe(2) + confirm.mockRestore() + }) + + it('一具都删不掉时不摆清理按钮,并把删不掉的原因挂在壳子名字上', async () => { + const wrapper = await openPreview({ + zombie_units_deletable: 0, + zombie_unit_samples: [{ id: 203, name: '紫光汇智', code: '1001', blockers: ['直属人员 3 人'] }] + }) + expect(wrapper.text()).not.toContain('清理 ') + const chip = wrapper.findAll('.badge').find((entry) => entry.text().includes('紫光汇智')) + expect(chip?.attributes('title')).toContain('直属人员 3 人') + }) + + it('后端还没给 zombie_units_deletable 时不摆按钮:不拿全部壳子去赌删除安全', async () => { + const wrapper = await openPreview({ zombie_units_deletable: undefined }) + expect(wrapper.text()).not.toContain('清理 ') + }) + + it('后端还没给这些新字段时不炸,只是格子空着', async () => { + api.getStatus.mockResolvedValue(statusOf()) + api.syncRuns.mockResolvedValue([]) + api.preview.mockResolvedValue({ + credential: 'directory_key', + credential_label: '', + permission_version: 1, + total_users: 10, + returned_users: 10, + member_limit: 5000, + truncated: false, + organizations: { total: 2, new: 0, known: 2, disabled: 0, offboard_candidates: 0 }, + users: { new: 0, adopt_candidates: 0, inactive: 0, unassigned: 0, protected_admins: 0, offboard_candidates: 0 }, + offboard_accounts: [], + organization_sample: [], + warning: '' + }) + const wrapper = mountButton() + await flushPromises() + const button = wrapper.findAll('button').find((entry) => entry.text().includes('体检')) + await button!.trigger('click') + await flushPromises() + expect(wrapper.text()).toContain('组织') + expect(stores.error).not.toHaveBeenCalled() + }) +}) diff --git a/frontend/src/components/oa/HubSyncButton.vue b/frontend/src/components/oa/HubSyncButton.vue index cb4ebe4..e81a6c4 100644 --- a/frontend/src/components/oa/HubSyncButton.vue +++ b/frontend/src/components/oa/HubSyncButton.vue @@ -86,7 +86,16 @@ {{ statusLabel(row.status) }} - {{ summaryOf(row) }} + + {{ summaryOf(row) }} + + {{ line }} + + {{ t('common.noData') }} @@ -120,6 +129,34 @@ +
+
+ {{ t('hub.zombieUnitsSample') }} + {{ unit.name }} +
+
+ + {{ t('hub.cleanShellsHint') }} +
+
+
    +
  • + {{ note }} +
  • +

{{ previewData.users.mobile_note }}

@@ -145,10 +182,10 @@ import { computed, onMounted, ref } from 'vue' import { useI18n } from 'vue-i18n' import BaseDialog from '@/components/common/BaseDialog.vue' import Icon from '@/components/icons/Icon.vue' -import { hubAPI } from '@/api' +import { hubAPI, orgAPI } from '@/api' import type { HubDirectoryPreview, HubStatus, HubSyncResult, HubSyncRun } from '@/api/hub' import { useAuthStore } from '@/stores/auth' -import { describeCancelResult, syncLooksStuck } from '@/utils/hubSync' +import { describeCancelResult, describeRunDetails, describeRunSummary, syncLooksStuck } from '@/utils/hubSync' import { errorMessage } from '@/utils/oa' import { useAppStore } from '@/stores/app' @@ -168,6 +205,7 @@ const showPreview = ref(false) const previewData = ref(null) const pulling = ref(false) const cancelling = ref(false) +const cleaning = ref(false) // 只有开了统一身份、且当前用户管得到人员,才摆这个按钮 const visible = computed(() => status.value?.enabled === true && authStore.can('org:person')) @@ -238,7 +276,11 @@ const previewGroups = computed(() => { { label: t('hub.cntTotal'), value: view.organizations.total }, { label: t('hub.cntNew'), value: view.organizations.new }, { label: t('hub.cntKnown'), value: view.organizations.known }, - { label: t('hub.cntOffboard'), value: view.organizations.offboard_candidates } + { label: t('hub.cntRenamed'), value: view.organizations.renamed }, + { label: t('hub.cntOffboard'), value: view.organizations.offboard_candidates }, + { label: t('hub.cntOffboardReal'), value: view.organizations.offboard_pending }, + { label: t('hub.cntZombieUnits'), value: view.organizations.zombie_units }, + { label: t('hub.cntLocalUnits'), value: view.organizations.local_units } ] }, { @@ -247,14 +289,58 @@ const previewGroups = computed(() => { { label: t('hub.cntNew'), value: view.users.new }, { label: t('hub.cntAdopt'), value: view.users.adopt_candidates }, { label: t('hub.cntOffboard'), value: view.users.offboard_candidates }, + { label: t('hub.cntOffboardReal'), value: view.users.offboard_pending }, + { label: t('hub.cntAccountRenames'), value: view.users.account_renames }, + { label: t('hub.cntNameRenames'), value: view.users.name_renames }, + { label: t('hub.cntAccountReleases'), value: view.users.account_releases }, + { label: t('hub.cntAccountConflicts'), value: view.users.account_conflicts }, { label: t('hub.cntInactive'), value: view.users.inactive }, { label: t('hub.cntUnassigned'), value: view.users.unassigned }, + { label: t('hub.cntProtected'), value: view.users.protected_admins }, { label: t('hub.cntMobile'), value: view.users.with_mobile } ] } ] }) +/** + * 熔断与"这趟让不让位"是两个会改变结果的口径,光看数字格子看不出来,单独拼成句子。 + * + * 熔断线没跨过的时候也要摆出来:管理员真正想知道的是"这趟离被挡下还差多少", + * 只在被挡下那一刻才说话,等于让人拿一次事故换一次提示。 + */ +const previewNotes = computed(() => { + const view = previewData.value + if (!view) return [] + const notes: string[] = [] + const peopleGuard = view.users.offboard_guard + if (peopleGuard?.percent) { + notes.push( + t('hub.guardNotePeople', { + percent: peopleGuard.percent, + floor: peopleGuard.min_people, + ceiling: peopleGuard.ceiling, + pending: view.users.offboard_pending + }) + ) + } + const unitGuard = view.organizations.offboard_guard + if (unitGuard?.percent) { + notes.push( + t('hub.guardNoteUnits', { + percent: unitGuard.percent, + floor: unitGuard.min_units, + ceiling: unitGuard.ceiling, + pending: view.organizations.offboard_pending + }) + ) + } + if (view.users.account_releases_allowed === false) { + notes.push(t('hub.releaseBlockedNote', { floor: view.users.account_release_floor })) + } + return notes +}) + function statusLabel(value: string): string { const key = `hub.status_${value}` const label = t(key) @@ -269,13 +355,11 @@ function statusClass(value: string): string { } function summaryOf(row: HubSyncRun): string { - if (row.status === 'skipped') return t('hub.skipped') - if (!row.created && !row.updated && !row.offboarded && row.unchanged) return t('hub.unchanged') - return [ - `${t('hub.created')} ${row.created}`, - `${t('hub.updated')} ${row.updated}`, - `${t('hub.offboarded')} ${row.offboarded}` - ].join(' · ') + return describeRunSummary(row, t) +} + +function detailsOf(row: HubSyncRun): string[] { + return describeRunDetails(row, t) } async function load() { @@ -286,6 +370,29 @@ async function load() { } } +/** 能一键删掉的壳子数:后端没给这个字段时按 0 处理,不拿全部壳子去赌删除安全。 */ +const deletableShells = computed(() => previewData.value?.organizations.zombie_units_deletable ?? 0) + +async function cleanShells() { + if (cleaning.value) return + if (!window.confirm(t('hub.cleanShellsConfirm', { value: deletableShells.value }))) return + cleaning.value = true + try { + const result = await orgAPI.cleanupShellUnits() + appStore.success( + result.skipped.length + ? t('hub.cleanShellsDoneSkipped', { deleted: result.deleted.length, skipped: result.skipped.length }) + : t('hub.cleanShellsDone', { value: result.deleted.length }) + ) + // 重新体检:壳子那几格与「会不会停用部门」都跟着变了 + previewData.value = await hubAPI.preview() + } catch (error) { + appStore.error(errorMessage(error)) + } finally { + cleaning.value = false + } +} + async function preview() { if (previewing.value) return previewing.value = true diff --git a/frontend/src/components/oa/SyncJobPanel.vue b/frontend/src/components/oa/SyncJobPanel.vue index 2e16887..5cbc5a9 100644 --- a/frontend/src/components/oa/SyncJobPanel.vue +++ b/frontend/src/components/oa/SyncJobPanel.vue @@ -45,6 +45,13 @@

{{ job.last_run.trigger_label }} · {{ summary }}

+

+ {{ line }} +

{{ t('syncSchedule.neverRun') }}

@@ -66,6 +73,7 @@ import { computed } from 'vue' import { useI18n } from 'vue-i18n' import Icon from '@/components/icons/Icon.vue' import type { HubScheduleJob } from '@/api/hub' +import { describeRunDetails, describeRunSummary } from '@/utils/hubSync' const props = defineProps<{ job?: HubScheduleJob @@ -127,16 +135,10 @@ const cursorText = computed(() => { return changes.lag ? `${changes.cursor} · ${t('hub.changesLag', { value: changes.lag })}` : String(changes.cursor) }) -const summary = computed(() => { - const run = props.job?.last_run - if (!run) return '' - if (run.trigger === 'changes') return t('hub.changesAppliedCount', { value: run.changes_applied }) - return [ - `${t('hub.created')} ${run.created}`, - `${t('hub.updated')} ${run.updated}`, - `${t('hub.units')} ${run.units_created}/${run.units_updated}` - ].join(' · ') -}) +// 这一句与「同步定时任务」的执行记录、页头同步结果框共用同一个函数: +// 三处以前各写一份,改名与账号让位两边都不报,而这两类恰恰最要人去核对 +const summary = computed(() => (props.job?.last_run ? describeRunSummary(props.job.last_run, t) : '')) +const details = computed(() => (props.job?.last_run ? describeRunDetails(props.job.last_run, t) : [])) function statusLabel(value: string): string { const key = `hub.status_${value}` diff --git a/frontend/src/components/oa/mobile/MobileFold.vue b/frontend/src/components/oa/mobile/MobileFold.vue index 15a0a1d..cdbb241 100644 --- a/frontend/src/components/oa/mobile/MobileFold.vue +++ b/frontend/src/components/oa/mobile/MobileFold.vue @@ -1,6 +1,7 @@ @@ -19,6 +20,10 @@ /** * 折叠块:手机上「默认收起、点了才展开」的唯一实现。 * + * 不给标题(`title` 传空串)就是**一块不折叠的内容**:那一行连箭头一起不摆,内容直接摊开。 + * 表单那一节的名字没配过时走这一档——上面那排页签已经写着「表单内容」, + * 同一句话不该在 390px 上占两行(还搭上一颗没用的折叠箭头)。 + * * 一张 47 个字段的单子全摊开是六屏,领导真正要看的就两三样。折叠的粒度按流程设计里 * 本来就有的分隔条走(divider 字段就是分节标题),不额外发明一层「移动分组」配置—— * 设计器里改一分组,手机上跟着变,不会出现桌面改了手机上没改。 diff --git a/frontend/src/components/oa/mobile/MobileFormReader.spec.ts b/frontend/src/components/oa/mobile/MobileFormReader.spec.ts index b4ac9da..20e594d 100644 --- a/frontend/src/components/oa/mobile/MobileFormReader.spec.ts +++ b/frontend/src/components/oa/mobile/MobileFormReader.spec.ts @@ -116,6 +116,36 @@ describe('手机上「完整单据」那一屏', () => { expect(table.text()).toContain('高铁上海→北京往返二等座') // 第 2 条没写备注:那一列不占一行 expect(table.text()).not.toContain('第 2 条\n备注') + // 金额列按列上的格式写「1,129.00」,不摊出库里那个 1129 + expect(table.text()).toContain('1,129.00') + }) + + it('节名是兜底来的那一节不摆标题行:页签上已经写着「表单内容」', () => { + const wrapper = mount(MobileFormReader, { + props: { schema: { fields: [field({ key: 'reason', label: '报销事由', type: 'textarea' })] } as FormSchema, data: { reason: '出差' } }, + global + }) + // 既没分页也没分隔条:整张表就一节,那一行连「N 项」和折叠箭头一起不摆 + expect(wrapper.findAll('[aria-expanded]')).toHaveLength(0) + expect(wrapper.text()).not.toContain('表单内容') + expect(visibleText(wrapper)).toContain('报销事由出差') + }) + + it('好几节的时候兜底那节照摆标题:那时候节名是把正文分开的记号', () => { + const wrapper = mount(MobileFormReader, { + props: { + schema: { + fields: [ + field({ key: 'serial_no', label: '单号', type: 'auto' }), + field({ key: 'reason', label: '报销事由', type: 'textarea' }) + ] + } as FormSchema, + data: { serial_no: 'BX-1', reason: '出差' } + }, + global + }) + // 「系统取数」起了名字,兜底的「表单内容」也就得跟着起,两节才分得开 + expect(wrapper.findAll('[aria-expanded]').map((node) => node.text())).toEqual(['系统取数1 项', '表单内容1 项']) }) it('一张空表单也不炸', () => { diff --git a/frontend/src/components/oa/mobile/MobileFormReader.vue b/frontend/src/components/oa/mobile/MobileFormReader.vue index 913edc1..ce17a7e 100644 --- a/frontend/src/components/oa/mobile/MobileFormReader.vue +++ b/frontend/src/components/oa/mobile/MobileFormReader.vue @@ -10,7 +10,7 @@ diff --git a/frontend/src/components/oa/mobile/MobileFormSummary.spec.ts b/frontend/src/components/oa/mobile/MobileFormSummary.spec.ts index b34b2ef..6b7d855 100644 --- a/frontend/src/components/oa/mobile/MobileFormSummary.spec.ts +++ b/frontend/src/components/oa/mobile/MobileFormSummary.spec.ts @@ -104,6 +104,16 @@ describe('MobileFormSummary:一屏读不完的都得折起来', () => { expect(rowsTexts(wrapper)).toHaveLength(6) }) + it('节名是兜底来的那一节不摆标题行,正文一行不少', () => { + const wrapper = render({ + groups: [{ name: '表单内容', generic: true, items: Array.from({ length: 4 }, (_, index) => item(index + 1)) }] + }) + // 那一行标题(连带「N 项」与折叠箭头)整个不摆,页签上已经写着这三个字 + expect(wrapper.findAll('[aria-expanded]')).toHaveLength(0) + expect(wrapper.text()).not.toContain('表单内容') + expect(rowsTexts(wrapper)).toHaveLength(4) + }) + it('明细只占一行(条数与合计都在那一行上),完整单据说清楚折了多少空值', () => { const wrapper = render() const table = wrapper.findAll('button').find((btn) => btn.text().includes('费用明细')) @@ -164,6 +174,22 @@ describe('MobileFormSummary:配了手机端版式就只有一节', () => { expect(labels).toEqual(['报销事由', '报销金额', '发起人', '备注']) }) + it('节名没配就不摆那一行标题:页签上已经写着「表单内容」', () => { + const wrapper = renderMobile({ ...ORDER, title: '' }) + expect(wrapper.text()).not.toContain('表单内容') + // 标题行没了,那颗折叠箭头也跟着没:这一节从头到尾就是正文 + expect(wrapper.findAll('[aria-expanded]')).toHaveLength(0) + // 正文一行不少,顺序照配置 + expect(wrapper.findAll('[data-test="m-row"]').map((row) => row.findAll('p')[0].text())).toEqual([ + '报销事由', + '报销金额', + '发起人', + '备注' + ]) + // 对照:配了名字的节照旧摆标题 + expect(renderMobile(ORDER).findAll('[aria-expanded]')).toHaveLength(1) + }) + it('十二格也不再折叠:点名要的格子不该被「展开更早 N 条」收起来', () => { const many: MobileLayout = { enabled: true, diff --git a/frontend/src/components/oa/mobile/MobileFormSummary.vue b/frontend/src/components/oa/mobile/MobileFormSummary.vue index 19060fd..a5bca87 100644 --- a/frontend/src/components/oa/mobile/MobileFormSummary.vue +++ b/frontend/src/components/oa/mobile/MobileFormSummary.vue @@ -9,7 +9,7 @@ @@ -137,7 +137,7 @@ @@ -258,6 +258,17 @@ const opened = ref>(new Set()) // 换一张单子(分节数会变)时把展开状态清回去,别让上一张的展开留在这一张上 watch(() => props.plan.total, () => (opened.value = new Set())) +/** + * 这一节要不要标题行。 + * + * 只有一节、而那一节的名字还是代码兜底补的(`generic`),就不摆:上面那排页签已经写着 + * 「表单内容」,同一句话在 390 的屏上占两行,还搭上「N 项」和一颗没用的折叠箭头。 + * 好几节的时候照旧摆——那时候节名是把正文分开的记号,撤了反而读不出哪段是哪段。 + */ +function bare(group: PlanGroup): boolean { + return Boolean(group.generic) && props.plan.groups.length === 1 +} + function isOpen(name: string): boolean { return opened.value.has(name) } diff --git a/frontend/src/components/oa/mobile/MobileTaskView.spec.ts b/frontend/src/components/oa/mobile/MobileTaskView.spec.ts index e1947a7..40d5b42 100644 --- a/frontend/src/components/oa/mobile/MobileTaskView.spec.ts +++ b/frontend/src/components/oa/mobile/MobileTaskView.spec.ts @@ -48,7 +48,15 @@ async function render(view = stubView(expenseDetail())) { } }) await flushPromises() - return { wrapper, view } + return { wrapper, view, router: r } +} + +/** 从屏底「···」里点某一行动作,走的是人真会走的那条路。 */ +async function openMore(wrapper: Awaited>['wrapper'], label: string) { + await wrapper.find('[data-test="m-more"]').trigger('click') + const menu = wrapper.find('[data-test="m-menu"]') + await menu.findAll('button').find((btn) => btn.text().includes(label))!.trigger('click') + await flushPromises() } /** 从屏底那颗「同意」走到意见弹层:两条出口这一档要先挑一条。 */ @@ -123,16 +131,57 @@ describe('手机上的审批页', () => { }) it('提交这一步整个交给桌面那份逻辑,手机上不多算一遍', async () => { - api.listProcessing.mockResolvedValue({ items: [], total: 0, page: 1, page_size: 2, pages: 0 }) const { wrapper, view } = await render() await approveFlow(wrapper) await wrapper.find('[data-test="m-submit"]').trigger('click') await flushPromises() expect(view.calls.map((call) => call.name)).toContain('submit') - // 手上一条不剩,就回待办列表,不把人留在一张办完的单子上 expect(view.calls.filter((call) => call.name === 'submit')).toHaveLength(1) }) + it('批完就关掉这张单子回待办列表,不再自动塞进下一条', async () => { + // 手上还剩别的单子:落点仍是列表,而不是另一张陌生的单据 + api.listProcessing.mockResolvedValue({ + items: [{ id: 'task-9', title: '另一条待办' }], + total: 1, + page: 1, + page_size: 2, + pages: 1 + }) + const { wrapper, router } = await render() + await approveFlow(wrapper) + await wrapper.find('[data-test="m-submit"]').trigger('click') + await flushPromises() + expect(router.currentRoute.value.name).toBe('my-todo') + // 列表那一屏自己挂载、自己取数,这一屏不再为「下一条」多打一次接口 + expect(api.listProcessing).not.toHaveBeenCalled() + }) + + it('转办把人送回待办列表,加签留在原处刷新:单子有没有离开手里,两条路不一样', async () => { + const transfer = await render() + await openMore(transfer.wrapper, '转办') + await transfer.wrapper.find('[data-test="m-people-confirm"]').trigger('click') + await flushPromises() + expect(transfer.router.currentRoute.value.name).toBe('my-todo') + + const add = await render() + await openMore(add.wrapper, '加签') + await add.wrapper.find('[data-test="m-people-confirm"]').trigger('click') + await flushPromises() + // 加签之后这条待办还在自己手里:就地取一次,别把人甩到「已办」那一屏 + expect(add.view.calls.map((call) => call.name)).toContain('reload') + expect(add.router.currentRoute.value.name).toBe('todo-detail') + }) + + it('退回也算办完这一环,同样回待办列表', async () => { + const { wrapper, view, router } = await render() + await wrapper.find('[data-test="m-goback"]').trigger('click') + await wrapper.find('[data-test="m-goback-confirm"]').trigger('click') + await flushPromises() + expect(view.calls.map((call) => call.name)).toContain('confirmGoBack') + expect(router.currentRoute.value.name).toBe('my-todo') + }) + it('退回带得上目标与方式,加签抄送分享都从更多里够得着', async () => { const { wrapper, view } = await render() await wrapper.find('[data-test="m-goback"]').trigger('click') diff --git a/frontend/src/components/oa/mobile/MobileTaskView.vue b/frontend/src/components/oa/mobile/MobileTaskView.vue index 374eddb..26439a6 100644 --- a/frontend/src/components/oa/mobile/MobileTaskView.vue +++ b/frontend/src/components/oa/mobile/MobileTaskView.vue @@ -76,7 +76,7 @@ >

{{ t('task.nodeDecisionBanner', { app: item.appName || item.app, action: item.kindLabel, route: item.route }) }}

- +
@@ -265,7 +265,7 @@ @@ -303,7 +303,7 @@ @@ -372,7 +372,7 @@ @@ -446,7 +446,7 @@ diff --git a/frontend/src/views/auth/SsoCallbackView.landing.spec.ts b/frontend/src/views/auth/SsoCallbackView.landing.spec.ts new file mode 100644 index 0000000..9bc8d62 --- /dev/null +++ b/frontend/src/views/auth/SsoCallbackView.landing.spec.ts @@ -0,0 +1,140 @@ +// @vitest-environment jsdom +/** + * 企业微信卡片点开之后的最后那一跳:落地页把人送到哪一页。 + * + * 前面几段(OA 推 Hub、Hub 换企微、Hub 认点击人)在 `backend/scripts/check_notify_*.py` + * 那三份里钉着,这一份只管最后半米:Hub 302 回来时地址上带的那一样东西,怎么变成 + * "人就站在那条待办面前"。三条形态都要走对: + * + * * ``/sso#code=…``:``launch_url`` 填的是后端回调(``/sso/hub``),后端验完票给一条短码, + * 会话与落地页都由 ``POST /auth/sso/exchange`` 一起回(推送链路的深链就在这儿回来); + * * ``/sso?ticket=…&redirect=…``:``launch_url`` 直接填前端路由,票据由这一页交给后端验, + * 落地页取地址栏上那一个; + * * ``/sso?error=…``:后端当场把票拒了(比如开了「免登必须校验 state」而企微那一路不带 + * state),这一屏只说一句话,**一次请求都不许多发**。 + * + * 还钉一条安全边界:``redirect`` 是 Hub 原样带回来的,写成外站就一律不进, + * 落回系统自己的第一屏,绝不把人送去别人的域名。 + */ +import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest' +import { flushPromises, mount } from '@vue/test-utils' +import { createPinia, setActivePinia } from 'pinia' +import { createMemoryHistory, createRouter } from 'vue-router' +import { createI18n } from 'vue-i18n' +import zh from '@/i18n/locales/zh' +import { useAppStore, useAuthStore } from '@/stores' +import { rememberReturnPath, takeReturnPath } from '@/utils/ssoJump' +import SsoCallbackView from './SsoCallbackView.vue' + +vi.mock('@/api/auth', () => ({ ssoBegin: vi.fn(async () => ({ portal_url: 'https://hub.example.com' })) })) + +function stub() { + const loginWithCode = vi.fn() + const loginWithTicket = vi.fn() + const pinia = createPinia() + setActivePinia(pinia) + const auth = useAuthStore() + const app = useAppStore() + vi.spyOn(auth, 'loginWithCode').mockImplementation(loginWithCode) + vi.spyOn(auth, 'loginWithTicket').mockImplementation(loginWithTicket) + // 落地页兜底要按权限挑第一屏,这一份只关心"别落到外站",给一个够用的最小权限 + vi.spyOn(auth, 'can').mockImplementation((code: string) => code === 'work:todo') + vi.spyOn(app, 'fetchPublicSettings').mockResolvedValue({ hub: { portal_url: 'https://hub.example.com' } } as never) + return { auth, loginWithCode, loginWithTicket } +} + +async function open(target: string, double: ReturnType) { + const router = createRouter({ + history: createMemoryHistory(), + routes: [ + { path: '/sso', name: 'sso-callback', component: SsoCallbackView }, + { path: '/todo/:id', name: 'todo-detail', component: { template: '
' } }, + { path: '/todo', name: 'my-todo', component: { template: '
' } }, + { path: '/work/:job', name: 'work-detail', component: { template: '
' } }, + { path: '/workbench', name: 'workbench', component: { template: '
' } }, + { path: '/profile', name: 'profile', component: { template: '
' } }, + { path: '/home', name: 'portal-home', component: { template: '
' } }, + { path: '/login', name: 'login', component: { template: '
' } } + ] + }) + await router.push(target) + await router.isReady() + const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh } }) + const wrapper = mount(SsoCallbackView, { + global: { plugins: [router, i18n], + // 版面壳子不影响这一跳的判断,但它的 slot 必须渲染出来,否则屏上那句说明就没了 + stubs: { AuthLayout: { template: '
' }, LocaleSwitcher: true } } + }) + await flushPromises() + return { wrapper, router } +} + +beforeAll(() => { + // 兜底那一屏按手机还是桌面挑法不同,两者都靠 matchMedia 分家 + window.matchMedia = ((query: string) => ({ + matches: false, media: query, onchange: null, + addListener: () => {}, removeListener: () => {}, + addEventListener: () => {}, removeEventListener: () => {}, dispatchEvent: () => false + })) as unknown as typeof window.matchMedia +}) + +beforeEach(() => { + localStorage.clear() + sessionStorage.clear() +}) + +describe('企业微信卡片点开之后的落地', () => { + it('后端回调那条:短码换到会话,人直接站在那条待办面前', async () => { + const double = stub() + double.loginWithCode.mockResolvedValue({ user: {}, redirect: '/todo/task-9' }) + const { router } = await open('/sso#code=SHORT-CODE-1', double) + expect(double.loginWithCode).toHaveBeenCalledWith('SHORT-CODE-1') + expect(double.loginWithTicket).not.toHaveBeenCalled() + expect(router.currentRoute.value.path).toBe('/todo/task-9') + }) + + it('前端路由那条:验票成功后落地址栏带来的深链', async () => { + const double = stub() + double.loginWithTicket.mockResolvedValue({}) + const { router } = await open('/sso?ticket=T-1&state=&redirect=/work/job-77', double) + expect(double.loginWithTicket).toHaveBeenCalledWith('T-1', '') + expect(router.currentRoute.value.path).toBe('/work/job-77') + }) + + it('Hub 没带回 redirect:接住登录页跳出去之前存下的来路', async () => { + const double = stub() + double.loginWithTicket.mockResolvedValue({}) + rememberReturnPath('/work/job-88') + const { router } = await open('/sso?ticket=T-3', double) + expect(router.currentRoute.value.path).toBe('/work/job-88') + // 取一次即清:这一份只管这一次落地,下一次进站该落哪页重新算 + expect(takeReturnPath()).toBe('') + }) + + it('地址栏带来的 redirect 比存着的那一份优先', async () => { + const double = stub() + double.loginWithCode.mockResolvedValue({ user: {}, redirect: '' }) + rememberReturnPath('/workbench') + const { router } = await open('/sso?ticket=T-4&redirect=%2Ftodo%2Ftask-5', double) + expect(router.currentRoute.value.path).toBe('/todo/task-5') + }) + + it('redirect 写成外站就不进:落回系统自己的第一屏', async () => { + const double = stub() + double.loginWithTicket.mockResolvedValue({}) + const { router } = await open('/sso?ticket=T-2&redirect=%2F%2Fevil.example.com%2Fx', double) + const landed = router.currentRoute.value.fullPath + expect(landed).not.toContain('evil.example.com') + expect(landed.startsWith('/')).toBe(true) + }) + + it('后端拒票那一屏:一句话说明,一次登录请求都不发', async () => { + const double = stub() + const { wrapper, router } = await open('/sso?error=SSO_STATE_REJECTED', double) + expect(double.loginWithCode).not.toHaveBeenCalled() + expect(double.loginWithTicket).not.toHaveBeenCalled() + expect(router.currentRoute.value.path).toBe('/sso') + expect(wrapper.text()).toContain('SSO_STATE_REJECTED') + expect(wrapper.text()).toContain(zh.auth.ssoErrState) + }) +}) diff --git a/frontend/src/views/auth/SsoCallbackView.vue b/frontend/src/views/auth/SsoCallbackView.vue index 2634993..62255ce 100644 --- a/frontend/src/views/auth/SsoCallbackView.vue +++ b/frontend/src/views/auth/SsoCallbackView.vue @@ -73,6 +73,7 @@ import { leaveToPortal } from '@/utils/portal' import { useAuthStore } from '@/stores/auth' import { useAppStore } from '@/stores/app' import { safeRedirect } from '@/utils/returnPath' +import { resetAutoJumpBudget, takeReturnPath } from '@/utils/ssoJump' import { errorMessage } from '@/utils/oa' const { t } = useI18n() @@ -100,9 +101,12 @@ function scrubTicketFromUrl(): void { window.history.replaceState({}, document.title, window.location.pathname) } -function targetPath(): string { +function targetPath(sessionRedirect = ''): string { + // 来路三个来源按顺位取:后端回调带回来的 > 地址栏上的 > 跳去门户之前自己存的那一份 + // (Hub 一期不解析 redirect,登录页无感跳出去时把来路暂存在了 ssoJump 里) + const wanted = firstText(sessionRedirect) || firstText(route.query.redirect) || takeReturnPath() // 只认站内路径:`//` 与 `/\` 这类写法会被浏览器送去另一台主机 - return safeRedirect(route.query.redirect) + return safeRedirect(wanted) } async function toPortal() { @@ -159,11 +163,13 @@ async function run() { if (entryKind.value === 'code') { const session = await authStore.loginWithCode(code) scrubTicketFromUrl() - await router.replace(safeRedirect(session.redirect || route.query.redirect)) + resetAutoJumpBudget() + await router.replace(targetPath(session.redirect)) return } await authStore.loginWithTicket(ticket, state) scrubTicketFromUrl() + resetAutoJumpBudget() await router.replace(targetPath()) } catch (error) { // 失败一律不再试第二次:票据与短码都是一次性的,重试只会得到同样的拒绝。 diff --git a/frontend/src/views/oa/NotifyChannelView.pagination.spec.ts b/frontend/src/views/oa/NotifyChannelView.pagination.spec.ts new file mode 100644 index 0000000..7adcb6e --- /dev/null +++ b/frontend/src/views/oa/NotifyChannelView.pagination.spec.ts @@ -0,0 +1,174 @@ +// @vitest-environment jsdom +/** + * 投递记录那一屏的分页。 + * + * 后端以前只回「最近 80 条」,跳过和失败堆到几百行时,第 81 条往后压根翻不到; + * 现在按 page / page_size 取,界面这一半钉的是:分页器念得出后端给的总数、点第几页 + * 就带 page=几 去要、每页条数换档要回第 1 页,而换任何筛选(状态、渠道、关键词) + * 也都得回第 1 页——停在第 9 页筛一个只剩 3 条的状态,界面上就是一片空白。 + * 顺带钉住「全部」那一格:它读的是后端 counts 里的 ''(当前筛选下的总数), + * 不再永远是 0。 + */ +import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest' +import { flushPromises, mount } from '@vue/test-utils' +import { createPinia, setActivePinia } from 'pinia' +import { createI18n } from 'vue-i18n' +import zh from '@/i18n/locales/zh' +import Pagination from '@/components/common/Pagination.vue' +import NotifyChannelView from './NotifyChannelView.vue' + +const api = vi.hoisted(() => ({ + notifyMeta: vi.fn(), + listChannels: vi.fn(), + listDeliveries: vi.fn(), + createChannel: vi.fn(), + updateChannel: vi.fn(), + deleteChannel: vi.fn(), + testChannel: vi.fn(), + resendDelivery: vi.fn(), + recheckDelivery: vi.fn(), + sendDeliveryNow: vi.fn() +})) + +vi.mock('@/api', () => ({ notifyAPI: api })) + +const META = { + kinds: [{ value: 'hub_wecom', label: '企业微信(经统一身份 Hub 推送)' }], + events: [{ value: 'task', label: '新的待办' }], + textVars: [], + smtpPresets: [], + hubMsgtypes: [{ value: 'textcard', label: '卡片(可点开直达待办)' }], + hubReceiverPresets: [{ value: ['user_id', 'account'], label: 'Hub 用户 ID 优先', hint: '默认那一档' }], + hubReceiverDefault: ['user_id', 'account'] +} + +const COUNTS = { '': 105, pending: 0, sending: 0, success: 9, failed: 0, dead: 0, skipped: 96 } + +/** 后端那一页回什么就照着头一眼的请求回:翻页、换每页条数都只动 total 之外的那几项。 */ +function pageOf(query: Record = {}) { + const pageSize = Number(query.page_size ?? 20) + const page = Number(query.page ?? 1) + return { + items: [{ + id: `d${page}`, channel: 'hub', kind: 'hub_wecom', type: 'task', typeLabel: '新的待办', + personName: '张三', target: 'zhangsan', targetFieldLabel: '登录账号', + title: `第 ${page} 页的那条待办提醒`, status: 'skipped', createTime: '2026-11-05 09:00:00', lastError: '' + }], + counts: COUNTS, + total: 105, + page, + page_size: pageSize, + pages: Math.ceil(105 / pageSize) + } +} + +function buttons(root: ParentNode): HTMLElement[] { + return Array.from(root.querySelectorAll('button')) as HTMLElement[] +} + +function click(list: HTMLElement[], text: string): void { + const hit = list.find((item) => item.textContent?.trim().includes(text)) + if (!hit) throw new Error(`找不到按钮:${text}`) + hit.click() +} + +/** 最近一次 listDeliveries 带出去的那串查询参数。 */ +function lastQuery(): Record { + const calls = api.listDeliveries.mock.calls + return (calls[calls.length - 1]?.[0] ?? {}) as Record +} + +async function openDeliveryTab() { + api.notifyMeta.mockResolvedValue(META) + api.listChannels.mockResolvedValue({ items: [], enabled: true, masterSwitch: true, hubCoverage: null }) + api.listDeliveries.mockImplementation(async (query: Record = {}) => pageOf(query)) + setActivePinia(createPinia()) + const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh }, missingWarn: false, fallbackWarn: false }) + const wrapper = mount(NotifyChannelView, { attachTo: document.body, global: { plugins: [i18n] } }) + await flushPromises() + expect(api.listDeliveries).not.toHaveBeenCalled() + click(buttons(document.body), '发送记录') + await flushPromises() + return wrapper +} + +beforeAll(() => { + // jsdom 没有 matchMedia,而 DataTable 一上来就靠它决定移动版式还是桌面板式 + window.matchMedia = ((query: string) => ({ + matches: true, + media: query, + onchange: null, + addEventListener: vi.fn(), + removeEventListener: vi.fn(), + addListener: vi.fn(), + removeListener: vi.fn(), + dispatchEvent: vi.fn() + })) as unknown as typeof window.matchMedia +}) + +beforeEach(() => { + vi.clearAllMocks() + document.body.innerHTML = '' +}) + +describe('消息渠道 · 投递记录分页', () => { + it('分页器念得出后端给的总数,「全部」那一格不再是 0', async () => { + const wrapper = await openDeliveryTab() + expect(lastQuery()).toMatchObject({ page: 1, page_size: 20 }) + expect(wrapper.text()).toContain('共') + expect(wrapper.text()).toContain('105') + expect(wrapper.text()).toContain('全部 105') + }) + + it('点第 2 页就带着 page=2 去要,不是把已经拿到手的那 20 条切一切', async () => { + const wrapper = await openDeliveryTab() + const next = wrapper.find('[aria-label="第 2 页"]') + expect(next.exists()).toBe(true) + await next.trigger('click') + await flushPromises() + expect(lastQuery()).toMatchObject({ page: 2, page_size: 20 }) + expect(wrapper.text()).toContain('第 2 页的那条待办提醒') + }) + + it('换状态筛回第 1 页:停在第 4 页筛一个只剩几条的状态,不该是一片空白', async () => { + const wrapper = await openDeliveryTab() + await wrapper.find('[aria-label="第 4 页"]').trigger('click') + await flushPromises() + expect(lastQuery()).toMatchObject({ page: 4 }) + click(buttons(document.body), '已跳过 96') + await flushPromises() + expect(lastQuery()).toMatchObject({ page: 1, status: 'skipped' }) + }) + + it('换渠道、搜关键词也都从头一页开始', async () => { + const wrapper = await openDeliveryTab() + await wrapper.find('[aria-label="第 3 页"]').trigger('click') + await flushPromises() + // SearchInput 是防抖 300ms 之后才报 keyword 的,这里等它一下而不是另接一条快路径 + await wrapper.find('input[placeholder="Search..."]').setValue('锁定校验') + await new Promise((resolve) => setTimeout(resolve, 400)) + await flushPromises() + expect(lastQuery()).toMatchObject({ page: 1, keyword: '锁定校验' }) + }) + + it('每页条数换档传的是 page_size,并且回第 1 页', async () => { + const wrapper = await openDeliveryTab() + await wrapper.find('[aria-label="第 5 页"]').trigger('click') + await flushPromises() + const pager = wrapper.findComponent(Pagination) + pager.vm.$emit('update:pageSize', 50) + await flushPromises() + expect(lastQuery()).toMatchObject({ page: 1, page_size: 50 }) + }) + + it('补发之后留在当前这一页,不把人弹回第 1 页', async () => { + const wrapper = await openDeliveryTab() + await wrapper.find('[aria-label="第 3 页"]').trigger('click') + await flushPromises() + api.resendDelivery.mockResolvedValue({}) + click(buttons(document.body), '重新排队') + await flushPromises() + expect(api.resendDelivery).toHaveBeenCalledWith('d3') + expect(lastQuery()).toMatchObject({ page: 3 }) + }) +}) diff --git a/frontend/src/views/oa/NotifyChannelView.receiver.spec.ts b/frontend/src/views/oa/NotifyChannelView.receiver.spec.ts new file mode 100644 index 0000000..87e4ed9 --- /dev/null +++ b/frontend/src/views/oa/NotifyChannelView.receiver.spec.ts @@ -0,0 +1,168 @@ +// @vitest-environment jsdom +/** + * 渠道页上「收件人标识」这一格:走统一身份 Hub 代发企业微信时按哪一列认人,现在是可配的。 + * + * Hub 认哪几种标识、默认哪一档都在后端 ``channels.HUB_RECEIVER_FIELDS`` 里,这里钉界面那一半: + * 列表里要看得见当前按哪一列认人;编辑 Hub 渠道时把那几档摊开、选中库里现存的那一档; + * 换一档保存出去的必须是 ``config.receiver`` 那根数组;覆盖人数要在换档之前就说出来; + * 投递记录里那一串标识要带着来源——10086 是 Hub 主键、zhangsan 是登录账号, + * 排查方向完全不同(前者跟着同步走,后者会被企微字段改写)。 + */ +import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest' +import { flushPromises, mount } from '@vue/test-utils' +import { createPinia, setActivePinia } from 'pinia' +import { createI18n } from 'vue-i18n' +import zh from '@/i18n/locales/zh' +import NotifyChannelView from './NotifyChannelView.vue' + +const api = vi.hoisted(() => ({ + notifyMeta: vi.fn(), + listChannels: vi.fn(), + listDeliveries: vi.fn(), + createChannel: vi.fn(), + updateChannel: vi.fn(), + deleteChannel: vi.fn(), + testChannel: vi.fn(), + resendDelivery: vi.fn(), + recheckDelivery: vi.fn(), + sendDeliveryNow: vi.fn() +})) + +vi.mock('@/api', () => ({ notifyAPI: api })) + +const META = { + kinds: [ + { value: 'hub_wecom', label: '企业微信(经统一身份 Hub 推送)' }, + { value: 'email', label: '邮件(SMTP)' } + ], + events: [{ value: 'task', label: '新的待办' }], + textVars: [], + smtpPresets: [], + hubMsgtypes: [ + { value: 'textcard', label: '卡片(可点开直达待办)' }, + { value: 'markdown', label: '纯文本提醒(不带链接)' } + ], + hub: { + ready: true, missing: [], baseUrl: 'https://hub.example.com', appCode: 'oa', keySet: true, + pushPath: '/api/v1/auth/notify/wecom/messages', forcedOff: false, timeoutSeconds: 10 + }, + hubReceivers: [ + { value: 'user_id', label: 'Hub 用户 ID', column: 'users.hub_user_id' }, + { value: 'account', label: '登录账号', column: 'users.account' } + ], + hubReceiverPresets: [ + { value: ['user_id', 'account'], label: 'Hub 用户 ID 优先', hint: '默认那一档' }, + { value: ['account', 'user_id'], label: '登录账号优先', hint: '主键不可信时用' }, + { value: ['user_id'], label: '只认 Hub 用户 ID', hint: '最严格' }, + { value: ['account'], label: '只认登录账号', hint: '一改账号就失联' } + ], + hubReceiverDefault: ['user_id', 'account'] +} + +/** 后端回的老渠道:库里没有 receiver 这一项,界面要落在默认那一档上。 */ +function channel(over: Record = {}) { + return { + id: 1, code: 'hub', name: '企业微信', kind: 'hub_wecom', + kindLabel: '企业微信(经统一身份 Hub 推送)', enabled: true, events: ['task'], + config: { msgtype: 'textcard', with_link: true, title_limit: 64 }, + receiverPref: ['user_id', 'account'], receiverLabel: 'Hub 用户 ID → 登录账号', + problems: [], today: { success: 3, failed: 0, skipped: 1 }, ...over + } +} + +const COVERAGE = { active: 108, fields: { user_id: 100, account: 108 }, any: 108, none: 8 } + +const DELIVERY = { + id: 'd1', channel: 'hub', kind: 'hub_wecom', type: 'task', typeLabel: '新的待办', + personName: '张三', target: 'zhangsan', targetField: 'account', targetFieldLabel: '登录账号', + title: '你有 1 条待办审批', status: 'success', createTime: '2026-11-05 09:00:00', lastError: '' +} + +function buttons(root: ParentNode): HTMLElement[] { + return Array.from(root.querySelectorAll('button')) as HTMLElement[] +} + +function click(list: HTMLElement[], text: string): void { + const hit = list.find((item) => item.textContent?.trim().includes(text)) + if (!hit) throw new Error(`找不到按钮:${text}`) + hit.click() +} + +async function open(rows: Record[] = [channel()]) { + api.notifyMeta.mockResolvedValue(META) + api.listChannels.mockResolvedValue({ items: rows, enabled: true, masterSwitch: true, hubCoverage: COVERAGE }) + api.listDeliveries.mockResolvedValue({ + items: [DELIVERY], counts: { '': 1, skipped: 1 }, total: 1, page: 1, page_size: 20, pages: 1 + }) + api.updateChannel.mockResolvedValue(channel()) + setActivePinia(createPinia()) + const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh }, missingWarn: false, fallbackWarn: false }) + const wrapper = mount(NotifyChannelView, { attachTo: document.body, global: { plugins: [i18n] } }) + await flushPromises() + return wrapper +} + +/** 打开那条 Hub 渠道的编辑框(对话框 teleport 到 body,只能从 document 里找)。 */ +async function editDialog(wrapper: ReturnType) { + const edit = wrapper.find('button[title="编辑"]') + expect(edit.exists()).toBe(true) + await edit.trigger('click') + await flushPromises() + return document.body +} + +beforeAll(() => { + // jsdom 没有 matchMedia,而 DataTable 一上来就靠它决定移动版式还是桌面板式 + window.matchMedia = ((query: string) => ({ + matches: true, + media: query, + onchange: null, + addEventListener: vi.fn(), + removeEventListener: vi.fn(), + addListener: vi.fn(), + removeListener: vi.fn(), + dispatchEvent: vi.fn() + })) as unknown as typeof window.matchMedia +}) + +describe('消息渠道 · 收件人标识', () => { + beforeEach(() => { + vi.clearAllMocks() + document.body.innerHTML = '' + }) + + it('渠道列表说得出当前按哪一列认人', async () => { + const wrapper = await open() + expect(wrapper.text()).toContain('按 Hub 用户 ID → 登录账号 认人') + }) + + it('老渠道没配过这一项,编辑框落在默认那一档上', async () => { + const body = await editDialog(await open()) + const picked = buttons(body).filter((item) => item.className.includes('badge-primary')) + expect(picked.map((item) => item.textContent?.trim()).join('|')).toContain('Hub 用户 ID 优先') + }) + + it('每一档都带一句能发到几个人,换档之前先看见代价', async () => { + const body = await editDialog(await open()) + const only = buttons(body).find((item) => item.textContent?.includes('只认 Hub 用户 ID')) + expect(only?.textContent).toContain('100') + expect(body.textContent).toContain('在职账号 108 人:按这一档能发到 108 人,8 人两种标识都没有') + }) + + it('换成一档保存出去的是 config.receiver 那根数组', async () => { + const body = await editDialog(await open()) + click(buttons(body), '只认登录账号') + click(buttons(body), '保存') + await flushPromises() + expect(api.updateChannel).toHaveBeenCalledWith('hub', expect.objectContaining({ + config: expect.objectContaining({ receiver: ['account'] }) + })) + }) + + it('投递记录里那一串标识带着它是哪一列取的', async () => { + const wrapper = await open() + click(buttons(document.body), '发送记录') + await flushPromises() + expect(wrapper.text() + document.body.textContent).toContain('登录账号:zhangsan') + }) +}) diff --git a/frontend/src/views/oa/NotifyChannelView.vue b/frontend/src/views/oa/NotifyChannelView.vue index 81f0bc4..b4b2bf4 100644 --- a/frontend/src/views/oa/NotifyChannelView.vue +++ b/frontend/src/views/oa/NotifyChannelView.vue @@ -53,6 +53,9 @@ + + +