feat: 新增流程明细导出功能及相关优化

新增流程明细导出页面、权限码与接口;优化消息通知推送逻辑,将外发任务叫醒通路统一管理;修复移动端表单展示逻辑,优化同步历史与投递记录明细显示;调整生产环境配置与镜像版本,适配新功能需求。
main
kangwenjing 2026-11-05 16:41:26 +08:00
parent db917805b8
commit 22beadf4db
93 changed files with 13978 additions and 640 deletions

View File

@ -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-<user_id>-<原名>`,人与权限都不动),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)

View File

@ -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)

View File

@ -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,

View File

@ -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 的某个组织。

View File

@ -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
]

View File

@ -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-<user_id>-<原名>):"
"本地行、待办、审批轨迹、按主键挂的权限都不动,按账号存的引用跟着这行一起搬。"
"清单被截断的那一趟不让位,增量同步也不让位——一次补丁证明不了这个人已经不在了。"),
_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"), "允许跨域的前端来源",

View File

@ -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(),

View File

@ -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()

View File

@ -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)

View File

@ -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")),
)

View File

@ -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):
"""流程干预「修正表单数据」:只交改动的那几项,系统留痕由服务端自己写。"""

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

View File

@ -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

View File

@ -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}

View File

@ -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,要用户登录态)。

File diff suppressed because it is too large Load Diff

View File

@ -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)
# ---------------------------------------------------------------------------

View File

@ -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)

View File

@ -49,7 +49,7 @@
# 永远读不到(文件路径本身就是它决定的),后端会在日志里提醒一句并忽略。
# -----------------------------------------------------------------------------
[env]
name = "dev"
name = "prod"
# -----------------------------------------------------------------------------
# 哪些项必须写在 config.<环境名>.toml 里(本文件不放,放了也是被盖住的那一层):

View File

@ -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-<user_id>-<原名>),人、待办、按主键挂的权限都不动。关掉就退回"只报数不处理"
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

View File

@ -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())

View File

@ -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())

View File

@ -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())

View File

@ -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())

View File

@ -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())

View File

@ -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())

View File

@ -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())

View File

@ -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/<task>`` 是个人页面,而 ``engine.notify()`` 对整批收件人
只传一个 ``task=``;一人一条入队时必须按人分,旁人退回 ``/work/<job>``。
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/<task> 只给这条待办的持有人,同批旁人退回单据页。
# 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:]))

View File

@ -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())

View File

@ -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())

View File

@ -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())

View File

@ -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()

View File

@ -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))

View File

@ -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",
})
#: 还原时的插回顺序:先单据与额度,再是挂在它们身上的行

View File

@ -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`(含密钥),不挂配置也能起 |

View File

@ -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

View File

@ -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=<Hub 下发的免登应用密钥>
| `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=<Hub 下发的免登应用密钥>
| `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=<Hub 下发的免登应用密钥>
| `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-<user_id>-<原名>`),好让 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-<user_id>-<原名>`):`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/<task_id>`(审批人自己的
页面,点开就能同意/退回),其余发 `/work/<job>`,没有单据就不带。**绝不拼
`site_front_url`**:Hub 按本系统登记的 `home_url` 在点击时刻现拼绝对地址(9.6.6),
本系统写死域名等于把域名焊进一条永久有效的链接里,以后换域名历史消息全成死链。
`/todo/<task_id>` 还多一道按人的闸:`engine.notify()` 对整批收件人只传一个 `task=`,
而那是**个人页面**,所以一人一条入队时 (`channels.hub_task_links`) 会核一下这条待办
到底是不是这个人的——不是(例如"外部审批那一环超时"同时知会兜底管理员,或那条待办
已经被办掉了)就把 task 抹掉,深链退回 `/work/<job>`。少这一道,管理员点开的是
"不是我的那条待办":审批页只读、按钮全灰。
链接本身不是凭据,是"应用 + 深链"的路由:同一张单据推十次用的是同一条链接,每次点击
现签一次性票据。转给同事点开是同事自己的身份,本系统的权限判定照旧——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/<job>`)、
标题/正文/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`(票据只能用一次)。

View File

@ -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 安全区、软键盘顶页面)还得在手机上过一遍。

View File

@ -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`)、重开读得回来、进撤销栈与未保存、删掉的格子不留死配置 |

View File

@ -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/<task>` 只发给这条待办的**持有人**。
`notify()` 对整批收件人只传一个 `task=`("外部审批那一环超时"会连兜底管理员一起知会),
合并成一条时这种差别根本没法落进链接;一人一条之后入队时按人核一次归属
(`channels.hub_task_links`),不是持有人的就把 task 抹掉,深链退回 `/work/<job>`。
### 群机器人一批发一条
`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 # 这条要连开发库
```

View File

@ -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` 字段只出一列、未操作者那几列与预览
逐行对得上。

View File

@ -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` 不能承载业务参数。

View File

@ -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,两个实现

View File

@ -226,6 +226,16 @@ export const http = {
const response = await apiClient.get<Blob>(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<DownloadResult> => {
const response = await apiClient.post<Blob>(url, body ?? {}, { responseType: 'blob' })
return { blob: response.data, filename: filenameOfDisposition(response.headers?.['content-disposition']) }
},
/**
* 存一个文件到本地(网盘、附件都是这一条)。
*

View File

@ -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<string, string[]>
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<DetailCatalog> {
return http.get<DetailCatalog>('/export/detail/catalog')
}
export function count(body: DetailBody): Promise<CountResult> {
return http.post<CountResult>('/export/detail/count', body)
}
export function preview(body: DetailBody): Promise<PreviewResult> {
return http.post<PreviewResult>('/export/detail/preview', body)
}
export function download(body: DetailBody): Promise<DownloadResult> {
return http.postDownload('/export/detail/download', body)
}
/** 取回来顺手落地,回给调用方真实文件名,好在那句提示里念出来。 */
export async function downloadDetail(body: DetailBody): Promise<string> {
const result = await download(body)
const filename = result.filename || `流程明细导出.${body.fmt === 'csv' ? 'csv' : 'xlsx'}`
saveBlob(result.blob, filename)
return filename
}

View File

@ -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<string, number>
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<Record<string, unknown>>
note: string
}
offboard_accounts: string[]
organization_sample: Array<{

View File

@ -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'

View File

@ -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<NotifyMeta> {
return http.get<NotifyMeta>('/notify/meta')
}
export interface ChannelList extends NotifyList<NotifyChannel> {}
export interface ChannelList extends NotifyList<NotifyChannel> {
/** 有 Hub 渠道时后端顺带算的一份收件人标识覆盖情况;没有就是 null */
hubCoverage?: NotifyReceiverCoverage | null
}
export function listChannels(): Promise<ChannelList> {
return http.get<ChannelList>('/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<NotifyDelivery> {}
/**
* 投递记录是分页的:``total`` / ``pages`` 给分页器,``counts`` 是各状态在当前筛选
* (渠道 / 消息类型 / 关键词,不含状态本身)下各有多少条,``''`` 那一项是「全部」。
*/
export interface DeliveryList extends NotifyList<NotifyDelivery>, BasePaginationResponse<NotifyDelivery> {}
export function listDeliveries(query: DeliveryQuery = {}): Promise<DeliveryList> {
return http.get<DeliveryList>('/notify/deliveries', { limit: 80, ...query })
export function listDeliveries(query: DeliveryQuery = {}, options?: FetchOptions): Promise<DeliveryList> {
return http.get<DeliveryList>('/notify/deliveries', { page: 1, page_size: 20, ...query }, options)
}
/** 对方修好了:重新排队,下一轮调度再发。 */
@ -56,6 +72,11 @@ export function resendDelivery(id: string): Promise<NotifyDelivery> {
return http.post<NotifyDelivery>(`/notify/deliveries/${encodeURIComponent(id)}/resend`)
}
/** 找 Hub 回查这一条的逐人送达结果,按对方口径改写本地记录(只读,可反复点)。 */
export function recheckDelivery(id: string): Promise<NotifyDelivery> {
return http.post<NotifyDelivery>(`/notify/deliveries/${encodeURIComponent(id)}/recheck`)
}
/** 不等下一轮调度,当场再发一次。 */
export function sendDeliveryNow(id: string): Promise<NotifyDelivery> {
return http.post<NotifyDelivery>(`/notify/deliveries/${encodeURIComponent(id)}/send-now`)

View File

@ -47,6 +47,43 @@ export function unbindUnitHub(id: string): Promise<Unit> {
return http.del<Unit>(`/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<ShellUnitList> {
return http.get<ShellUnitList>('/org/units/shells')
}
/** 一键清理空壳部门;``ids`` 留空 = 清掉所有符合条件的,``dryRun`` 一行都不动。 */
export function cleanupShellUnits(payload: { ids?: string[]; dryRun?: boolean } = {}): Promise<ShellCleanupResult> {
return http.post<ShellCleanupResult>('/org/units/shells/cleanup', {
ids: payload.ids ?? [],
dry_run: payload.dryRun ?? false
})
}
export interface PersonQuery {
keyword?: string
organization_id?: string

View File

@ -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)
})
</script>

View File

@ -141,6 +141,7 @@ const sections = computed<NavSection[]>(() => {
{ 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 },

View File

@ -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('、')
}
</script>

View File

@ -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<string, unknown> = {}) {
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<string, never>)
},
offboard_accounts: [],
organization_sample: [],
warning: ''
}
}
function statusOf(patch: Record<string, unknown> = {}) {
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: '<div><slot /><slot name="footer" /></div>' }
}
}
})
}
/** 把「标签 -> 数字」这两行凑成一张表,断言时按标签取值,不靠整页文本猜。 */
function cellsOf(wrapper: ReturnType<typeof mountButton>): Record<string, string> {
const out: Record<string, string> = {}
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<string, unknown> = {}) {
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<typeof openPreview>, 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()
})
})

View File

@ -86,7 +86,16 @@
<td class="py-1.5 pr-3">
<span class="badge" :class="statusClass(row.status)">{{ statusLabel(row.status) }}</span>
</td>
<td class="py-1.5 pr-3 text-gray-500 dark:text-dark-400">{{ summaryOf(row) }}</td>
<td class="py-1.5 pr-3 text-gray-500 dark:text-dark-400">
{{ summaryOf(row) }}
<span
v-for="line in detailsOf(row)"
:key="line"
class="mt-0.5 block text-[11px] text-amber-600 dark:text-amber-400"
>
{{ line }}
</span>
</td>
</tr>
<tr v-if="!runs.length">
<td colspan="4" class="py-4 text-center text-gray-400">{{ t('common.noData') }}</td>
@ -120,6 +129,34 @@
</div>
</div>
</div>
<div v-if="previewData.organizations.zombie_unit_samples?.length" class="mt-3">
<div class="flex flex-wrap items-center gap-1.5">
<span class="text-xs text-gray-400">{{ t('hub.zombieUnitsSample') }}</span>
<span
v-for="unit in previewData.organizations.zombie_unit_samples || []"
:key="unit.id"
class="badge"
:class="unit.blockers?.length ? 'badge-gray' : 'badge-amber'"
:title="[unit.code, ...(unit.blockers || [])].join(' · ')"
>{{ unit.name }}</span>
</div>
<div v-if="deletableShells" class="mt-2 flex flex-wrap items-center gap-2">
<button type="button" class="btn btn-secondary btn-xs" :disabled="cleaning" @click="cleanShells">
<Icon name="trash" class="mr-1 h-3.5 w-3.5" />
{{ cleaning ? t('hub.cleanShellsBusy') : t('hub.cleanShells', { value: deletableShells }) }}
</button>
<span class="text-[11px] text-gray-400">{{ t('hub.cleanShellsHint') }}</span>
</div>
</div>
<ul v-if="previewNotes.length" class="mt-3 space-y-1.5">
<li
v-for="note in previewNotes"
:key="note"
class="rounded-xl bg-gray-50 px-3 py-2 text-xs text-gray-500 dark:bg-dark-700/40 dark:text-dark-400"
>
{{ note }}
</li>
</ul>
<p v-if="previewData.users.mobile_note" class="mt-3 rounded-xl bg-gray-50 px-3 py-2 text-xs text-gray-500 dark:bg-dark-700/40 dark:text-dark-400">
{{ previewData.users.mobile_note }}
</p>
@ -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<HubDirectoryPreview | null>(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

View File

@ -45,6 +45,13 @@
<p class="mt-0.5 text-[11px] text-gray-400">
{{ job.last_run.trigger_label }} · {{ summary }}
</p>
<p
v-for="line in details"
:key="line"
class="mt-0.5 text-[11px] text-amber-600 dark:text-amber-400"
>
{{ line }}
</p>
</template>
<p v-else class="mt-1 text-xs text-gray-400">{{ t('syncSchedule.neverRun') }}</p>
</div>
@ -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}`

View File

@ -1,6 +1,7 @@
<template>
<div class="overflow-hidden rounded-xl bg-white shadow-sm dark:bg-dark-800" :class="tone">
<button
v-if="title"
type="button"
class="flex w-full items-center gap-2 px-3.5 py-3 text-left"
:aria-expanded="open"
@ -11,7 +12,7 @@
<span v-if="note" class="flex-shrink-0 text-xs text-gray-400 dark:text-dark-500">{{ note }}</span>
<Icon name="chevronRight" class="h-4 w-4 flex-shrink-0 text-gray-400 transition-transform dark:text-dark-500" :class="open ? 'rotate-90' : ''" />
</button>
<div v-show="open" class="border-t border-gray-100 dark:border-dark-700"><slot /></div>
<div v-show="!title || open" :class="title ? 'border-t border-gray-100 dark:border-dark-700' : ''"><slot /></div>
</div>
</template>
@ -19,6 +20,10 @@
/**
* 折叠块:手机上「默认收起、点了才展开」的唯一实现。
*
* 不给标题(`title` 传空串)就是**一块不折叠的内容**:那一行连箭头一起不摆,内容直接摊开。
* 表单那一节的名字没配过时走这一档——上面那排页签已经写着「表单内容」,
* 同一句话不该在 390px 上占两行(还搭上一颗没用的折叠箭头)。
*
* 一张 47 个字段的单子全摊开是六屏,领导真正要看的就两三样。折叠的粒度按流程设计里
* 本来就有的分隔条走(divider 字段就是分节标题),不额外发明一层「移动分组」配置——
* 设计器里改一分组,手机上跟着变,不会出现桌面改了手机上没改。

View File

@ -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('一张空表单也不炸', () => {

View File

@ -10,7 +10,7 @@
<MobileFold
v-for="section in plan.sections"
:key="section.key"
:title="section.name"
:title="section.generic && plan.sections.length === 1 ? '' : section.name"
:note="section.embed ? t('mobile.embedPage') : t('mobile.fieldCount', { count: section.rows.length })"
default-open
>

View File

@ -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,

View File

@ -9,7 +9,7 @@
<MobileFold
v-for="group in plan.groups"
:key="group.name"
:title="group.name"
:title="bare(group) ? '' : group.name"
:note="t('mobile.fieldCount', { count: group.items.length })"
default-open
>
@ -137,7 +137,7 @@
<MobileFold
v-for="(group, index) in plan.groups"
:key="group.name"
:title="group.name"
:title="bare(group) ? '' : group.name"
:note="t('mobile.fieldCount', { count: group.items.length })"
:default-open="index === 0"
>
@ -258,6 +258,17 @@ const opened = ref<Set<string>>(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)
}

View File

@ -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<ReturnType<typeof render>>['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')

View File

@ -76,7 +76,7 @@
>
<p class="font-medium leading-relaxed">{{ t('task.nodeDecisionBanner', { app: item.appName || item.app, action: item.kindLabel, route: item.route }) }}</p>
<div class="mt-2 flex gap-2">
<button type="button" class="btn btn-primary btn-sm flex-1" @click="ctx.confirmDecision(item.id, next)">{{ t('task.nodeDecisionConfirm') }}</button>
<button type="button" class="btn btn-primary btn-sm flex-1" @click="ctx.confirmDecision(item.id, finishToTodo)">{{ t('task.nodeDecisionConfirm') }}</button>
<button type="button" class="btn btn-secondary btn-sm" @click="ctx.rejectDecision(item.id)">{{ t('task.nodeDecisionReject') }}</button>
</div>
</div>
@ -265,7 +265,7 @@
<template #footer>
<button type="button" class="btn btn-secondary flex-none px-5" @click="approveSheet = false">{{ t('mobile.lookAgain') }}</button>
<button type="button" class="btn btn-primary flex-1" :disabled="ctx.busy.value" data-test="m-submit" @click="approve">
{{ ctx.busy.value ? t('common.loading') : t('mobile.submitNext') }}
{{ ctx.busy.value ? t('common.loading') : t('mobile.submitBack') }}
</button>
</template>
</MobileSheet>
@ -303,7 +303,7 @@
</div>
<template #footer>
<button type="button" class="btn btn-secondary flex-none px-5" @click="ctx.goBackShow.value = false">{{ t('common.cancel') }}</button>
<button type="button" class="btn btn-danger flex-1" :disabled="ctx.busy.value" @click="ctx.confirmGoBack(next)">{{ t('common.confirm') }}</button>
<button type="button" class="btn btn-danger flex-1" :disabled="ctx.busy.value" data-test="m-goback-confirm" @click="ctx.confirmGoBack(finishToTodo)">{{ t('common.confirm') }}</button>
</template>
</MobileSheet>
@ -372,7 +372,7 @@
<template #footer>
<button type="button" class="btn btn-secondary flex-none px-5" @click="closePeople">{{ t('common.cancel') }}</button>
<button v-if="ctx.sendShow.value" type="button" class="btn btn-primary flex-1" :disabled="ctx.busy.value" @click="send">{{ t('common.confirm') }}</button>
<button v-else type="button" class="btn btn-primary flex-1" :disabled="ctx.busy.value" @click="ctx.confirmPeople(ctx.peopleMode.value === 'transfer' ? next : undefined)">{{ t('common.confirm') }}</button>
<button v-else type="button" class="btn btn-primary flex-1" :disabled="ctx.busy.value" data-test="m-people-confirm" @click="ctx.confirmPeople(ctx.peopleMode.value === 'transfer' ? finishToTodo : stayOnDoc)">{{ t('common.confirm') }}</button>
</template>
</MobileSheet>
@ -446,7 +446,7 @@
<script setup lang="ts">
/**
* 手机上的审批页:一屏读完该读的,底下那颗「同意」把单批掉,办完直接跳下一条。
* 手机上的审批页:一屏读完该读的,底下那颗「同意」把单批掉,办完关掉这张单子回待办列表。
*
* 这里没有第二套审批逻辑。出口怎么合、哪几格这一环能改、必填那道闸、退回能退到哪几环、
* 写回卡没卡、OA 按钮锁没锁、表单里那几格附件要不要随行交上去——全部来自 TaskDetailView
@ -480,7 +480,6 @@ import { useMobileShell, type FontScale } from '@/composables/useMobileShell'
import { usePullToRefresh } from '@/composables/useMobileRefresh'
import { expandPerms } from '@/utils/tabPages'
import { personText } from '@/utils/personLabel'
import { taskAPI } from '@/api'
import { useAppStore } from '@/stores/app'
import { badgeClass, workStatusLabel, workStatusVariant } from '@/utils/oa'
import { formatDateTimeToMinute } from '@/utils/format'
@ -660,19 +659,29 @@ function pickAndApprove(item: TaskRouteButton) {
async function approve() {
approveSheet.value = false
await ctx.submit(next)
await ctx.submit(finishToTodo)
}
/** 办完不停在原地:手上通常不止一条,直接把人送到下一条待办。 */
async function next() {
const list = await taskAPI.listProcessing({ page: 1, page_size: 2 }).catch(() => null)
const hit = (list?.items ?? []).find((item) => item.id !== taskId.value)
/**
* 办完这张单子就把它关掉,回待办列表重新取一次。
*
* 原先是「自动去下一条」:省一次拇指,代价是批完的人看不见「这条真的走了、还剩几条」,
* 而且两个 id 之间组件不重新挂载,抬头那一屏还是上一张单子的内容。列表本来就自己取数,
* 剩下的那几条摆在眼前,下一条点不点由人决定。
*/
async function finishToTodo() {
menuOpen.value = false
if (hit) await router.replace({ name: 'todo-detail', params: { id: hit.id } })
else await router.replace({ name: 'my-todo' })
closeReader()
await router.replace({ name: 'my-todo' })
await appStore.refreshBadgeCounts()
}
/** 加签不改归属:单子还压在手里,就地取一次,别把人送去「已办」。 */
function stayOnDoc() {
menuOpen.value = false
void ctx.reload()
}
function backToList() {
if (window.history.length > 1) router.back()
else router.replace({ name: 'my-todo' })

View File

@ -273,8 +273,10 @@ export function stubView(
goBackWay.value = 'step'
goBackShow.value = true
}) as TaskView['openGoBack'],
confirmGoBack: (async () => {
confirmGoBack: (async (done?: unknown) => {
calls.push({ name: 'confirmGoBack' })
// 与真的那份一样:办成了才把「去哪儿」这个回调交出去
if (typeof done === 'function') (done as () => void)()
}) as TaskView['confirmGoBack'],
peopleShow,
peopleMode,
@ -298,8 +300,9 @@ export function stubView(
peopleOpinion.value = ''
peopleShow.value = true
}) as TaskView['openTransfer']),
confirmPeople: (async () => {
calls.push({ name: 'confirmPeople' })
confirmPeople: (async (done?: unknown) => {
calls.push({ name: 'confirmPeople', at: peopleMode.value })
if (typeof done === 'function') (done as () => void)()
}) as TaskView['confirmPeople'],
sendShow,
sendMode,

View File

@ -2,7 +2,7 @@
import { beforeAll, describe, expect, it } from 'vitest'
import { i18n } from '@/i18n'
import zh from '@/i18n/locales/zh'
import { fieldText, planForm, readerSections } from './useFormPlan'
import { fieldText, mobileRowCells, planForm, readerSections } from './useFormPlan'
import { expenseData, expenseSchema } from './mobileFixtures'
import type { FormFieldDef, FormSchema, MobileLayout } from '@/types'
@ -100,6 +100,50 @@ describe('把一格的值说成一句人话', () => {
expect(fieldText(field({ key: 'k', type: 'user' }), [{ name: '李明' }])).toBe('李明')
})
it('钱按格子配的格式写,单位与桌面只读态同一句', () => {
// 桌面写「12.00 元」,手机上不能只写「12.00」:金额没配单位也要补那个「元」
expect(fieldText(field({ key: 'k', type: 'money' }), 12)).toBe('12.00 元')
expect(fieldText(field({ key: 'k', type: 'money', unit: '美元' }), 4860)).toBe('4,860.00 美元')
// 配了「原样数字」/小数位的格子,手机上别再自己按两位小数写一遍
expect(fieldText(field({ key: 'k', type: 'number', numberFormat: 'plain' }), 1234.5)).toBe('1234.5')
expect(fieldText(field({ key: 'k', type: 'number', precision: 0 }), 1234.5)).toBe('1,235')
expect(fieldText(field({ key: 'k', type: 'money', numberFormat: 'currency' }), -1200.5)).toContain('-¥1,200.50')
// 明细那一列的钱也按列上的格式写:与桌面摊明细时同一份 formatNumber
const detail = field({
key: 'rows',
type: 'table',
columns: [
{ key: 'item', label: '事项', type: 'text' },
{ key: 'money', label: '金额', type: 'money' }
]
})
expect(mobileRowCells(detail, { item: '高铁往返', money: 1129 })).toEqual([
{ key: 'item', label: '事项', value: '高铁往返', numeric: false },
{ key: 'money', label: '金额', value: '1,129.00', numeric: true }
])
})
it('星期几、月份、定位这三类念成人话,不摊出库里的码', () => {
// 与桌面只读态共用 utils/formRuntime 那几份读法:手机上不该看到 1-7 与 ['2026-10']
expect(fieldText(field({ key: 'k', type: 'week' }), ['1', '3'])).toBe('周一、周三')
expect(fieldText(field({ key: 'k', type: 'week' }), ['9'])).toBe('')
expect(fieldText(field({ key: 'k', type: 'months' }), ['2026-10', '2026-11'])).toBe('2026年10-11月')
expect(fieldText(field({ key: 'k', type: 'location' }), { lng: '116.4', lat: '39.9', address: '北京市海淀区' })).toBe('北京市海淀区(116.4, 39.9)')
expect(fieldText(field({ key: 'k', type: 'timerange' }), ['09:00', '10:30'])).toBe('09:00 ~ 10:30')
})
it('部门那一格只念部门名,不把整条组织路径摊在手机上', () => {
// 库里存的是组织路径,桌面只读态取的是下拉候选项的 label(就是部门名),手机上同一个口径
expect(fieldText(field({ key: 'k', type: 'dept' }), '紫光汇智\\软件开发事业部')).toBe('软件开发事业部')
// 带尾杠、只有一级、物件、多选这几种写法都得念得出名字
expect(fieldText(field({ key: 'k', type: 'dept' }), '紫光汇智\\软件开发事业部\\')).toBe('软件开发事业部')
expect(fieldText(field({ key: 'k', type: 'dept' }), '紫光汇智')).toBe('紫光汇智')
expect(fieldText(field({ key: 'k', type: 'dept' }), { name: '董事长', path: '紫光汇智\\董事长' })).toBe('董事长')
expect(fieldText(field({ key: 'k', type: 'dept' }), ['紫光汇智\\董事长', '紫光汇智\\总经理'])).toBe('董事长、总经理')
// 从前这一格走人员口径:路径被当账号问了一遍姓名接口,回来拼成「路径(路径)」,三行才读完
expect(fieldText(field({ key: 'k', type: 'dept' }), '紫光汇智\\董事长')).not.toContain('(')
})
it('空值就是一句空话,版式那一侧靠它决定渲不渲染', () => {
expect(fieldText(field({ key: 'k', type: 'text' }), '')).toBe('')
expect(fieldText(field({ key: 'k', type: 'table' }), [])).toBe('')
@ -180,6 +224,17 @@ describe('页签与「手机上不展示」这两档', () => {
describe('完整单据那一屏的读法', () => {
it('按页签分节,外部页面那一节只给一张卡片', () => {
const plan = readerSections({ fields: [field({ key: 'reason', type: 'textarea' })] }, { data: { reason: '出差' } })
// 一张既没分页也没分隔条的表,在「完整单据」里就一节,名字是兜底的:那一行标题不摆
expect(plan.sections.map((section) => [section.name, section.generic])).toEqual([['表单内容', true]])
})
it('完整单据里「系统取数」那一节的名字是真名字,标题行照摆', () => {
const plan = readerSections(expenseSchema(), { data: expenseData() })
expect(plan.sections[0].generic).toBe(false)
})
it('页签分节时每一节都带着页签名上屏', () => {
const plan = readerSections(tabsSchema(), { data: { reason: '出差', city: '', invoice_no: 'FP-1' } })
expect(plan.sections.map((row) => row.name)).toEqual(['费用报销基本信息', '费用报销发票信息'])
const form = plan.sections[0]
@ -383,6 +438,27 @@ describe('按配置摆的那一版:只有一节', () => {
expect(planForm(mobileSchema({ enabled: true, fields: [{ key: 'reason' }] }, TINY), { data: TINY_DATA }).groups[0]?.name).toBe('表单内容')
})
it('兜底来的节名标成 generic:那一行标题在手机上不摆', () => {
// 「表单内容」是代码补的,不是配表的人起的名字——上面那排页签已经写着这三个字了
expect(planForm(mobileSchema({ enabled: true, fields: [{ key: 'reason' }] }, TINY), { data: TINY_DATA }).groups[0]?.generic).toBe(true)
// 配了名字、或者名字来自页签,都是真名字,标题行照摆
expect(
planForm(mobileSchema({ enabled: true, title: '费用报销基本信息', fields: [{ key: 'reason' }] }, TINY), {
data: TINY_DATA
}).groups[0]?.generic
).toBe(false)
const withTabs = [field({ key: 'tabs_host', type: 'tabs', tabs: [{ key: 'tab_1', label: '费用报销基本信息' }] }), field({ key: 'reason', type: 'textarea', tab: 'tab_1' })]
expect(planForm(mobileSchema({ enabled: true, fields: [{ key: 'reason' }] }, withTabs), { data: { reason: '出差' } }).groups[0]?.generic).toBe(false)
})
it('自动归置那一版也一样:分隔条与页签起的名字算名字,兜底那句不算', () => {
const withDivider = { fields: [field({ key: 'd1', type: 'divider', label: '第二段' }), field({ key: 'reason', type: 'textarea' })] }
expect(planForm(withDivider, { data: { reason: '出差' } }).groups.map((group) => group.generic)).toEqual([false])
// 没有分隔条也没有页签:整张表就一节,名字是兜底的
expect(planForm(expenseSchema(), { data: expenseData() }).groups.some((group) => group.generic)).toBe(false)
expect(planForm({ fields: [field({ key: 'reason', type: 'textarea' })] }, { data: { reason: '出差' } }).groups[0]?.generic).toBe(true)
})
it('明细收成一行时照样填 plan.table:明细那一屏与几处判据读的都是它', () => {
const plan = planForm(mobileSchema({ enabled: true, fields: [{ key: 'rows', style: 'card' }] }), { data: expenseData() })
expect(plan.table?.count).toBe(12)

View File

@ -16,6 +16,7 @@
*/
import { i18n } from '@/i18n'
import { MOBILE_FLOAT_MAX, mobileEntries, mobileFieldLabel, mobileLayoutOf, styleFor } from '@/utils/mobileLayout'
import { displayUnit, formatNumber, locationText, monthsText, rangeText, weekText } from '@/utils/formRuntime'
import { personText } from '@/utils/personLabel'
import { isEmbedTab, isTabsField, tabEmbedField, tabKeyOf, tabsFieldOf, tabsOf } from '@/utils/tabPages'
import type { AttachmentItem, FormFieldDef, FormSchema, FormTabDef, MobileFieldLayout, MobileFieldStyle, MobileLayout } from '@/types'
@ -43,9 +44,16 @@ export interface PlanItem {
rows: Record<string, unknown>[]
}
/** 一节:`planForm` 摆出来的那一节,节名是照表单上现成的东西认出来的。 */
export interface PlanGroup {
name: string
items: PlanItem[]
/**
* 这一节的名字是**兜底**来的(表单既没配节名、也没有页签和分隔条),不是配表的人起的名字。
* 手机上这种节不再摆标题行:上面那排页签已经写着「表单内容」,同一句话不该在 390px 上
* 占两行,那一行还多带一个「N 项」和一颗折叠箭头。
*/
generic?: boolean
}
export interface PlanMedia {
@ -94,6 +102,8 @@ export interface ReaderSection {
embedField: FormFieldDef | null
/** 这一节是外部系统的页面:手机上不内嵌,给一张「打开」卡片 */
embed: boolean
/** 同 `PlanGroup.generic`:名字是兜底来的,那一行标题就不摆 */
generic?: boolean
}
export interface ReaderPlan {
@ -108,6 +118,17 @@ export interface ReaderPlan {
const NUMERIC = new Set(['money', 'number', 'formula', 'rate'])
const MEDIA = new Set(['attachment', 'image'])
/**
* 明细那一列的值念成什么:金额与数字按那一列配的格式写(与桌面摊明细时同一份
* `formatNumber`),其余原样。不这么一步,手机上「金额 1129」在电脑上是「1,129.00」。
*/
function rowCellText(col: FormFieldDef, value: unknown): string {
const raw = String(value ?? '').trim()
if (!NUMERIC.has(String(col.type)) || raw === '') return raw
const num = Number(value)
return Number.isFinite(num) ? formatNumber(num, col) : raw
}
/**
* 明细那一条摆哪几列、各摆成什么话:只摆填了的那几列,空列不占行。
*
@ -121,7 +142,7 @@ export function mobileRowCells(field: FormFieldDef, item: Record<string, unknown
.map((col) => ({
key: String(col.key),
label: String(col.label ?? col.key),
value: String(row[col.key] ?? '').trim(),
value: rowCellText(col, row[col.key]),
numeric: NUMERIC.has(String(col.type))
}))
.filter((cell) => cell.value !== '')
@ -145,18 +166,25 @@ function optionLabel(field: FormFieldDef, value: unknown): string {
return hit ? String(hit.label ?? hit.value) : String(value)
}
function money(value: unknown): string {
const num = Number(value)
if (!Number.isFinite(num)) return String(value)
return num.toLocaleString('zh-CN', { minimumFractionDigits: 2, maximumFractionDigits: 2 })
/**
* 数字与金额念成什么样:读 `utils/formRuntime.formatNumber` 那一份(千分位 / 小数位 / 货币
* 都按格子上的配置来),单位口径照桌面只读态那句——金额没配单位就补一个「元」,
* 别的类型配了才写。手机上从前自己按两位小数写,于是同一张单子在电脑上写「12.00 元」、
* 在手机上写「12.00」,配了「原样数字」或整数精度的格子两边更是对不上。
*/
function numericText(field: FormFieldDef, value: unknown): string {
const text = formatNumber(value, field)
if (field.type === 'money') return `${text} ${displayUnit(field.unit) || t('form.moneyUnit')}`
const unit = displayUnit(field.unit)
return unit ? `${text} ${unit}` : text
}
/** 一条明细里第一个金额列的合计:没有金额列就不显示合计,不硬凑。 */
/** 一条明细里第一个金额列的合计:没有金额列就不显示合计,不硬凑;写法跟着那一列的格式走。 */
function rowsSum(rows: Record<string, unknown>[], columns: FormFieldDef[] = []): string {
const moneyCol = columns.find((col) => col.type === 'money' || col.type === 'number')
if (!moneyCol) return ''
const sum = rows.reduce((acc, row) => acc + (Number(row?.[moneyCol.key]) || 0), 0)
return money(sum)
return formatNumber(sum, moneyCol)
}
/**
@ -186,6 +214,36 @@ function filesOf(value: unknown): AttachmentItem[] {
})
}
/**
* 部门那一格存的是组织路径(`紫光汇智\软件开发事业部`),手机上要的答案是「哪个部门」,
* 也就是路径末段那个名字——与桌面只读态同一个口径(桌面取部门下拉候选项的 label,
* 那本来就是部门名,见 `utils/deptOptions.buildDeptOptions`)。
*
* 这一格从前跟选人格子共用 `personText`:部门路径被当人员引用报给 `/org/persons/label`,
* 后端对认不出的字符串照字面给个名字(`app/service/org.py:_ref_missing`),前端再拼成
* `姓名(账号)`,手机上念出来就是「紫光汇智\软件开发事业部(紫光汇智\软件开发事业部)」——
* 同一条路径在 390px 上摊三行,还把末段那 7 个字挤到第二行。
*/
export function deptText(value: unknown): string {
const list = Array.isArray(value) ? value : [value]
return list.map(deptName).filter(Boolean).join('、')
}
/** 一条部门引用 -> 部门名:路径取末段,物件取名字,尾部那个反斜杠不算一层。 */
function deptName(value: unknown): string {
const raw =
value && typeof value === 'object'
? String(
(value as Record<string, unknown>).name ??
(value as Record<string, unknown>).label ??
(value as Record<string, unknown>).path ??
''
)
: String(value ?? '')
const parts = raw.split(/[\\/]/).map((part) => part.trim()).filter(Boolean)
return parts[parts.length - 1] ?? ''
}
/** 把一格的值说成一句人话。控件不渲染,所以这一句就是手机上看到的全部内容。 */
export function fieldText(field: FormFieldDef, value: unknown): string {
if (isEmpty(value)) return ''
@ -193,12 +251,12 @@ export function fieldText(field: FormFieldDef, value: unknown): string {
if (MEDIA.has(field.type)) return String(filesOf(value).length)
if (field.type === 'table') return String(Array.isArray(value) ? value.length : 0)
if (field.type === 'signature') return t('mobile.signed')
if (field.type === 'money') return `${money(value)}${field.unit ? ` ${field.unit}` : ''}`
if (NUMERIC.has(field.type)) {
const num = Number(value)
const text = Number.isFinite(num) ? String(value) : String(value)
return field.unit ? `${text} ${field.unit}` : text
}
if (NUMERIC.has(field.type)) return numericText(field, value)
// 这几类桌面有现成的读法(`utils/formRuntime`),手机上不另发明一套:
// 星期几存 1-7、月份存 ['2026-10']、定位是个物件,直接 String() 就是一串没人看得懂的码
if (field.type === 'week') return weekText(value, (day) => t(`form.weekday${day}`))
if (field.type === 'months') return monthsText(value)
if (field.type === 'location') return locationText(value)
if (['select', 'radio', 'picker', 'cascader'].includes(field.type)) {
return Array.isArray(value) ? value.map((item) => optionLabel(field, item)).join('、') : optionLabel(field, value)
}
@ -206,7 +264,8 @@ export function fieldText(field: FormFieldDef, value: unknown): string {
const list = Array.isArray(value) ? value : [value]
return list.map((item) => optionLabel(field, item)).join('、')
}
if (['user', 'dept'].includes(field.type)) {
if (field.type === 'dept') return deptText(value)
if (field.type === 'user') {
const list = Array.isArray(value) ? value : [value]
return list.map((item) => (typeof item === 'string' ? personText(item) : String((item as Record<string, unknown>)?.name ?? item))).join('、')
}
@ -214,10 +273,7 @@ export function fieldText(field: FormFieldDef, value: unknown): string {
const list = Array.isArray(value) ? value : [value]
return list.map((item) => String((item as Record<string, unknown>)?.title ?? (item as Record<string, unknown>)?.serial ?? item)).join('、')
}
if (field.type === 'daterange' || field.type === 'timerange') {
const list = Array.isArray(value) ? value : [value]
return list.filter((item) => !isEmpty(item)).join(' ~ ')
}
if (field.type === 'daterange' || field.type === 'timerange') return rangeText(value)
if (typeof value === 'object') {
const row = value as Record<string, unknown>
return String(row.title ?? row.name ?? row.label ?? row.text ?? '')
@ -261,10 +317,10 @@ export function planForm(schema: FormSchema | null | undefined, options: PlanOpt
let divider = ''
let atTab = ''
const pushGroup = (name: string) => {
const found = plan.groups.find((item) => item.name === name)
const pushGroup = (title: SectionName) => {
const found = plan.groups.find((item) => item.name === title.name)
if (found) return found
const created: PlanGroup = { name, items: [] }
const created: PlanGroup = { ...title, items: [] }
plan.groups.push(created)
return created
}
@ -366,7 +422,11 @@ export function planForm(schema: FormSchema | null | undefined, options: PlanOpt
* 以及本环节要人填的那几格(上面有填写块),仍然一律不上这一屏。
*/
function planByMobileLayout(config: MobileLayout): FormPlan {
const section: PlanGroup = { name: String(config.title ?? '').trim() || mobileSectionName(fields), items: [] }
const titled = String(config.title ?? '').trim()
const section: PlanGroup = {
...(titled ? { name: titled, generic: false } : mobileSectionName(fields)),
items: []
}
plan.custom = true
plan.showFull = Boolean(config.showFullSheet)
for (const { field, entry, embed, slotKey } of mobileEntries(config, fields)) {
@ -428,10 +488,20 @@ function kindOf(field: FormFieldDef): PlanItem['kind'] {
* 配置没写节名时的兜底:有页签就取第一个页签的名字——配表的人既然把这张单分成了
* 「基本信息 / 票据」两页,手机上要的那一节多半就是第一页;再没有就叫「表单内容」。
*/
function mobileSectionName(fields: FormFieldDef[]): string {
function mobileSectionName(fields: FormFieldDef[]): SectionName {
const pages = pageListOf(fields)
const first = pages.find((tab) => !isEmbedTab(tab)) ?? pages[0]
return String(first?.label ?? '').trim() || t('work.formData')
const label = String(first?.label ?? '').trim()
return label ? { name: label, generic: false } : { name: t('work.formData'), generic: true }
}
/**
* 一节的名字,连带说清这个名字是不是兜底来的(见 `PlanGroup.generic`):
* 页签名与分隔条都是表单上现成的字,算起的了名字;「表单内容」那三个字是代码补的,不算。
*/
interface SectionName {
name: string
generic: boolean
}
/** 排版件:自己不摆值。divider 不在这里——它下面要当分节标题用。 */
@ -462,10 +532,10 @@ function onEmbedPage(field: FormFieldDef, pages: FormTabDef[]): boolean {
* 为什么页签优先:配表的人把一张单分成「基本信息 / 发票信息」两页,手机上第一眼就该
* 看见这两个词;分隔条是某一页里面的分段,比页签低一层。
*/
function sectionName(field: FormFieldDef, pages: FormTabDef[], divider: string): string {
function sectionName(field: FormFieldDef, pages: FormTabDef[], divider: string): SectionName {
const tab = String(pageOf(field, pages)?.label ?? '').trim()
const head = [tab, String(divider ?? '').trim()].filter(Boolean).join(' · ')
return head || t('work.formData')
return head ? { name: head, generic: false } : { name: t('work.formData'), generic: true }
}
/**
@ -475,10 +545,12 @@ function sectionName(field: FormFieldDef, pages: FormTabDef[], divider: string):
* 不然它们会挤进一个叫「表单内容」的节里——那三个字什么也没说,而摘要那一屏
* 早就把这六格并成同一句话了,两处对不上号更难读。
*/
function readerSectionName(field: FormFieldDef, page: FormTabDef | null, divider: string): string {
function readerSectionName(field: FormFieldDef, page: FormTabDef | null, divider: string): SectionName {
const head = [String(page?.label ?? '').trim(), String(divider ?? '').trim()].filter(Boolean).join(' · ')
if (head) return head
return field.type === 'auto' ? t('mobile.autoFields') : t('work.formData')
if (head) return { name: head, generic: false }
// 「系统取数」那一节的名字不是兜底:它说的是这一节的料是哪来的,标题行照样摆
if (field.type === 'auto') return { name: t('mobile.autoFields'), generic: false }
return { name: t('work.formData'), generic: true }
}
export interface ReaderOptions {
@ -505,20 +577,22 @@ export function readerSections(schema: FormSchema | null | undefined, options: R
/** 外部页面那一页:手机上不内嵌,只摆一张「打开」卡片,所以这一节没有格子 */
const pushEmbedSection = (tab: FormTabDef) => {
const label = String(tab.label ?? '').trim()
plan.sections.push({
key: `embed:${tab.key}`,
name: String(tab.label ?? '').trim() || t('work.formData'),
name: label || t('work.formData'),
rows: [],
embedField: host ? tabEmbedField(host, tab) : null,
embed: true
embed: true,
generic: !label
})
}
const sectionFor = (field: FormFieldDef, page: FormTabDef | null) => {
const name = readerSectionName(field, page, divider)
const found = plan.sections.find((row) => !row.embed && row.name === name)
const title = readerSectionName(field, page, divider)
const found = plan.sections.find((row) => !row.embed && row.name === title.name)
if (found) return found
const created: ReaderSection = { key: name, name, rows: [], embedField: null, embed: false }
const created: ReaderSection = { ...title, key: title.name, rows: [], embedField: null, embed: false }
plan.sections.push(created)
return created
}

View File

@ -75,6 +75,7 @@ export const PERMISSION_GROUPS: PermissionGroupMeta[] = [
labelKey: 'perm.groupSystem',
items: [
{ code: 'monitor:work', labelKey: 'perm.monitorWork' },
{ code: 'monitor:export', labelKey: 'perm.monitorExport' },
{ code: 'statistics:view', labelKey: 'perm.statisticsView' },
{ code: 'log:view', labelKey: 'perm.logView' },
{ code: 'system:setting', labelKey: 'perm.systemSetting' },

View File

@ -25,7 +25,7 @@ import ProfileView from '@/views/oa/ProfileView.vue'
import { TASK_VIEW_KEY } from '@/components/oa/mobile/taskContext'
import { useAuthStore } from '@/stores/auth'
import { expenseDetail, expenseSchema, stubView } from '@/components/oa/mobile/mobileFixtures'
import type { FormFieldDef, FormSchema } from '@/types'
import type { FormFieldDef, FormSchema, MobileFieldLayout } from '@/types'
import { startOfWork } from '@/utils/approvalRecord'
import { i18n } from '@/i18n'
import zh from '@/i18n/locales/zh'
@ -153,37 +153,56 @@ function tabsPreviewSchema(): FormSchema {
return { fields: [host, ...cells], layout: { columns: 3 } }
}
/**
* `title=none`:节名留空,同时把「标签页」也撤掉。
*
* 只撤名字不撤页签看不出这一档——节名会回落到第一个页签名,那是起了名字的。撤干净之后
* 这张表既没起名也没分页,手机上就一节,名字由代码兜底补一句(`PlanGroup.generic`),
* 那一行标题连「N 项」和折叠箭头一起不摆,得眼看一次才知道正文一行没少。
* 生产上「工作联络单」配的就是这一版。
*/
const unnamedSection = params.get('title') === 'none'
const sectionTitle = unnamedSection ? '' : '费用报销基本信息'
/**
* `form=custom`:开了「手机端」面板那一档的样子——手机上只出一节。
*
* 这一档要眼看的正是"配成什么样就是什么样":节名、顺序、哪几格上屏、明细摊不摊开、
* 金额上不上抬头、末尾有没有「完整单据」,全在这份配置里,预览台把它摆出来对一遍。
*
* `&title=none` 摆的是节名留空那一档(见上面 `unnamedSection`)。
*/
function customPreviewSchema(): FormSchema {
const base = tabsPreviewSchema()
// 部门那一格存的是组织路径,不是部门名:预览台摆一条真的,手机上才能眼看它念成什么
const costDept = { key: 'cost_dept', label: '费用归属部门', type: 'dept' } as unknown as FormFieldDef
const cells = unnamedSection ? base.fields.filter((item) => item.type !== 'tabs') : base.fields
const entries: MobileFieldLayout[] = [
{ key: 'reason', style: 'block', label: '事由' },
{ key: 'amount', style: 'float' },
{ key: 'approved', style: 'float' },
{ key: 'days' },
{ key: 'trip' },
{ key: 'city' },
{ key: 'empty_note' },
{ key: 'starter' },
{ key: 'cost_dept' },
{ key: 'starter_dept' },
{ key: 'rows', style: 'list' },
{ key: 'invoices', style: 'gallery' },
// 「标签页」第二页整页是别人的系统:手机上给一张「打开」卡片,配置里点它的键带页签
{ key: 'tabs_host#tab_2', style: 'embed' }
]
return {
...base,
fields: [...cells, costDept],
layout: {
...(base.layout ?? {}),
mobile: {
enabled: true,
title: '费用报销基本信息',
title: sectionTitle,
showFullSheet: false,
fields: [
{ key: 'reason', style: 'block', label: '事由' },
{ key: 'amount', style: 'float' },
{ key: 'approved', style: 'float' },
{ key: 'days' },
{ key: 'trip' },
{ key: 'city' },
{ key: 'empty_note' },
{ key: 'starter' },
{ key: 'starter_dept' },
{ key: 'rows', style: 'list' },
{ key: 'invoices', style: 'gallery' },
// 「标签页」第二页整页是别人的系统:手机上给一张「打开」卡片,配置里点它的键带页签
{ key: 'tabs_host#tab_2', style: 'embed' }
]
fields: unnamedSection ? entries.filter((item) => !item.key.includes('#')) : entries
}
}
}
@ -196,7 +215,10 @@ const keyword = ref('')
const previewDetail = expenseDetail(open === 'readonly' ? { can_process: false } : {})
if (paginated) previewDetail.forms = [{ ...previewDetail.forms[0], content: tabsPreviewSchema() }]
if (customPreview) previewDetail.forms = [{ ...previewDetail.forms[0], content: customPreviewSchema() }]
if (customPreview) {
previewDetail.forms = [{ ...previewDetail.forms[0], content: customPreviewSchema() }]
previewDetail.data = { ...previewDetail.data, cost_dept: '紫光汇智\\软件开发事业部' }
}
const previewView = stubView(previewDetail, {
requiredMissing: open === 'missing' ? ['出差天数'] : [],
frozen: open === 'frozen',

View File

@ -146,7 +146,8 @@ export default {
// An array on purpose: t() reads "|" as a plural separator and would keep only the first form
phrases: ['Approved', 'Agree', 'Noted', 'Please check invoice compliance', 'Approved, mind next month budget'],
lookAgain: 'Not yet',
submitNext: 'Submit, next one',
// Done with this one: back to the todo list, which refetches on its own
submitBack: 'Submit, back to list',
pickRoute: 'Pick a route',
pickRouteHint: 'This step offers {count} routes; pick one, then add a note',
routeByCondition: 'Target decided by condition',
@ -296,7 +297,8 @@ export default {
ssoLocalLogin: 'Sign in with a local admin account',
ssoEntryHint: 'Accounts and passwords live in the unified portal. Sign in there, then open this app from the portal and you will be signed in automatically',
ssoEnter: 'Go to the unified portal',
ssoAutoJump: 'You will be sent to the unified portal in a moment, no account needed on this page',
ssoAutoJump: 'If you were not sent over on your own, use this button to reach the unified portal, no account needed here',
ssoJumping: 'Taking you to the unified portal, no account needed on this page',
ssoLocalOnlyHint: 'Everyone else signs in through the unified portal; this form is only for the break-glass local admin accounts',
ssoWorkingCode: 'The unified portal has confirmed your identity, opening your local session',
ssoErrDisabled: 'Unified portal sign-in is not enabled yet; ask an administrator to check the Hub URL, app code and integration key',
@ -3218,6 +3220,7 @@ export default {
orgRole: 'Job roles',
orgAuthRole: 'Permission roles',
monitorWork: 'Process monitor',
monitorExport: 'Process detail export',
statisticsView: 'Statistics',
logView: 'Operation logs',
systemSetting: 'System settings',
@ -3246,6 +3249,8 @@ export default {
weekday7: 'Sun',
jobFull: 'Full sync (org + people)',
jobChanges: 'Incremental sync (change feed)',
sectionOptions: 'What the sync writes',
optionsHint: 'These decide what a sync may write and when it should rather leave everything alone. Saving applies immediately and the next run (including "Sync now") follows them; they only affect the write side, never login.',
syncOrgs: 'Sync units',
syncOffboard: 'Offboard gone people',
memberLimit: 'People per run',
@ -3280,10 +3285,10 @@ export default {
colSummary: 'Result',
colOperator: 'Operator',
colDuration: 'Duration',
dirtyCount: '{value} unsaved schedule change(s)',
save: 'Save schedule',
dirtyCount: '{value} unsaved change(s)',
save: 'Save and apply',
saving: 'Saving',
saveDone: 'Schedule saved, the next scheduler tick already uses it: {value}'
saveDone: 'Saved, the next sync run already uses it: {value}'
},
hub: {
title: 'Unified Identity (Hub)',
@ -3356,6 +3361,28 @@ export default {
cntMobile: 'With mobile',
cntInactive: 'Disabled at hub',
cntUnassigned: 'Without organization',
cntRenamed: 'Naming follows Hub',
cntOffboardReal: 'Actually disabled',
cntZombieUnits: 'Stale duplicate units',
cntLocalUnits: 'Local-only units',
cntAccountRenames: 'Login renames',
cntNameRenames: 'Name renames',
cntAccountReleases: 'Zombie accounts released',
cntAccountConflicts: 'Login conflicts',
cntProtected: 'Protected, skipped',
cleanShells: 'Clean {value} empty unit shell(s)',
cleanShellsBusy: 'Cleaning',
cleanShellsHint: 'Only removes disabled shells whose code and name an active unit already took over, with no people, no children and no role scope',
cleanShellsConfirm: 'Delete these unit shells? They are the old rows Hub left behind after it re-numbered organizations: '
+ 'their code and name are already taken by an active unit, so sync will never rebind or merge them. '
+ 'Each one is re-checked before deletion; those with people, children or a role data scope are skipped. '
+ 'Permissions, documents and id-based settings are untouched.',
cleanShellsDone: 'Deleted {value} unit shell(s)',
cleanShellsDoneSkipped: 'Deleted {deleted} unit shell(s), {skipped} could not be removed (see the reasons on each)',
zombieUnitsSample: 'Stale duplicates:',
guardNotePeople: 'Offboard circuit breaker: {percent}% (never below {floor} people), so this run stops at {ceiling}; it would disable {pending}. Above the ceiling nobody gets disabled.',
guardNoteUnits: 'Unit circuit breaker: {percent}% (never below {floor} units), so this run stops at {ceiling}; it would disable {pending}. Above the ceiling no unit gets disabled.',
releaseBlockedNote: 'Hub returned fewer than {floor} people, so the directory looks wiped or re-imported: this run leaves every login name alone.',
offboardAccounts: 'Accounts to disable',
memberLimit: 'Member limit',
lastSync: 'Last sync',
@ -3391,6 +3418,16 @@ export default {
duration: 'Duration',
skipped: 'Data version unchanged, nothing written',
unchanged: 'No changes',
renamedCount: '{value} renamed',
reclaimedCount: '{value} accounts freed',
unitsReboundCount: '{value} units rebound',
detailAccountRenames: 'Account renames: {items}',
detailNameRenames: 'Name renames: {items}',
detailReclaimed: 'Freed accounts: {items}',
detailRebound: 'Units rebound by code: {items}',
detailMore: ' ({total} total, first {shown} shown)',
detailGuardPeople: 'Breaker held off disabling {value} people, nobody was disabled',
detailGuardUnits: 'Breaker held off disabling {value} units, no unit was disabled',
ssoChannel: 'SSO channel',
ssoChannelOnly: 'SSO channel (SSO only)',
ssoActive: 'Ready (app code {code})',
@ -4496,6 +4533,26 @@ export default {
resend: 'Requeue',
sendNow: 'Send now',
queued: 'Requeued',
recheck: 'Check delivery',
recheckHint: 'Ask the identity hub for this message per-recipient result (read only, repeatable) and refresh this row',
rechecked: 'Refreshed from the hub',
hubWhere: 'via identity hub',
hubMsgtype: 'Message shape',
hubReceiver: 'Recipient id',
hubReceiverHint: 'Which column identifies the person on the hub; the order is the priority. Pick a single id and there is no fallback - people without it are skipped, with the reason written into the delivery log.',
hubReceiverCoverage: '{active} active accounts: this option reaches {covers}; {none} have neither id (unreachable until somebody fills them in).',
hubReceiverVia: 'matched by {fields}',
hubWithLink: 'Deep link to the item (opens straight on that task)',
hubLinkHint: 'Off sends a plain reminder with no link and no click-through. A card with nothing to point at already falls back to plain text.',
hubDegradedNoLink: 'Nothing to point this at (meeting reminders), so it went out as a plain reminder without a link',
hubDegradedNoHome: 'The hub has no home URL for this system, so it went out as a plain reminder without a link; new messages carry the deep link once it is filled in',
hubTitleLimit: 'Title budget (chars)',
hubTitleLimitHint: 'The hub prefixes the app name in brackets and rejects anything past 128 characters in total, so this is what is left for our own title.',
hubReady: 'Egress: {base} (hub app code {app}). The key is shared with single sign-on and directory sync, nothing to type here.',
hubMissing: 'The hub cannot push WeCom yet, missing: {items}. Fix it in Settings - Unified identity.',
hubPrereq: 'Two things still needed on the hub: the global push switch and this app push switch both on, and this system home URL registered (not a site-root file, or the deep link will not open). Either one off and the hub rejects the call.',
hubLinkOpen: 'Open this push link in a browser: the hub identifies the person first, then signs them into this system',
testSentHub: 'Handed to the hub - check your own WeCom; the link should land on your task list',
willRetryAt: 'Next retry',
stPending: 'Pending',
stSending: 'Sending',
@ -4889,6 +4946,124 @@ export default {
}
}
},
detailExport: {
title: 'Process Detail Export',
desc: 'Pick the processes, the form fields and the filters yourself, then export a detail sheet you can reconcile directly. Data scope follows Process monitor: anything hidden there cannot be exported here.',
keyword: 'Keyword',
keywordPlaceholder: 'Title / serial / process / initiator',
creator: 'Created by',
creatorByPerson: 'By person',
creatorByUnit: 'By unit',
creatorByKeyword: 'By name',
creatorPickPerson: 'Select creators',
creatorPickUnit: 'Select units',
creatorKeywordPlaceholder: 'Initiator name contains',
includeSubUnit: 'Include sub-units',
createDate: 'Created',
archiveDate: 'Archived',
status: 'Status',
statusPaused: 'Suspended',
unoperator: 'Pending on',
unoperatorPlaceholder: 'Select people',
unopMode: 'Match',
unopModeAny: 'Any of',
unopModeAll: 'All of',
unopModeNot: 'None of',
unopKinds: 'What counts as untouched',
unopIncludePrincipal: 'Count the delegator too',
unopIncludePrincipalHint: 'After a transfer or delegation, should the original holder still count as untouched',
unopExcludeLocked: 'Exclude steps locked by an external system',
unopExcludeLockedHint: 'When an external system decides whether the buttons are clickable, the person cannot act, so do not blame them',
unopNeedKind: 'If you pick people, tick at least one rule for what counts as untouched',
kinds: {
task: 'Task untouched',
readPlain: 'Read receipt unopened',
readAction: 'Actionable CC unanswered',
terminate: 'Silent at termination',
addPending: 'Pending co-signer'
},
kindHelp: {
task: 'The task still sits in their inbox unprocessed. An inactive pre-co-sign task is counted under "Pending co-signer" instead.',
readPlain: 'A plain read receipt never opened (never opened = untouched). Opening it once clears this.',
readAction: 'An actionable CC expects an opinion: merely opening it is not enough, no reply still counts as untouched.',
terminate: 'At termination the system force-closed their task and they never took a position; the conclusion belongs to whoever terminated it.',
addPending: 'A pre-co-sign task exists but the step is not active yet. Off by default — they had nothing to act on.',
footer: 'Archived workbooks are covered too: an unopened read receipt is never migrated, it stays behind flagged as completed, so the filter still finds it. Transfers and delegations do not punish the wrong person — the task counts against whoever holds it now.'
},
projectName: 'Project name',
projectCode: 'Project code',
projectMatch: 'Match',
projectMatchEq: 'Equals',
projectMatchContains: 'Contains',
projectNone: 'None of the selected processes has a project field; drop the project filter or pick other processes.',
pickProcess: 'Processes',
processSearch: 'Search process or category',
processSelected: '{count} selected',
processLimit: 'Up to {count} processes per run',
processGroupOther: 'Uncategorised',
pickFields: 'Columns',
colBase: 'Workbook columns',
colUnoperator: 'Pending on',
colForm: 'Form fields',
colActivity: 'Step detail',
colSearch: 'Search columns',
colSelected: '{count} columns',
colCommon: 'Restore common set',
colCommonSave: 'Set as common set',
colCommonUpdate: 'Update common set',
colCommonRemove: 'Unset common set',
colCommonTag: 'Custom set: {count}',
colCommonTagHint: 'A common set you saved yourself. While your ticks match it exactly, that button reads "Unset common set"',
colCommonSaveHint: 'Save the {count} ticked columns as your common set; "Restore common set" comes back to it',
colCommonUpdateHint: 'The {count} columns ticked now differ from your saved set - overwrite it with these',
colCommonRemoveHint: 'Drop this custom common set; "Restore common set" falls back to the shipped one',
colCommonEmpty: 'Tick a few columns before saving a common set',
colCommonSaved: 'Saved {count} columns as your common set',
colCommonUpdated: 'Common set updated ({count} columns)',
colCommonRemoved: 'Custom common set removed; restoring falls back to the shipped one',
colCommonDropped: '{count} saved columns are not in the selected processes, so they were skipped',
colCommonRestoreCustom: 'Use your saved common set ({count} columns)',
colCommonRestoreDefault: 'Use the shipped common set ({count} columns)',
colClear: 'Clear columns',
colShared: 'A shared field name is ticked once and exported for every selected process',
colMissing: 'This process has no such field, so the column will not appear in its sheet',
colLayoutOnly: 'Layout only',
colLimit: 'This run needs {count} columns, above the {limit}-column limit',
colNone: 'Tick processes on the left to list their form fields here',
activityLimit: 'Up to {count} step groups; the rest were skipped',
headerBar: 'Sheet header',
headerSheets: '{count} sheet(s) will be produced',
headerRows: '~{total} rows',
headerEmpty: 'No columns ticked yet',
headerShow: 'Show header',
headerHide: 'Hide header',
layout: 'Sheet layout',
layoutPerProcess: 'One sheet per process',
layoutMerged: 'Merge into one sheet',
layoutPerProcessHint: 'Each process gets its own sheet, so its own fields stay in their own columns.',
layoutMergedHint: 'All processes in one sheet, headers unioned with a fixed process column; process-specific fields leave empty cells.',
layoutCsvBlocked: 'CSV is always a single sheet; per-process layout is unavailable with CSV.',
summary: 'Add a summary sheet',
summaryHint: 'Prepend a process / row-count / duration summary for reconciliation.',
format: 'File format',
fmtXlsx: 'Excel',
fmtCsv: 'CSV',
preview: 'Preview',
download: 'Export',
downloading: 'Building the file…',
downloaded: 'Exported {name}',
count: 'Estimate rows',
counting: 'Counting…',
counted: '{total} rows matched',
exceeded: 'This run matches {total} rows, above the {limit}-row limit: narrow the dates or select fewer processes',
needProcess: 'Tick at least one process',
needColumn: 'Tick at least one column',
previewEmpty: 'Pick processes and columns, then preview before exporting',
prefsSaved: 'Remembered these processes and columns',
reloadCatalog: 'Reload process catalog',
sheetSummary: 'Summary',
totalRows: '{count} rows'
},
error: {
notFoundTitle: 'Page not found',
notFoundDesc: 'This page may have been removed or the address is wrong',

View File

@ -142,7 +142,8 @@ export default {
// 存成数组:t() 会把 | 当复数分隔符,串着存只会剩第一条
phrases: ['同意', '拟同意', '已阅', '请财务注意发票合规', '同意,注意下月额度'],
lookAgain: '再看看',
submitNext: '提交,看下一条',
// 办完这张就回待办列表:列表自己会重新取一次,剩下的那几条摆在眼前
submitBack: '提交,回待办',
pickRoute: '选一个出口',
pickRouteHint: '这一环配了 {count} 条出口,选完再写意见',
routeByCondition: '去向由条件决定',
@ -292,7 +293,8 @@ export default {
ssoLocalLogin: '用本地管理员账号登录',
ssoEntryHint: '本系统的账号密码统一由统一门户管理:请前往统一门户登录,再在门户里点击本系统,就会自动进入',
ssoEnter: '前往统一门户',
ssoAutoJump: '几秒后自动前往统一门户,无需在本页输入账号密码',
ssoAutoJump: '没有自动跳过去时,点上面这个按钮前往统一门户,无需在本页输入账号密码',
ssoJumping: '正在前往统一门户,无需在本页输入账号密码',
ssoLocalOnlyHint: '普通用户请从统一门户免登进入;这一栏只给应急用的本地管理员账号',
ssoWorkingCode: '统一门户已经验过身份,正在为你建立本地会话,请稍候',
ssoErrDisabled: '统一门户免登还没有启用,请联系管理员检查 Hub 站点地址、应用编码与免登应用密钥',
@ -3206,6 +3208,7 @@ export default {
orgRole: '岗位角色',
orgAuthRole: '权限角色',
monitorWork: '流程监控',
monitorExport: '流程明细导出',
statisticsView: '统计分析',
logView: '操作日志',
systemSetting: '系统设置',
@ -3234,6 +3237,8 @@ export default {
weekday7: '周日',
jobFull: '全量同步(组织 + 人员)',
jobChanges: '增量同步(变更流水)',
sectionOptions: '同步落库口径',
optionsHint: '这几项决定同步往库里写什么、什么情况下宁可一动不动。保存即生效,下一趟同步(含手动点的「立即同步」)就按新口径走;它们只管写库,不影响登录。',
syncOrgs: '同步部门',
syncOffboard: '离职停用',
memberLimit: '单次人员上限',
@ -3268,10 +3273,10 @@ export default {
colSummary: '结果',
colOperator: '操作人',
colDuration: '耗时',
dirtyCount: '{value} 项排期改动未保存',
save: '保存排期',
dirtyCount: '{value} 项改动未保存',
save: '保存并生效',
saving: '保存中',
saveDone: '排期已保存,下一次调度就按新排期走:{value}'
saveDone: '已保存,下一趟同步就按新值走:{value}'
},
hub: {
title: '统一身份认证(Hub)',
@ -3344,6 +3349,27 @@ export default {
cntMobile: '带手机号',
cntInactive: 'Hub 已停用',
cntUnassigned: '无所属组织',
cntRenamed: '跟随 Hub 改名',
cntOffboardReal: '这趟真停用',
cntZombieUnits: '重名壳子部门',
cntLocalUnits: '本地自建部门',
cntAccountRenames: '登录名改名',
cntNameRenames: '姓名改名',
cntAccountReleases: '僵尸账号让位',
cntAccountConflicts: '登录名冲突',
cntProtected: '受保护跳过',
cleanShells: '清理 {value} 个空壳部门',
cleanShellsBusy: '清理中',
cleanShellsHint: '只删「已停用 + 同名同码的在职部门已经接住身份 + 没人没下级没被角色引用」的那几具',
cleanShellsConfirm: '删除这些空壳部门?它们是 Hub 换过主键之后留下的旧身子:编码与名称都已被在职部门接管,'
+ '同步不会再认它们,也不会自动合并。删掉之前会再核一遍,还有人、有下级或被角色当数据范围的都会跳过。'
+ '权限、单据和按主键挂的配置都不受影响。',
cleanShellsDone: '已删除 {value} 个空壳部门',
cleanShellsDoneSkipped: '已删除 {deleted} 个空壳部门,{skipped} 个删不掉(原因见部门上的说明)',
zombieUnitsSample: '重名壳子:',
guardNotePeople: '离职停用熔断:{percent}%(且不少于 {floor} 人),这趟最多停 {ceiling} 人;预计停用 {pending} 人,跨过线就一个都不停用。',
guardNoteUnits: '部门停用熔断:{percent}%(且不少于 {floor} 个),这趟最多停 {ceiling} 个;预计停用 {pending} 个,跨过线就一个都不停。',
releaseBlockedNote: 'Hub 这趟回的人数不足 {floor},目录像是在清空或重导:这一趟不会动任何人的登录名。',
offboardAccounts: '将被停用的账号',
memberLimit: '单次人员上限',
lastSync: '上次同步',
@ -3379,6 +3405,16 @@ export default {
duration: '耗时',
skipped: '数据版本未变化,已跳过写入',
unchanged: '无变更',
renamedCount: '改名 {value} 人',
reclaimedCount: '账号让位 {value} 个',
unitsReboundCount: '认回部门 {value} 个',
detailAccountRenames: '登录名改名:{items}',
detailNameRenames: '姓名改名:{items}',
detailReclaimed: '僵尸账号让位:{items}',
detailRebound: '按编码认回部门:{items}',
detailMore: '(共 {total} 条,这里列前 {shown} 条)',
detailGuardPeople: '熔断挡住了 {value} 人的离职停用,这一趟一个人都没停',
detailGuardUnits: '熔断挡住了 {value} 个部门的停用,这一趟一个部门都没停',
ssoChannel: '免登通道',
ssoChannelOnly: '免登通道(仅免登)',
ssoActive: '可用(应用编码 {code})',
@ -4494,6 +4530,26 @@ export default {
resend: '重新排队',
sendNow: '立刻再发一次',
queued: '已重新排队',
recheck: '回查送达',
recheckHint: '问统一身份 Hub 要这一条的逐人投递结果(只读,可反复点),按对方的记录改写这条',
rechecked: '已按 Hub 的记录更新',
hubWhere: '经统一身份 Hub',
hubMsgtype: '消息形态',
hubReceiver: '收件人标识',
hubReceiverHint: '这一路按哪一列认人:顺序就是优先级。只选一种时不退回另一种——那种标识取不到值的人会被跳过,投递记录里写明原因。',
hubReceiverCoverage: '在职账号 {active} 人:按这一档能发到 {covers} 人,{none} 人两种标识都没有(怎么配都收不到,得先补资料)。',
hubReceiverVia: '按 {fields} 认人',
hubWithLink: '带单据深链(点开直达那条待办)',
hubLinkHint: '关掉就发纯文字提醒:不生成链接,也就没有点开那一跳。卡片形态在没有单据可指时会自动退成纯文字。',
hubDegradedNoLink: '没有单据可指(会议提醒那类),已发成不带链接的纯提醒',
hubDegradedNoHome: 'Hub 未登记本系统首页地址(home_url),已发成不带链接的纯提醒;补好后新消息自动带回深链',
hubTitleLimit: '标题字数上限',
hubTitleLimitHint: 'Hub 会在标题前面强制加【应用名称】,两边合计不超过 128 字符,超了整条被拒。这一格是留给自己标题的额度。',
hubReady: '出口:{base}(Hub 应用编码 {app})。密钥与免登、组织人员同步共用同一把,这里不用再填。',
hubMissing: '统一身份这边还发不出企业微信,缺:{items}。到「系统设置 → 统一身份」补上。',
hubPrereq: 'Hub 侧还要两件事:全局推送开关与本应用的推送开关都打开;登记本系统的首页地址(别填成站点根级文件,否则拼出的深链打不开)。任一没开,Hub 会当场拒收。',
hubLinkOpen: '在浏览器里打开这条推送链接:Hub 先认人,再免登跳回本系统',
testSentHub: '已交给 Hub,去你自己的企业微信里看一眼;点开应落到待办列表',
willRetryAt: '下次重试',
stPending: '待发送',
stSending: '发送中',
@ -4887,6 +4943,124 @@ export default {
}
}
},
detailExport: {
title: '流程明细导出',
desc: '自选流程、自选表单字段、自选筛选条件,导一张能直接拿去对账的明细表。数据范围与流程监控一致:监控里看不到的单子,这里也导不出来。',
keyword: '关键字',
keywordPlaceholder: '标题 / 单号 / 流程 / 发起人',
creator: '创建人',
creatorByPerson: '按人员',
creatorByUnit: '按部门',
creatorByKeyword: '按姓名',
creatorPickPerson: '选择创建人',
creatorPickUnit: '选择部门',
creatorKeywordPlaceholder: '发起人姓名包含',
includeSubUnit: '含下级部门',
createDate: '创建日期',
archiveDate: '归档日期',
status: '流程状态',
statusPaused: '已挂起',
unoperator: '未操作者',
unoperatorPlaceholder: '选择人员,可多选',
unopMode: '匹配方式',
unopModeAny: '包含任一',
unopModeAll: '包含全部',
unopModeNot: '不包含',
unopKinds: '算未操作的口径',
unopIncludePrincipal: '算上转办 / 代理的委托方',
unopIncludePrincipalHint: '待办转到别人名下后,原来那个人还要不要算未操作',
unopExcludeLocked: '排除表态锁在外部系统的环节',
unopExcludeLockedHint: '这一环的按钮由外部系统决定能不能点时,人点不了,也就别记在他账上',
unopNeedKind: '挑了人就得勾至少一种「算未操作」的口径,不然这条筛选没有判据',
kinds: {
task: '待办未处理',
readPlain: '待阅未打开',
readAction: '抄送需处理未回复',
terminate: '终止时未表态',
addPending: '加签未激活'
},
kindHelp: {
task: '待办还挂在人名下没处理。前置加签还没激活的那条不算在这里,见「加签未激活」。',
readPlain: '普通待阅一条都没打开过(没打开 = 没操作)。只要点开过一次就不算了。',
readAction: '「抄送需处理」要求回处理意见:光打开不算,没回意见照样算未操作。',
terminate: '单子终止那一刻待办被系统强行结掉,本人从头到尾没表过态;结论记在动手终止的人身上。',
addPending: '前置加签派下去了但环节还没激活,待办已经在这个人名下。默认不算——激活之前他确实无从下手。',
footer: '归档单子的待阅也能查:没打开过的待阅归档时不迁表,行还留在原表里打了完成标记,所以「只看未操作者」在已归档流程上同样查得出来。转办和代理派单不背锅:待办照旧算在当前持有人头上没操作。'
},
projectName: '相关核算项目名称',
projectCode: '相关核算项目编码',
projectMatch: '匹配方式',
projectMatchEq: '等于',
projectMatchContains: '包含',
projectNone: '所选流程里没有「相关核算项目」这一格,去掉项目筛选或换流程。',
pickProcess: '选流程',
processSearch: '搜索流程名称或分类',
processSelected: '已选 {count} 条',
processLimit: '一次最多 {count} 条流程',
processGroupOther: '未分类',
pickFields: '选字段',
colBase: '单据固有列',
colUnoperator: '未操作者',
colForm: '表单字段',
colActivity: '环节明细',
colSearch: '搜索列名',
colSelected: '已选 {count} 列',
colCommon: '恢复常用列',
colCommonSave: '设为常用列',
colCommonUpdate: '更新常用列',
colCommonRemove: '取消常用列',
colCommonTag: '自定义常用列 {count} 列',
colCommonTagHint: '这套常用列是你自己存的。当前勾的跟它一模一样时,那颗按钮会变成「取消常用列」',
colCommonSaveHint: '把当前勾的 {count} 列存成你的常用列,以后点「恢复常用列」就回到这套',
colCommonUpdateHint: '当前勾的 {count} 列和存好的常用列不一样,点这里用这套盖掉它',
colCommonRemoveHint: '取消这套自定义常用列,「恢复常用列」回到出厂默认那套',
colCommonEmpty: '先勾几列,再存成常用列',
colCommonSaved: '已把 {count} 列设为常用列',
colCommonUpdated: '已更新常用列({count} 列)',
colCommonRemoved: '已取消自定义常用列,「恢复常用列」回到出厂默认那套',
colCommonDropped: '常用列里有 {count} 列不在所选流程里,这次没带回来',
colCommonRestoreCustom: '用你存的这套常用列({count} 列)',
colCommonRestoreDefault: '用出厂默认的常用列({count} 列)',
colClear: '清空列',
colShared: '同名字段勾一次,所有已选流程一起出这一列',
colMissing: '这条流程没这一格,它那张表里不会出现这列',
colLayoutOnly: '版面格',
colLimit: '这次要出 {count} 列,超过单张表上限 {limit} 列',
colNone: '先在左边勾流程,这里才会列出各流程的表单字段',
activityLimit: '环节列最多 {count} 个,多出来的没算进去',
headerBar: '本次表头',
headerSheets: '将出 {count} 张表',
headerRows: '预计 {total} 行',
headerEmpty: '还没勾列',
headerShow: '看表头',
headerHide: '收起表头',
layout: '出表方式',
layoutPerProcess: '按流程分表',
layoutMerged: '合并成一张表',
layoutPerProcessHint: '一条流程一个 sheet,各自的表单字段各自成列,不串味。',
layoutMergedHint: '所有流程并成一张表,表头取并集、固定带「流程」列;不同流程各自的专属字段会留下空列。',
layoutCsvBlocked: 'CSV 只能是一张表,切到 CSV 后按流程分表不可用。',
summary: '附一张汇总表',
summaryHint: '在最前面加一张「流程 / 条数 / 耗时」的对账用汇总。',
format: '文件格式',
fmtXlsx: 'Excel',
fmtCsv: 'CSV',
preview: '预览',
download: '导出',
downloading: '正在出文件…',
downloaded: '已导出 {name}',
count: '算一下行数',
counting: '正在统计…',
counted: '命中 {total} 行',
exceeded: '这次命中 {total} 行,超过单次上限 {limit} 行:请收窄日期或减少流程条数',
needProcess: '至少勾一条流程',
needColumn: '至少勾一列',
previewEmpty: '勾好流程和列,点这里先看一眼再导',
prefsSaved: '已记住这次的流程与字段',
reloadCatalog: '刷新流程目录',
sheetSummary: '汇总',
totalRows: '{count} 行'
},
error: {
notFoundTitle: '页面不存在',
notFoundDesc: '您访问的页面可能已被移除或地址有误',

View File

@ -268,6 +268,13 @@ const routes: RouteRecordRaw[] = [
component: () => import('@/views/oa/MonitorView.vue'),
meta: { titleKey: 'monitor.title', permission: 'monitor:work' }
},
{
// 流程明细导出:一条独立菜单、一个独立权限码,不是流程监控的子页
path: 'export/detail',
name: 'detail-export',
component: () => import('@/views/oa/ProcessDetailExportView.vue'),
meta: { titleKey: 'detailExport.title', permission: 'monitor:export' }
},
{
path: 'statistics',
name: 'statistics',

View File

@ -3924,8 +3924,9 @@ export interface NotifyChannel {
id?: number
code: string
name: string
/** email 邮件;dingtalk / feishu / wecom 群机器人;webhook 自定义回调 */
kind: 'email' | 'dingtalk' | 'feishu' | 'wecom' | 'webhook'
/** email 邮件;dingtalk / feishu / wecom 群机器人;webhook 自定义回调;
* hub_wecom 企业微信应用消息(交给统一身份 Hub 代发,本系统不持有企微密钥) */
kind: 'email' | 'dingtalk' | 'feishu' | 'wecom' | 'webhook' | 'hub_wecom'
kindLabel?: string
enabled: boolean
/** 订阅的消息类型,取值同站内信的 type */
@ -3942,6 +3943,10 @@ export interface NotifyChannel {
lastError?: string
/** 现在还缺什么;空数组 = 配齐了 */
problems?: string[]
/** 走 Hub 的渠道:认人用的标识顺序(如 `['user_id','account']`);其它渠道为空 */
receiverPref?: string[]
/** 上面那串顺序的人话:`Hub 用户 ID → 登录账号` */
receiverLabel?: string
today?: { success: number; failed: number; skipped: number }
}
@ -3956,6 +3961,11 @@ export interface NotifyDelivery {
personName?: string
/** 收件地址;机器人地址里的 token 已打码 */
target?: string
/** 走统一身份 Hub 那一路时,`target` 是按哪一列取的(`user_id` / `account`):
* 一串数字分不清是 Hub 主键还是登录账号,排查时这是两回事 */
targetField?: string
/** 上面那一列的中文名,后端直接给;空 = 这条不是 Hub 渠道 */
targetFieldLabel?: string
title?: string
body?: string
job?: string
@ -3970,11 +3980,58 @@ export interface NotifyDelivery {
ms?: number
}
/** 统一身份 Hub 那一半的配置状态:渠道页只读它,改在「系统设置 → 统一身份」。 */
export interface NotifyHubStatus {
/** 站点、应用密钥都齐了,这一路发得出去 */
ready: boolean
/** 还缺哪几项,界面直接念 */
missing: string[]
baseUrl: string
appCode: string
keySet: boolean
pushPath: string
/** 应急总闸(OA_HUB_DISABLED)开着:Hub 相关一律回本地,推送也停 */
forcedOff: boolean
timeoutSeconds: number
}
export interface NotifyMeta {
kinds: Array<{ value: string; label: string }>
events: Array<{ value: string; label: string }>
textVars: Array<{ value: string; label: string }>
smtpPresets: Array<{ label: string; port: number; security: string }>
hubMsgtypes: Array<{ value: string; label: string }>
/** Hub 认收件人用的几种标识(渠道 `config.receiver` 的取值)与常用的几种顺序组合 */
hubReceivers?: Array<{ value: string; label: string; column: string }>
hubReceiverPresets?: Array<{ value: string[]; label: string; hint: string }>
hubReceiverDefault?: string[]
hub?: NotifyHubStatus
}
/** 在职账号里各收件标识能覆盖多少人:换标识之前先看这一眼,别等投出一堆 skipped。 */
export interface NotifyReceiverCoverage {
/** 在职账号总数 */
active: number
/** 每一种标识**各自**取到值的人数 */
fields: Record<string, number>
/** 几种都试一遍能发到的人数 */
any: number
/** 怎么配都发不到的人数——这一档要有人去补资料 */
none: number
}
/** Hub 回传的逐人投递明细(投递记录 response.hub 里那一份)。 */
export interface NotifyHubDetail {
msgKey?: string
status?: string
link?: string
reason?: string
attempt?: number
sentAt?: string
duplicate?: boolean
wecomUserId?: string
recheckedAt?: string
degraded?: string
}
export interface NotifyList<T> {

View File

@ -899,6 +899,22 @@ export function spacerHeight(field?: { height?: number } | null): number {
/** 星期几的取值:1-7,周一到周日(与 ISO 星期同号,导出去别处也对得上)。 */
export const WEEK_DAY_VALUES: readonly string[] = ['1', '2', '3', '4', '5', '6', '7']
/**
* 星期几那一格的读法:库里存的是 ``1``-``7``,念的时候要换成「周一、周三」。
*
* 名字由调用方给(界面上念的是词条 ``form.weekdayN``),这一层不碰 i18n——它整个文件
* 是后端 ``service/formruntime.py`` 的镜像,翻译是界面那一片的事。桌面只读态与手机版式
* (``components/oa/mobile/useFormPlan.ts:fieldText``)都读这一句,两边不会各切一套星期。
*/
export function weekText(value: unknown, label: (day: string) => string): string {
const list = Array.isArray(value) ? value : value === null || value === undefined || value === '' ? [] : [value]
return list
.map((item) => String(item))
.filter((item) => WEEK_DAY_VALUES.includes(item))
.map((item) => label(item))
.join('、')
}
/**
* 多选月份(``type=months``)那一格的取值:``['2026-10', '2026-11']``。
*

View File

@ -1,7 +1,13 @@
import { describe, expect, it } from 'vitest'
import type { HubSyncCancelResult } from '@/api/hub'
import type { HubSyncCancelResult, HubSyncRun } from '@/api/hub'
import zh from '@/i18n/locales/zh'
import { describeCancelResult, stuckRunCount, syncLooksStuck } from './hubSync'
import {
describeCancelResult,
describeRunDetails,
describeRunSummary,
stuckRunCount,
syncLooksStuck
} from './hubSync'
const t = (key: string, named?: Record<string, unknown>) => {
const value = key.split('.').reduce<unknown>((acc, part) => (acc as Record<string, unknown>)?.[part], zh)
@ -84,3 +90,123 @@ describe('describeCancelResult', () => {
expect(zh.hub.cancel).toBe('终止')
})
})
/** 一条执行记录,只填界面上真会读的字段。 */
function runOf(patch: Partial<HubSyncRun> = {}): HubSyncRun {
return {
id: 'r1',
trigger: 'manual',
trigger_label: '手工',
status: 'success',
started_at: '2026-11-05 10:02:00',
finished_at: '2026-11-05 10:02:09',
duration_ms: 9000,
total_users: 99,
returned_users: 99,
created: 0,
updated: 0,
offboarded: 0,
units_created: 0,
units_updated: 0,
units_offboarded: 0,
permission_version: 74,
member_limit: 5000,
truncated: false,
credential: 'directory_key',
credential_label: '目录密钥',
operator: '1',
operator_name: '管理员',
message: '',
unchanged: true,
...patch
} as HubSyncRun
}
describe('describeRunSummary', () => {
it('增量那一趟只说落了几条变更和游标', () => {
expect(describeRunSummary(runOf({ trigger: 'changes', changes_applied: 3, cursor_seq: 812 }), t)).toBe(
'落库 3 条 · 812'
)
})
it('版本没变的那一趟说跳过,不摆一串 0', () => {
expect(describeRunSummary(runOf({ status: 'skipped' }), t)).toContain('已跳过写入')
})
it('全 0 且后端说无变更,才写「无变更」', () => {
expect(describeRunSummary(runOf(), t)).toBe('无变更')
})
it('只有改名的那一趟不算无变更,改名/让位/认回都要报出来', () => {
const text = describeRunSummary(
runOf({ unchanged: true, updated: 99, renamed: 14, reclaimed: 68, units_rebound: 2 }),
t
)
expect(text).toContain('改名 14 人')
expect(text).toContain('账号让位 68 个')
expect(text).toContain('认回部门 2 个')
expect(text).not.toBe('无变更')
})
it('没动部门时不摆部门那一格,动了才摆', () => {
expect(describeRunSummary(runOf({ created: 1, unchanged: false }), t)).not.toContain('部门 新增/更新')
const withUnits = describeRunSummary(
runOf({ created: 1, unchanged: false, units_created: 14, units_offboarded: 2 }),
t
)
expect(withUnits).toContain('部门 新增/更新 14/0')
expect(withUnits).toContain('部门停用 2')
})
it('后端还没有这几个字段时照旧出句子,不写 undefined', () => {
const text = describeRunSummary(runOf({ created: 2, updated: 3, offboarded: 1, unchanged: false }), t)
expect(text).toBe('新增人员 2 · 更新人员 3 · 停用人员 1')
})
})
describe('describeRunDetails', () => {
it('没有明细的老记录什么都不摆', () => {
expect(describeRunDetails(runOf(), t)).toEqual([])
})
it('改名、让位、认回各自成一句,名字点到位', () => {
const lines = describeRunDetails(
runOf({
details: {
account_renames: ['zhangsan →lisi'],
name_renames: ['张三 →章三'],
reclaimed_accounts: ['wangwu →hub-lost-88-wangwu'],
rebound_units: ['研发中心(Hub 12 → 77)'],
renamed: 1,
reclaimed: 1,
units_rebound: 1,
name_renamed: 1
}
}),
t
)
expect(lines.join('\n')).toContain('登录名改名:zhangsan →lisi')
expect(lines.join('\n')).toContain('姓名改名:张三 →章三')
expect(lines.join('\n')).toContain('僵尸账号让位:wangwu →hub-lost-88-wangwu')
expect(lines.join('\n')).toContain('按编码认回部门:研发中心(Hub 12 → 77)')
})
it('名单被上限裁掉时说清总共多少条,别让人以为是全部', () => {
const lines = describeRunDetails(
runOf({ details: { account_renames: ['a →b', 'c →d'], renamed: 97 } }),
t
)
expect(lines[0]).toContain('共 97 条,这里列前 2 条')
})
it('熔断挡住的那部分单独成句:这一趟少干了活', () => {
const lines = describeRunDetails(runOf({ details: { guards: { people: 87, units: 6 } } }), t)
expect(lines.join('\n')).toContain('熔断挡住了 87 人的离职停用')
expect(lines.join('\n')).toContain('熔断挡住了 6 个部门的停用')
})
it('只给了计数没给名单时不摆空句子', () => {
expect(describeRunDetails(runOf({ details: { account_renames: [], renamed: 0 } }), t)).toEqual([])
})
})

View File

@ -5,7 +5,7 @@
* (``views/oa/SyncScheduleView.vue``)都要回答同一个问题,判据错一处就会变成"明明卡住
* 了却不给出口"或"跑得好好的却摆一颗终止按钮",所以口径只写在这一个地方。
*/
import type { HubStatus, HubSyncCancelResult } from '@/api/hub'
import type { HubStatus, HubSyncCancelResult, HubSyncRun } from '@/api/hub'
type Translate = (key: string, named?: Record<string, unknown>) => string
@ -39,3 +39,63 @@ export function describeCancelResult(result: HubSyncCancelResult, t: Translate):
if (result.stopping) parts.push(t('hub.cancelStopping'))
return parts.join(' · ')
}
/**
* 一条同步记录在界面上该说的那句话。
*
* 页头的同步结果框和「同步定时任务」的执行记录以前各写一份:一份报「新增/更新/停用」,
* 一份还带部门,改名与僵尸账号让位两边都不报 —— 而这恰恰是最需要人去核对的两类动作。
* 口径收在这一个函数里,两边读到的永远是同一句。
*/
export function describeRunSummary(row: HubSyncRun, t: Translate): string {
if (row.trigger === 'changes') {
return `${t('hub.changesAppliedCount', { value: row.changes_applied ?? 0 })}${
row.cursor_seq ? ` · ${row.cursor_seq}` : ''
}`
}
if (row.status === 'skipped') return t('hub.skipped')
// 旧记录没有这三个数(后端还没这两列时全是 undefined),按 0 处理就好
const renamed = row.renamed ?? 0
const reclaimed = row.reclaimed ?? 0
const rebound = row.units_rebound ?? 0
if (row.unchanged && !renamed && !reclaimed && !rebound) return t('hub.unchanged')
const parts = [
`${t('hub.created')} ${row.created}`,
`${t('hub.updated')} ${row.updated}`,
`${t('hub.offboarded')} ${row.offboarded}`
]
if (row.units_created || row.units_updated || row.units_offboarded) {
parts.push(`${t('hub.units')} ${row.units_created}/${row.units_updated}`)
if (row.units_offboarded) parts.push(`${t('hub.unitsOffboarded')} ${row.units_offboarded}`)
}
if (renamed) parts.push(t('hub.renamedCount', { value: renamed }))
if (reclaimed) parts.push(t('hub.reclaimedCount', { value: reclaimed }))
if (rebound) parts.push(t('hub.unitsReboundCount', { value: rebound }))
return parts.join(' · ')
}
/**
* 这一趟的名单级明细:改的是谁、谁让出了登录名、哪些部门被认了回来。
*
* ``message`` 是整段 2000 字的文本,名字排在后面就会被裁掉;``details`` 按类存了有界名单,
* 这里只负责把它拼成短句。名单被上限裁掉时补一句「共 N 条」,免得看着像全部。
*/
export function describeRunDetails(row: HubSyncRun, t: Translate): string[] {
const detail = row.details
if (!detail) return []
const lines: string[] = []
const add = (label: string, items: string[] | undefined, total: number | undefined) => {
if (!items?.length) return
const more =
total && total > items.length ? t('hub.detailMore', { total, shown: items.length }) : ''
lines.push(t(label, { items: items.join('、') + more }))
}
add('hub.detailAccountRenames', detail.account_renames, detail.renamed)
add('hub.detailNameRenames', detail.name_renames, detail.name_renamed)
add('hub.detailReclaimed', detail.reclaimed_accounts, detail.reclaimed)
add('hub.detailRebound', detail.rebound_units, detail.units_rebound)
if (detail.guards?.people) lines.push(t('hub.detailGuardPeople', { value: detail.guards.people }))
if (detail.guards?.units) lines.push(t('hub.detailGuardUnits', { value: detail.guards.units }))
return lines
}

View File

@ -54,6 +54,16 @@ describe('打开系统第一屏落哪儿', () => {
expect(landingPath()).toBe('/home')
})
it('只授权了「流程明细导出」的角色:桌面和手机都落那一页,不再被守卫弹回登录页', () => {
signIn(['monitor:export'])
expect(landingPath()).toBe('/export/detail')
phoneShell.value = true
expect(landingPath()).toBe('/export/detail')
// 这一条排在最后,不抢前面几档:一旦他有门户,第一屏还是门户
signIn(['monitor:export', 'portal:home'])
expect(landingPath()).toBe('/home')
})
it('免登与登录没带 redirect 时也按这个走(safeRedirect 的兜底就是它)', () => {
expect(safeRedirect('')).toBe('/home')
phoneShell.value = true

View File

@ -40,21 +40,26 @@ const PHONE_LANDING: readonly LandingStep[] = [
['work:workbench', '/workbench'],
['work:todo', '/todo'],
['work:profile', '/profile'],
['portal:home', '/home']
['portal:home', '/home'],
// 只授权了「流程明细导出」的那种角色:这一页是能给他看的第一屏,
// 再往下兜到 /home 只会被守卫弹回登录页,看着像密码错了。
['monitor:export', '/export/detail']
]
/** 桌面:门户第一,与改造之前一模一样。 */
const DESKTOP_LANDING: readonly LandingStep[] = [
['portal:home', '/home'],
['work:workbench', '/workbench'],
['work:todo', '/todo'],
['work:profile', '/profile']
['work:profile', '/profile'],
['monitor:export', '/export/detail']
]
/**
* 打开系统第一屏落哪儿:先按设备挑表,再按权限挑那一条真进得去的。
*
* 门户没丢:抽屉侧栏里 `/home` 那一条还在(`components/layout/AppLayout` 的抽屉),
* 只是手机不再拿它当第一屏。一张表都没命中(权限少到极点)也回 `/home`,
* 让路由守卫去把人送去登录页,这里不自己发明去处。
* 只是手机不再拿它当第一屏。「只授权了一个功能页」的角色(例如只有 `monitor:export`)
* 排在最后兜住,否则这种账号登录成功也会立刻被守卫弹回登录页。一张表都没命中
* (权限少到极点)才回 `/home`,让路由守卫去把人送去登录页,这里不自己发明去处。
*/
export function landingPath(): string {
const authStore = useAuthStore()

View File

@ -0,0 +1,104 @@
// @vitest-environment jsdom
/**
* 无感跳转的三条底线。
*
* 企微卡片点进来不该先撞见一屏登录页,但"自动把人送出去"这件事一旦失控就是
* OA 与门户之间来回打转,所以这一层要钉住三件事:
*
* * 只有「只允许免登」这一档才自动跳——混合档还得给账号密码那扇门留位置;
* * 来路存得下、取得回、只取一次,并且只认站内路径(Hub 一期不解析 redirect);
* * 同一个窗口里最多自动跳两次,第三次起交回给人自己点;成功落地之后预算清零。
*/
import { beforeEach, describe, expect, it, vi } from 'vitest'
import { createPinia, setActivePinia } from 'pinia'
import { useAppStore } from '@/stores/app'
import {
autoJumpToPortal,
canAutoJump,
portalAddress,
rememberReturnPath,
resetAutoJumpBudget,
takeReturnPath
} from '@/utils/ssoJump'
const { begin, leave } = vi.hoisted(() => ({ begin: vi.fn(), leave: vi.fn() }))
vi.mock('@/api/auth', () => ({ ssoBegin: begin, getPublicSettings: vi.fn() }))
vi.mock('@/utils/portal', () => ({ leaveToPortal: leave }))
function hub(ssoOnly: boolean, portal = 'https://hub.example.com') {
useAppStore().applyPublicSettings({
site_name: 'OA',
site_logo: '',
site_description: '',
hub: { sso_only: ssoOnly, portal_url: portal }
} as never)
}
beforeEach(() => {
sessionStorage.clear()
localStorage.clear()
begin.mockReset()
leave.mockReset()
setActivePinia(createPinia())
hub(true)
})
describe('免登自动跳转', () => {
it('只允许免登这一档才谈得上自动跳', () => {
expect(portalAddress()).toBe('https://hub.example.com')
expect(canAutoJump()).toBe(true)
hub(false)
expect(portalAddress()).toBe('')
expect(canAutoJump()).toBe(false)
})
it('门户地址留空时不自动跳:那扇门后面什么都没有', () => {
hub(true, '')
expect(canAutoJump()).toBe(false)
})
it('跳之前先写好 state,并把来路接住', async () => {
begin.mockResolvedValue({ portal_url: 'https://portal.example.com' })
await expect(autoJumpToPortal('/todo/task-9')).resolves.toBe(true)
expect(begin).toHaveBeenCalledTimes(1)
// 门户回显的地址优先:改门户域名不用等前端缓存跟着换
expect(leave).toHaveBeenCalledWith('https://portal.example.com')
expect(takeReturnPath()).toBe('/todo/task-9')
// 取一次即清,否则下一次进本站也会被拽去同一页
expect(takeReturnPath()).toBe('')
})
it('门户回显为空就退回本地那份,人不留在原地', async () => {
begin.mockResolvedValue({ portal_url: '' })
await expect(autoJumpToPortal('/work/job-1')).resolves.toBe(true)
expect(leave).toHaveBeenCalledWith('https://hub.example.com')
})
it('写 state 失败也照样让人出去:门户里点卡片仍然回得来', async () => {
begin.mockRejectedValue(new Error('offline'))
await expect(autoJumpToPortal('/todo')).resolves.toBe(true)
expect(leave).toHaveBeenCalledWith('https://hub.example.com')
})
it('门户连着把人退回来时停下来,不再来回打转', async () => {
begin.mockResolvedValue({ portal_url: 'https://hub.example.com' })
await autoJumpToPortal('/todo')
await autoJumpToPortal('/todo')
expect(leave).toHaveBeenCalledTimes(2)
expect(canAutoJump()).toBe(false)
await expect(autoJumpToPortal('/todo')).resolves.toBe(false)
expect(leave).toHaveBeenCalledTimes(2)
// 人自己点了一次按钮 / 成功落地之后,预算清零重来
resetAutoJumpBudget()
expect(canAutoJump()).toBe(true)
})
it('来路只认站内路径:外站写法与登录页本身都不存', () => {
for (const outside of ['//evil.example.com/x', 'https://evil.example.com/x', '\\\\evil', '', '/login', '/sso', undefined]) {
rememberReturnPath(outside)
expect(takeReturnPath()).toBe('')
}
rememberReturnPath('/work/job-7?tab=1')
expect(takeReturnPath()).toBe('/work/job-7?tab=1')
})
})

View File

@ -0,0 +1,117 @@
/**
* 免登自动跳转:没有本地会话时不摆登录页,直接把整页送去统一门户。
*
* 企微卡片点开的那一路,用户本来就该一步进门,不该先撞见一屏「前往统一门户」
* 再自己点一下。这里把那一屏省掉,代价是三件事必须一起做,少一件就变成"看着像死循环":
*
* 1. **接住来路**:Hub 一期不解析 `redirect` 之类的查询参数(对接指南 1.4),绕门户
* 一圈回来地址上就没有它了,所以跳出去之前先把想去的站内路径存进 sessionStorage,
* 落地时取回来;
* 2. **数着跳**:门户把地址原样退回来(票据没签成、Hub 那边也没登录态)时,无感跳转
* 就成了 OA 与 Hub 之间来回打转。同一段时间里最多自动跳两次,第三次起把这一屏
* 交回给人自己点,那两颗按钮还在,谁都不会被关在门外;
* 3. **只在这一档自动跳**:`sso` 档(只允许免登)本来就没有第二种登录方式,跳走不损失
* 什么;`hybrid` / `local` 还得给账号密码那扇门留着位置,不该抢在前面。
*/
import { ssoBegin } from '@/api/auth'
import { useAppStore } from '@/stores/app'
import type { HubPublicSettings } from '@/types'
import { leaveToPortal } from '@/utils/portal'
/** 跳去门户之前想去的站内路径;落地时取一次即清。 */
const RETURN_KEY = 'unisoa_sso_return'
/** 这段时间里自动跳过几次,格式 `次数,最后一次的毫秒时间戳`。 */
const JUMP_KEY = 'unisoa_sso_jumps'
/** 正常一趟「跳过去 → 门户登录 → 带票回来」用掉 1 次,留 1 次给被退回来的那一趟。 */
const MAX_AUTO_JUMPS = 2
/** 超出这个窗口的计数不算数:上一次失败留下的数字不该拦住这一次。 */
const JUMP_WINDOW_MS = 60_000
function bag(): Storage | null {
try {
return window.sessionStorage
} catch {
// 隐私模式与非浏览器环境下没有 sessionStorage,退化成"不接来路、不数次数"
return null
}
}
function isInternal(path: string): boolean {
// 协议相对写法(//evil.com)与 /\evil.com 都会被浏览器送去另一台主机
return /^\/(?!\/|\\)/.test(path)
}
/**
* 门户地址:只有「只允许免登」这一档才谈得上自动跳。
*
* 应急后门(`/login?local=1`)不算在这里 —— 调用方自己已经因为 `?local=1` 换成了
* 账号密码表单,压根走不到这一条。
*/
export function portalAddress(): string {
const hub = (useAppStore().cachedPublicSettings?.hub as HubPublicSettings) || {}
if (hub.sso_only !== true) return ''
return String(hub.portal_url || '').trim()
}
/** 跳出去之前记下想去的站内路径(对接指南 1.4:Hub 不会替我们带回来)。 */
export function rememberReturnPath(path: unknown): void {
const store = bag()
if (!store) return
const value = typeof path === 'string' ? path.trim() : ''
// 登录页与落地页本身不是"想去的那一页",存进去只会让人绕回来绕回去
if (isInternal(value) && value !== '/login' && !value.startsWith('/sso')) {
store.setItem(RETURN_KEY, value)
}
}
/** 落地时取回来路,取一次即清:留着会让下一次进本站也跳到同一页去。 */
export function takeReturnPath(): string {
const store = bag()
if (!store) return ''
const value = store.getItem(RETURN_KEY) || ''
store.removeItem(RETURN_KEY)
return isInternal(value) ? value : ''
}
function jumps(): number {
const store = bag()
if (!store) return MAX_AUTO_JUMPS
const raw = store.getItem(JUMP_KEY)
if (!raw) return 0
const [countText, atText] = raw.split(',')
const at = Number(atText)
if (!Number.isFinite(at) || Date.now() - at > JUMP_WINDOW_MS) return 0
return Number(countText) || 0
}
/** 还能不能自动跳。不消耗预算,给界面先决定画哪一屏用。 */
export function canAutoJump(): boolean {
return !!portalAddress() && jumps() < MAX_AUTO_JUMPS
}
/** 成功落地之后清空预算,下一次没有会话时重新拿到两次机会。 */
export function resetAutoJumpBudget(): void {
bag()?.removeItem(JUMP_KEY)
}
/**
* 立刻整页跳去统一门户。跳走了回 `true`(调用方把这一屏切成「正在跳转」),
* 条件不满足回 `false`,调用方照旧画那两颗按钮,绝不静默什么都不做。
*
* 本函数不抛异常:写 `state` 只是防会话固定,失败也照样让人出去,
* 门户里点卡片仍然回得来。
*/
export async function autoJumpToPortal(path?: unknown): Promise<boolean> {
if (!canAutoJump()) return false
const target = portalAddress()
bag()?.setItem(JUMP_KEY, `${jumps() + 1},${Date.now()}`)
rememberReturnPath(path ?? `${window.location.pathname}${window.location.search}`)
let portal = target
try {
portal = String((await ssoBegin()).portal_url || '') || target
} catch {
// 拿不到 state 也要跳:这一趟的目的是让人出去,不是让人等在这儿
}
leaveToPortal(portal)
return true
}

View File

@ -0,0 +1,117 @@
// @vitest-environment jsdom
/**
* 登录页在「只允许免登」这一档该干什么:不等人看清按钮,直接把整页送去统一门户。
*
* 钉三件事:
*
* * 没有本地会话又没有票据:不等那几秒,挂载完就把人送出去,屏上换成一枚转圈的"正在前往";
* * 门户连着把人退回来(自动跳的预算用完):这一屏停住,那两颗按钮还在,别来回打转;
* * 应急后门 `/login?local=1`:仍然是账号密码表单,自动跳转不能把管理员抢在门外。
*/
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 { useAuthStore } from '@/stores'
import { autoJumpToPortal } from '@/utils/ssoJump'
import LoginView from './LoginView.vue'
const { leave, begin, captcha } = vi.hoisted(() => ({
leave: vi.fn(),
begin: vi.fn(async () => ({ portal_url: 'https://hub.example.com' })),
captcha: vi.fn(async () => ({ required: false, image: '', question: '' }))
}))
vi.mock('@/utils/portal', () => ({ leaveToPortal: leave }))
vi.mock('@/api/auth', async (importOriginal) => ({
...(await importOriginal<typeof import('@/api/auth')>()),
ssoBegin: begin,
captcha,
getPublicSettings: async () => ({
site_name: 'UnisOA',
site_logo: '',
site_description: '',
hub: { sso_only: true, portal_url: 'https://hub.example.com' }
})
}))
async function open(target: string) {
const pinia = createPinia()
setActivePinia(pinia)
useAuthStore()
const router = createRouter({
history: createMemoryHistory(),
routes: [
{ path: '/login', name: 'login', component: LoginView },
{ path: '/home', name: 'portal-home', component: { template: '<div />' } }
]
})
await router.push(target)
await router.isReady()
const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh } })
const wrapper = mount(LoginView, {
global: {
plugins: [router, i18n, pinia],
stubs: {
AuthLayout: { template: '<div><slot /></div>' },
Input: { template: '<div />' },
LocaleSwitcher: true
}
}
})
await flushPromises()
return { wrapper, pinia }
}
beforeAll(() => {
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()
leave.mockReset()
begin.mockClear()
captcha.mockClear()
})
describe('只允许免登时的登录页', () => {
it('挂载完就把人送去门户,不摆一屏等人点', async () => {
const { wrapper } = await open('/login')
expect(leave).toHaveBeenCalledWith('https://hub.example.com')
expect(begin).toHaveBeenCalledTimes(1)
expect(wrapper.text()).toContain(zh.auth.ssoJumping)
// 送出去的路上不该先闪一张账号密码表单
expect(wrapper.find('form').exists()).toBe(false)
// 连去门户的路上都不该顺手要一张验证码:那是 Hub 的东西,这一屏用不上
expect(captcha).not.toHaveBeenCalled()
})
it('想去哪一页写在 redirect 上,跳之前先接住', async () => {
await open('/login?redirect=%2Ftodo%2Ftask-9')
// 绕门户一圈回来地址上没有它(对接指南 1.4),靠 sessionStorage 这一份接上
expect(sessionStorage.getItem('unisoa_sso_return')).toBe('/todo/task-9')
})
it('门户连着把人退回来就停下:不再自动跳,按钮留给人在', async () => {
await open('/login') // 用掉第 1 次
await autoJumpToPortal('/todo') // 用掉第 2 次,预算见底
leave.mockReset()
const again = await open('/login')
expect(leave).not.toHaveBeenCalled()
expect(again.wrapper.text()).toContain(zh.auth.ssoEnter)
expect(again.wrapper.text()).not.toContain(zh.auth.ssoJumping)
})
it('应急后门 /login?local=1 仍然是账号密码那扇门', async () => {
const { wrapper } = await open('/login?local=1')
expect(leave).not.toHaveBeenCalled()
expect(captcha).toHaveBeenCalledTimes(1)
expect(wrapper.find('form').exists()).toBe(true)
})
})

View File

@ -11,15 +11,22 @@
<p class="mt-2 text-sm text-gray-500 dark:text-dark-400">{{ t('auth.loginSubtitle') }}</p>
</div>
<!-- 只允许统一门户免登:本系统不再收账号密码,这一屏只把人送回统一门户 -->
<div v-if="ssoOnly" class="card p-6 text-center sm:p-8">
<Icon name="shield" class="mx-auto h-8 w-8 text-primary-600" />
<p class="mt-4 text-sm leading-6 text-gray-600 dark:text-dark-200">{{ t('auth.ssoEntryHint') }}</p>
<button type="button" class="btn btn-primary mt-6 w-full" @click="toPortal">
<Icon name="externalLink" class="mr-1 h-4 w-4" />
{{ t('auth.ssoEnter') }}
</button>
<p v-if="portalUrl" class="mt-4 text-xs text-gray-400">{{ t('auth.ssoAutoJump') }}</p>
<!-- 只允许统一门户免登:本系统不再收账号密码,这一屏要么正在跳,要么留两颗按钮 -->
<div v-if="deciding || ssoOnly" class="card p-6 text-center sm:p-8">
<template v-if="deciding || jumping">
<Icon name="refresh" class="mx-auto h-8 w-8 animate-spin text-primary-600" />
<p v-if="jumping" class="mt-4 text-sm leading-6 text-gray-600 dark:text-dark-200">{{ t('auth.ssoJumping') }}</p>
<p v-else class="mt-4 text-sm leading-6 text-gray-600 dark:text-dark-200">{{ t('auth.ssoSubtitle') }}</p>
</template>
<template v-else>
<Icon name="shield" class="mx-auto h-8 w-8 text-primary-600" />
<p class="mt-4 text-sm leading-6 text-gray-600 dark:text-dark-200">{{ t('auth.ssoEntryHint') }}</p>
<button type="button" class="btn btn-primary mt-6 w-full" @click="toPortal">
<Icon name="externalLink" class="mr-1 h-4 w-4" />
{{ t('auth.ssoEnter') }}
</button>
<p v-if="portalUrl" class="mt-4 text-xs text-gray-400">{{ t('auth.ssoAutoJump') }}</p>
</template>
</div>
<form v-else class="card p-6 sm:p-8" @submit.prevent="submit">
@ -108,7 +115,7 @@
</template>
<script setup lang="ts">
import { computed, onBeforeUnmount, onMounted, ref } from 'vue'
import { computed, onMounted, ref } from 'vue'
import { useRoute, useRouter } from 'vue-router'
import { useI18n } from 'vue-i18n'
import AuthLayout from '@/components/layout/AuthLayout.vue'
@ -116,6 +123,7 @@ import Input from '@/components/common/Input.vue'
import Icon from '@/components/icons/Icon.vue'
import LocaleSwitcher from '@/components/common/LocaleSwitcher.vue'
import { captcha as fetchCaptcha, ssoBegin, type LoginCaptcha } from '@/api/auth'
import { autoJumpToPortal, canAutoJump, resetAutoJumpBudget } from '@/utils/ssoJump'
import { leaveToPortal } from '@/utils/portal'
import type { HubPublicSettings } from '@/types'
import { useAuthStore } from '@/stores/auth'
@ -138,7 +146,11 @@ const touched = ref(false)
const captcha = ref<LoginCaptcha | null>(null)
const captchaAnswer = ref('')
// 统一身份口径:只允许免登时这一屏不换表单,直接把用户送回统一门户
const hub = ref<HubPublicSettings>({})
// 公开配置有可能是后端注进 index.html 的那一份(`__APP_CONFIG__`),先同步接过来:
// 接住了就没有"先闪一张账号密码表单、再整页跳走"那一下
const hub = ref<HubPublicSettings>((appStore.cachedPublicSettings?.hub as HubPublicSettings) || {})
// 公开配置还没回来之前谁都别画:这一档到底是免登还是本地口令,得先问出来
const deciding = ref(!appStore.publicSettingsLoaded)
// 本地应急账号那扇门默认不画在界面上(对接文档第 10 节),只认地址上的 ?local=1:
// Hub 配错时管理员手敲 /login?local=1 就还能用本地口令进门,别把人锁在自己系统外面
const forceLocal = ref(route.query.local === '1')
@ -147,9 +159,8 @@ const portalUrl = computed(() => String(hub.value.portal_url || ''))
// 连门户地址都没有(Hub 站点地址留空)时就别再摆一个点了没反应的按钮:
// 留着账号密码表单,后端会给出「只允许从统一门户免登进入」这句能看懂的拒绝
const ssoOnly = computed(() => emergencyOnly.value && !forceLocal.value && !!portalUrl.value)
let jumpTimer: number | undefined
// 无会话时自动回统一门户前的等待:够看清按钮,也够手动改成 ?local=1
const AUTO_PORTAL_JUMP_MS = 4000
// 已经把人送出去了:这一屏换成"正在跳转",别再闪一张没人填的表单
const jumping = ref(false)
const accountError = computed(() => (touched.value && !account.value.trim() ? t('auth.accountRequired') : ''))
const passwordError = computed(() => (touched.value && !password.value ? t('auth.passwordRequired') : ''))
@ -196,7 +207,8 @@ async function submit() {
}
async function toPortal() {
window.clearTimeout(jumpTimer)
// 人自己点的这一次不算进自动跳转的预算,点完重新拿到两次机会
resetAutoJumpBudget()
// 先让后端写一条 state(防会话固定),再整页跳到统一门户;在门户点卡片就带票据回来。
try {
const begin = await ssoBegin()
@ -209,10 +221,15 @@ async function toPortal() {
onMounted(async () => {
const settings = await appStore.fetchPublicSettings()
hub.value = (settings?.hub as HubPublicSettings) || {}
deciding.value = false
if (ssoOnly.value && portalUrl.value) {
// 只允许免登又没有本地会话:把人送回统一门户。留够时间看清这两个按钮,
// 应急本地账号那条路不能被一次自动跳转抢掉
jumpTimer = window.setTimeout(() => void toPortal(), AUTO_PORTAL_JUMP_MS)
// 无感跳转:不摆一屏等人看清的按钮,直接把整页送去门户,来路那一页交给 ssoJump 接住。
// 只有门户连着把人退回来(自动跳的预算用完)才留下这两颗按钮让人自己决定;
// 应急本地账号那扇门走 /login?local=1,那一档 ssoOnly 本身就是假,抢不到。
if (canAutoJump()) {
jumping.value = true
void autoJumpToPortal(route.query.redirect)
}
return
}
// 本地模式后端直接回 required=false,不会多出输入框
@ -224,6 +241,4 @@ onMounted(async () => {
captcha.value = null
})
})
onBeforeUnmount(() => window.clearTimeout(jumpTimer))
</script>

View File

@ -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<typeof stub>) {
const router = createRouter({
history: createMemoryHistory(),
routes: [
{ path: '/sso', name: 'sso-callback', component: SsoCallbackView },
{ path: '/todo/:id', name: 'todo-detail', component: { template: '<div />' } },
{ path: '/todo', name: 'my-todo', component: { template: '<div />' } },
{ path: '/work/:job', name: 'work-detail', component: { template: '<div />' } },
{ path: '/workbench', name: 'workbench', component: { template: '<div />' } },
{ path: '/profile', name: 'profile', component: { template: '<div />' } },
{ path: '/home', name: 'portal-home', component: { template: '<div />' } },
{ path: '/login', name: 'login', component: { template: '<div />' } }
]
})
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: '<div><slot /></div>' }, 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)
})
})

View File

@ -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) {
// 失败一律不再试第二次:票据与短码都是一次性的,重试只会得到同样的拒绝。

View File

@ -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<string, unknown> = {}) {
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<string, unknown> {
const calls = api.listDeliveries.mock.calls
return (calls[calls.length - 1]?.[0] ?? {}) as Record<string, unknown>
}
async function openDeliveryTab() {
api.notifyMeta.mockResolvedValue(META)
api.listChannels.mockResolvedValue({ items: [], enabled: true, masterSwitch: true, hubCoverage: null })
api.listDeliveries.mockImplementation(async (query: Record<string, unknown> = {}) => 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 })
})
})

View File

@ -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<string, unknown> = {}) {
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<string, unknown>[] = [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<typeof mount>) {
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')
})
})

View File

@ -53,6 +53,9 @@
</template>
<template #cell-target="{ row }">
<span class="block max-w-[280px] truncate font-mono text-[11px] text-gray-500">{{ targetOf(row) }}</span>
<span v-if="row.receiverLabel" class="block max-w-[280px] truncate text-[11px] text-gray-400">
{{ t('notify.hubReceiverVia', { fields: row.receiverLabel }) }}
</span>
</template>
<template #cell-today="{ row }">
<span class="text-xs">
@ -121,19 +124,23 @@
</button>
</div>
<div class="flex flex-wrap items-center gap-2">
<Select v-model="query.channel" :options="channelOptions" compact class="w-44" @update:model-value="() => loadDeliveries()" />
<Select v-model="query.type" :options="typeOptions" compact class="w-40" @update:model-value="() => loadDeliveries()" />
<SearchInput v-model="query.keyword" class="w-48" @search="() => loadDeliveries()" />
<Select v-model="query.channel" :options="channelOptions" compact class="w-44" @update:model-value="() => reloadDeliveries()" />
<Select v-model="query.type" :options="typeOptions" compact class="w-40" @update:model-value="() => reloadDeliveries()" />
<SearchInput v-model="query.keyword" class="w-48" @search="() => reloadDeliveries()" />
</div>
</div>
<DataTable :columns="deliveryColumns" :data="deliveries" :loading="loadingDeliveries" row-key="id" :actions-count="2">
<DataTable :columns="deliveryColumns" :data="deliveries" :loading="loadingDeliveries" row-key="id" :actions-count="3">
<template #cell-status="{ row }">
<span :class="statusClass(row.status)">{{ statusLabel(row.status) }}</span>
<span v-if="row.attempts" class="ml-1 text-[11px] text-gray-400">×{{ row.attempts }}</span>
</template>
<template #cell-who="{ row }">
<span class="block truncate text-sm">{{ row.personName || row.person || '—' }}</span>
<span class="block max-w-[260px] truncate font-mono text-[11px] text-gray-400">{{ row.target }}</span>
<!-- 走 Hub 的那一路要说清这串是 Hub 主键还是登录账号:前者跟着同步走,
后者会被企微字段改写,排查方向完全不同 -->
<span class="block max-w-[260px] truncate font-mono text-[11px] text-gray-400">
{{ row.targetFieldLabel && row.target ? `${row.targetFieldLabel}:${row.target}` : row.target }}
</span>
</template>
<template #cell-title="{ row }">
<span class="block max-w-[320px] truncate text-sm">{{ row.title }}</span>
@ -144,6 +151,12 @@
<span v-else-if="row.status === 'failed' && row.nextAttemptAt" class="text-[11px] text-gray-400">
{{ t('notify.willRetryAt') }} {{ row.nextAttemptAt }}
</span>
<span v-else-if="hubDegraded(row)" class="block max-w-[260px] truncate text-[11px] text-amber-600"
:title="hubDegraded(row)">{{ hubDegraded(row) }}</span>
<a v-else-if="hubLink(row)" :href="hubLink(row)" target="_blank" rel="noopener"
class="block max-w-[260px] truncate text-[11px] text-primary-600" :title="t('notify.hubLinkOpen')">
{{ hubLink(row) }}
</a>
<span v-else class="text-[11px] text-gray-400">—</span>
</template>
<template #cell-actions="{ row }">
@ -154,12 +167,25 @@
<button v-if="row.status !== 'success'" type="button" class="btn btn-ghost btn-sm" @click="sendNow(row)">
<Icon name="bolt" class="mr-1 h-4 w-4" />{{ t('notify.sendNow') }}
</button>
<button v-if="row.kind === 'hub_wecom'" type="button" class="btn btn-ghost btn-sm" :title="t('notify.recheckHint')" @click="recheck(row)">
<Icon name="search" class="mr-1 h-4 w-4" />{{ t('notify.recheck') }}
</button>
</div>
</template>
<template #empty>
<EmptyState icon="mail" :title="t('notify.noDelivery')" />
</template>
</DataTable>
<!-- 一次筛选动辄几百条,翻不到第 12 页等于没记录;跳页直接输页码最省事 -->
<Pagination
v-if="pagination.total > 0"
:total="pagination.total"
:page="pagination.page"
:page-size="pagination.page_size"
show-jump
@update:page="handlePageChange"
@update:page-size="handlePageSizeChange"
/>
</div>
<!-- 新增 / 编辑渠道 -->
@ -227,6 +253,78 @@
<p class="input-hint">{{ t('notify.secretHint') }}</p>
</template>
<!-- 统一身份 Hub 代发企业微信:没有地址也没有密钥要填,站点和密钥都跟着
「系统设置 → 统一身份」走(与免登、组织人员同步共用同一把),这里只选形态 -->
<template v-else-if="isHub">
<div class="rounded-lg border border-gray-100 px-3 py-2.5 dark:border-dark-700">
<div class="flex items-start gap-2">
<Icon
:name="meta.hub?.ready ? 'checkCircle' : 'exclamationTriangle'"
class="mt-0.5 h-4 w-4 flex-shrink-0"
:class="meta.hub?.ready ? 'text-green-600' : 'text-amber-600'"
/>
<p class="text-sm">
<span v-if="meta.hub?.ready">{{ t('notify.hubReady', { base: meta.hub.baseUrl, app: meta.hub.appCode || '—' }) }}</span>
<span v-else class="text-amber-700 dark:text-amber-200">{{ t('notify.hubMissing', { items: (meta.hub?.missing || []).join('、') }) }}</span>
</p>
</div>
<p class="mt-1.5 text-xs text-gray-500">{{ t('notify.hubPrereq') }}</p>
</div>
<!-- 收件人标识:Hub 只认那几种,顺序就是认人的优先级。这一档决定"发出去的是
谁的哪个号",选错的代价是有人静默收不到,所以把覆盖人数一起摆在这儿 -->
<div>
<span class="input-label">{{ t('notify.hubReceiver') }}</span>
<div class="flex flex-wrap gap-1.5">
<button
v-for="preset in receiverPresets"
:key="preset.value.join('>')"
type="button"
class="badge"
:class="[isReceiverPicked(form.config.receiver, preset.value) ? 'badge-primary' : 'badge-gray']"
:title="preset.hint"
@click="form.config.receiver = [...preset.value]"
>
{{ preset.label }}
<span v-if="receiverCovers(preset.value) !== null" class="ml-1 opacity-70">
{{ receiverCovers(preset.value) }}
</span>
</button>
</div>
<p class="input-hint">{{ t('notify.hubReceiverHint') }}</p>
<p v-if="coverage && selectedReceiverCovers !== null" class="input-hint">
{{ t('notify.hubReceiverCoverage', {
active: coverage.active,
covers: selectedReceiverCovers,
none: coverage.none
}) }}
</p>
</div>
<div>
<span class="input-label">{{ t('notify.hubMsgtype') }}</span>
<div class="flex flex-wrap gap-1.5">
<button
v-for="item in meta.hubMsgtypes"
:key="item.value"
type="button"
class="badge"
:class="[String(form.config.msgtype || 'textcard') === item.value ? 'badge-primary' : 'badge-gray']"
@click="form.config.msgtype = item.value"
>
{{ item.label }}
</button>
</div>
</div>
<div class="space-y-1.5">
<label class="flex items-center gap-2 text-sm">
<Toggle v-model="form.config.with_link" />
{{ t('notify.hubWithLink') }}
</label>
<p class="input-hint">{{ t('notify.hubLinkHint') }}</p>
</div>
<Input v-model="form.config.title_limit" type="number" :label="t('notify.hubTitleLimit')" />
<p class="input-hint">{{ t('notify.hubTitleLimitHint') }}</p>
</template>
<template v-else>
<Input v-model="form.config.url" :label="t('notify.pushUrl')" required placeholder="https://robot.example.com/hook?access_token=..." />
<p class="input-hint">{{ t('notify.pushUrlHint') }}</p>
@ -308,13 +406,22 @@ import DataTable from '@/components/common/DataTable.vue'
import EmptyState from '@/components/common/EmptyState.vue'
import Icon from '@/components/icons/Icon.vue'
import Input from '@/components/common/Input.vue'
import Pagination from '@/components/common/Pagination.vue'
import SearchInput from '@/components/common/SearchInput.vue'
import Select from '@/components/common/Select.vue'
import TextArea from '@/components/common/TextArea.vue'
import Toggle from '@/components/common/Toggle.vue'
import type { Column } from '@/components/common/types'
import { notifyAPI } from '@/api'
import type { NotifyChannel, NotifyDelivery, NotifyMeta } from '@/types'
import type { DeliveryQuery } from '@/api/notify'
import type {
NotifyChannel,
NotifyDelivery,
NotifyHubDetail,
NotifyMeta,
NotifyReceiverCoverage
} from '@/types'
import { useOAList } from '@/composables/useOAList'
import { runAction } from '@/utils/oa'
const { t } = useI18n()
@ -323,10 +430,18 @@ type TabKey = 'channels' | 'deliveries'
/** 界面上的状态筛选:'' = 全部 */
type StatusKey = '' | 'pending' | 'failed' | 'dead' | 'skipped' | 'success'
const meta = reactive<NotifyMeta>({ kinds: [], events: [], textVars: [], smtpPresets: [] })
/**
* 投递记录的筛选条件。四个格子都得是实打实的字符串——它们直接挂在 v-model 上,
* 写成可选就把 ``string | undefined`` 喂进了下拉框和搜索框。
*/
type DeliveryFilter = { channel: string; status: StatusKey; type: string; keyword: string }
const meta = reactive<NotifyMeta>({ kinds: [], events: [], textVars: [], smtpPresets: [], hubMsgtypes: [] })
const rows = ref<NotifyChannel[]>([])
const loading = ref(false)
const masterSwitch = ref(true)
/** 收件人标识的覆盖情况:只有库里配了 Hub 渠道时后端才给,换标识之前先看这一眼 */
const coverage = ref<NotifyReceiverCoverage | null>(null)
const tabKey = ref<TabKey>('channels')
const testingCode = ref('')
@ -357,10 +472,35 @@ const form = reactive<{
remark: ''
})
const deliveries = ref<NotifyDelivery[]>([])
const loadingDeliveries = ref(false)
/** 后端 counts 里各状态在当前筛选下各有多少条,'' 那一项是「全部」 */
const counts = ref<Record<string, number>>({})
const query = reactive({ channel: '', status: '' as StatusKey, type: '', keyword: '' })
/** 翻过一次没有:切回这一页时不必再拉一遍,哪怕这一页正好是空的 */
let deliveriesLoaded = false
/**
* 投递记录走服务端分页,和待办、操作日志同一套加载器:翻页、换每页条数、
* 请求取消、每页条数记在本地,都不在这儿重写一遍。counts 挂在响应的另一半上,
* 所以在 fetcher 里顺手取走。
*/
const {
items: deliveries,
loading: loadingDeliveries,
params: query,
pagination,
load: loadDeliveries,
reload: reloadDeliveries,
handlePageChange,
handlePageSizeChange
} = useOAList<NotifyDelivery, DeliveryFilter>(
async (page, page_size, params, options) => {
const sent: DeliveryQuery = { ...params, page, page_size }
const got = await notifyAPI.listDeliveries(sent, options)
counts.value = got?.counts ?? {}
deliveriesLoaded = true
return got
},
{ channel: '', status: '', type: '', keyword: '' }
)
const tabs: Array<{ key: TabKey; labelKey: string }> = [
{ key: 'channels', labelKey: 'notify.tabChannels' },
@ -368,6 +508,7 @@ const tabs: Array<{ key: TabKey; labelKey: string }> = [
]
const isEmail = computed(() => form.kind === 'email')
const isHub = computed(() => form.kind === 'hub_wecom')
const securityOptions = computed(() => [
{ value: 'ssl', label: t('notify.securitySsl') },
{ value: 'starttls', label: t('notify.securityStarttls') },
@ -420,9 +561,69 @@ function eventLabels(events: string[]): string[] {
function targetOf(row: NotifyChannel): string {
const config = row.config || {}
if (row.kind === 'email') return String(config.mail_from || config.username || '—')
if (row.kind === 'hub_wecom') {
// 这一路没有地址可看:发到哪由统一身份配置决定,渠道上只有"发成什么形态"
return `${t('notify.hubWhere')} · ${msgtypeLabel(String(config.msgtype || 'textcard'))}`
}
return String(config.url || '—')
}
function msgtypeLabel(value: string): string {
return meta.hubMsgtypes.find((item) => item.value === value)?.label || value
}
/**
* 界面上的收件人标识选项:后端给"哪几种标识 + 常用的几种顺序",这里只管显示与选中比对。
* 顺序就是认人的优先级(``Hub 用户 ID → 登录账号``),口径见
* ``backend/app/service/channels.py`` 的 ``HUB_RECEIVER_FIELDS``。
*/
const receiverPresets = computed(() => meta.hubReceiverPresets ?? [])
/** 表单里那一格可能是数组、逗号串或没配过,统一洗成一份顺序;没配就是后端给的默认。 */
function receiverPrefOf(value: unknown): string[] {
const list = Array.isArray(value) ? value : String(value ?? '').split(',')
const out: string[] = []
list.forEach((item) => {
const key = String(item ?? '').trim().toLowerCase()
if (key && !out.includes(key)) out.push(key)
})
if (out.length) return out
return meta.hubReceiverDefault?.length ? [...meta.hubReceiverDefault] : ['user_id', 'account']
}
function isReceiverPicked(value: unknown, preset: string[]): boolean {
const picked = receiverPrefOf(value)
return picked.length === preset.length && picked.every((item, index) => item === preset[index])
}
/**
* 这一档能发到多少人:只勾一种就看那一列,几种都试则是"至少有一种标识"的人数。
* 后端没给覆盖数(库里压根没有 Hub 渠道)时返回 null,界面上这一句就不出现。
*/
function receiverCovers(pref: string[]): number | null {
const cov = coverage.value
if (!cov) return null
return pref.length === 1 ? cov.fields[pref[0]] ?? 0 : cov.any
}
const selectedReceiverPref = computed(() => receiverPrefOf(form.config.receiver))
const selectedReceiverCovers = computed(() => receiverCovers(selectedReceiverPref.value))
/** 这条投递在 Hub 那边留下的深链:永久有效、可反复点开,运维拿来手验最方便。 */
function hubLink(row: NotifyDelivery): string {
const hub = (row.response?.hub || {}) as NotifyHubDetail
return String(hub.link || '')
}
/** 发出去了但没带链接:说清是哪一种,别让"成功却没有链接"看起来像坏了。 */
function hubDegraded(row: NotifyDelivery): string {
const hub = (row.response?.hub || {}) as NotifyHubDetail
const key = String(hub.degraded || '')
if (key === 'hub_no_home') return t('notify.hubDegradedNoHome')
if (key === 'no_link') return t('notify.hubDegradedNoLink')
return ''
}
function statusLabel(status: string): string {
const key = `notify.st${status.charAt(0).toUpperCase()}${status.slice(1)}`
const text = t(key)
@ -460,6 +661,12 @@ function resetForm(row?: NotifyChannel) {
form.config = { ...(row?.config ?? {}), password: '', secret: '' }
if (form.config.port === undefined) form.config.port = 465
if (form.config.security === undefined) form.config.security = 'ssl'
// Hub 那一档的三个值:新建就给默认值,别让开关是个 undefined
if (form.config.msgtype === undefined) form.config.msgtype = 'textcard'
if (form.config.with_link === undefined) form.config.with_link = true
if (form.config.title_limit === undefined) form.config.title_limit = 64
// 收件人标识永远是个数组:老渠道没配过这一项,落到后端给的默认顺序上
form.config.receiver = receiverPrefOf(form.config.receiver)
form.textTemplate = row?.textTemplate ?? ''
form.timeoutSeconds = row?.timeoutSeconds ?? 10
form.retries = row?.retries ?? 3
@ -489,7 +696,14 @@ function payload(): Partial<NotifyChannel> {
mail_from: String(raw.mail_from || '').trim(),
username: String(raw.username || '').trim()
}
: { url: String(raw.url || '').trim() }
: isHub.value
? {
msgtype: String(raw.msgtype || 'textcard'),
with_link: raw.with_link !== false,
title_limit: Number(raw.title_limit) || 64,
receiver: receiverPrefOf(raw.receiver)
}
: { url: String(raw.url || '').trim() }
// 留空 = 不提交这一项:后端会把库里那把密钥原样留着
if (String(raw.password || '').trim()) config.password = String(raw.password).trim()
if (String(raw.secret || '').trim()) config.secret = String(raw.secret).trim()
@ -526,7 +740,9 @@ async function remove(row: NotifyChannel) {
async function test(row: NotifyChannel, keepOpen = false) {
if (!row.code) return
testingCode.value = row.code
const got = await runAction(() => notifyAPI.testChannel(row.code), { success: t('notify.testSent') })
// Hub 那一路是"已交给 Hub",最后到人手机还有企微那一跳,话别说满
const done = row.kind === 'hub_wecom' ? t('notify.testSentHub') : t('notify.testSent')
const got = await runAction(() => notifyAPI.testChannel(row.code), { success: done })
testingCode.value = ''
if (got !== null && keepOpen) await load()
if (got === null && keepOpen) return
@ -537,25 +753,19 @@ async function load() {
const got = await runAction(() => notifyAPI.listChannels())
rows.value = got?.items ?? []
masterSwitch.value = got?.masterSwitch !== false
coverage.value = got?.hubCoverage ?? null
loading.value = false
}
async function loadDeliveries() {
loadingDeliveries.value = true
const got = await runAction(() => notifyAPI.listDeliveries({ ...query }))
deliveries.value = got?.items ?? []
counts.value = got?.counts ?? {}
loadingDeliveries.value = false
}
function setQuery(status: StatusKey) {
query.status = status
void loadDeliveries()
// 换状态等于换一次筛选:还停在第 9 页的话,筛完很可能是一页空白
void reloadDeliveries()
}
function switchTab(tab: TabKey) {
tabKey.value = tab
if (tab === 'deliveries' && !deliveries.value.length) void loadDeliveries()
if (tab === 'deliveries' && !deliveriesLoaded) void loadDeliveries()
}
async function resend(row: NotifyDelivery) {
@ -563,6 +773,11 @@ async function resend(row: NotifyDelivery) {
if (done !== null) await loadDeliveries()
}
async function recheck(row: NotifyDelivery) {
const done = await runAction(() => notifyAPI.recheckDelivery(row.id), { success: t('notify.rechecked') })
if (done !== null) await loadDeliveries()
}
async function sendNow(row: NotifyDelivery) {
const done = await runAction(() => notifyAPI.sendDeliveryNow(row.id), { success: t('notify.testSent') })
if (done !== null) await loadDeliveries()

File diff suppressed because it is too large Load Diff

View File

@ -293,6 +293,7 @@ const PHONE_GROUPS: Array<{ title: string; items: PhoneEntry[] }> = [
title: 'nav.adminSection',
items: [
{ path: '/monitor', label: 'monitor.title', permission: 'monitor:work', icon: 'eye' },
{ path: '/export/detail', label: 'detailExport.title', permission: 'monitor:export', icon: 'download' },
{ path: '/statistics', label: 'nav.statistics', permission: 'statistics:view', icon: 'chartBar' },
{ path: '/settings', label: 'nav.systemSettings', permission: 'system:setting', icon: 'cog' }
]

View File

@ -0,0 +1,288 @@
// @vitest-environment jsdom
/**
* 「同步落库口径」这一组开关在界面上看得见、改得动、存得下去。
*
* 这几项决定一趟全量会不会停人、会不会改登录名、会不会把本地部门认领给 Hub。
* 以前只能拿 `PUT /hub/config` 改:清过库或换过站点的人看不见自己站在哪一档,
* 下一趟同步就把人停掉了。所以这里钉四条:摆在页面上、说明取后端那一份、
* 改动只提交真正改过的那几项、没有「系统设置」权限的人按不动。
*/
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 SyncScheduleView from './SyncScheduleView.vue'
const api = vi.hoisted(() => ({
getSchedule: vi.fn(),
syncRuns: vi.fn(),
syncNow: vi.fn(),
syncChanges: vi.fn(),
cancelSync: vi.fn(),
getConfigGroup: vi.fn(),
saveConfig: vi.fn()
}))
const stores = vi.hoisted(() => ({
success: vi.fn(),
error: vi.fn(),
can: vi.fn(() => true)
}))
vi.mock('@/api', () => ({ hubAPI: api, configAPI: api }))
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 item(name: string, kind: string, value: unknown, label: string, group = 'hub_sync') {
return {
name,
group,
label,
help: `${label}的说明`,
kind,
secret: false,
env: '',
restart_required: false,
value,
secret_set: false,
source: 'default',
source_label: '默认值',
stored_in_db: false,
file_value: null,
default_value: value,
env_locked: ''
}
}
function itemsFixture() {
return [
item('hub_sync_enabled', 'bool', true, '允许定时同步'),
item('hub_sync_when', 'enum', 'daily', '同步频率'),
item('hub_sync_time', 'time', '00:15', '同步时间'),
item('hub_sync_interval_minutes', 'int', 1440, '按间隔:隔多少分钟跑'),
item('hub_sync_retry_minutes', 'int', 10, '失败重试间隔'),
item('hub_sync_retries', 'int', 3, '失败重试次数'),
item('hub_sync_changes_enabled', 'bool', true, '增量同步(变更流水)'),
item('hub_sync_changes_interval_seconds', 'int', 45, '增量轮询周期(秒)'),
item('hub_sync_changes_limit', 'int', 200, '增量单批条数'),
item('hub_sync_changes_full_on_gap', 'bool', true, '落后过多就改拉全量'),
item('hub_sync_orgs', 'bool', true, '同步部门'),
item('hub_sync_include_disabled_units', 'bool', true, '带上已停用的组织', 'hub'),
item('hub_sync_bind_local_by_code', 'bool', true, '按编码认领本地部门'),
item('hub_sync_offboard', 'bool', true, '离职停用'),
item('hub_sync_offboard_guard_percent', 'int', 40, '离职停用熔断(%)'),
item('hub_sync_offboard_guard_min_people', 'int', 20, '离职停用熔断的人数底线'),
item('hub_sync_unit_offboard_guard_min', 'int', 5, '部门停用熔断的个数底线'),
item('hub_sync_reclaim_lost_accounts', 'bool', true, '让已查无此人的账号腾出登录名'),
item('hub_sync_roster_floor_percent', 'int', 50, '让位名单的清单人数下限(%)'),
item('hub_sync_skip_unchanged', 'bool', true, '版本没变就跳过'),
item('hub_sync_protect_admins', 'bool', true, '保护本地自建的管理员'),
item('hub_sync_member_limit', 'int', 5000, '单次导出人员上限'),
item('hub_sync_email_domain', 'str', '', '建号补全域名'),
item('hub_sync_locked_accounts', 'str', 'admin', '统一身份的管理员账号(OA 里只读)')
]
}
function scheduleFixture() {
const job = (key: string, name: string) => ({
key,
name,
description: `${name}的说明`,
enabled: true,
mode: 'daily',
mode_label: '每天',
summary: '每天 00:15',
time: '00:15',
weekdays: [1, 2, 3, 4, 5],
monthdays: [1],
interval_minutes: 1440,
retry_minutes: 10,
retries: 3,
grace_hours: 12,
sync_orgs: true,
sync_offboard: true,
skip_unchanged: true,
member_limit: 5000,
next_runs: ['2026-11-06 00:15:00'],
next_at: '2026-11-06 00:15:00',
occurrence: '2026-11-05 00:15:00',
due: false,
blocked_reason: '',
reason: '',
runs_for_occurrence: 0,
runs_last_30_days: 0,
last_run: null,
config_items: []
})
return {
now: '2026-11-05 10:48:18',
grace_hours: 12,
sync_allowed: true,
blocked: false,
blocked_reason: '',
forced_off: false,
base_url: 'https://hub.example',
credential_label: '目录密钥(X-Directory-Key)',
running: false,
modes: [{ value: 'daily', label: '每天' }],
weekdays: [{ value: 1, label: '周一' }],
jobs: [job('full', '全量同步(组织 + 人员)'), job('changes', '增量同步(变更流水)')]
}
}
function mountView() {
const i18n = createI18n({ legacy: false, locale: 'zh', messages: { zh } })
return mount(SyncScheduleView, {
global: { plugins: [i18n], stubs: { RouterLink: true, SyncJobPanel: true } }
})
}
/** 找到某一行的那颗开关:行内文案在前,Toggle 在后面,整行一起取文本再认。 */
function rowOf(wrapper: ReturnType<typeof mountView>, label: string) {
return wrapper.findAll('div.flex.items-start.justify-between').find((row) => row.text().includes(label))
}
beforeEach(() => {
Object.values(api).forEach((fn) => fn.mockReset())
api.getSchedule.mockResolvedValue(scheduleFixture())
api.syncRuns.mockResolvedValue([])
// 后端是按组给项的:hub_sync 与 hub 两组各返回自己那几项,页面自己合起来
api.getConfigGroup.mockImplementation((group: string) =>
Promise.resolve({
key: group,
label: '',
description: '',
items: itemsFixture().filter((entry) => entry.group === group)
})
)
api.saveConfig.mockImplementation((group: string) =>
Promise.resolve({ key: group, label: '', description: '', items: [] })
)
stores.success.mockReset()
stores.error.mockReset()
stores.can.mockReset()
stores.can.mockReturnValue(true)
})
describe('同步落库口径', () => {
it('落库口径这一段摆在页面上,标签与说明都用后端给的那一份', async () => {
const wrapper = mountView()
await flushPromises()
const text = wrapper.text()
expect(text).toContain('同步落库口径')
for (const label of [
'同步部门',
'带上已停用的组织',
'按编码认领本地部门',
'离职停用',
'让已查无此人的账号腾出登录名',
'版本没变就跳过',
'保护本地自建的管理员'
]) {
expect(text).toContain(label)
expect(text).toContain(`${label}的说明`)
}
expect(text).toContain('离职停用熔断(%)')
expect(text).toContain('单次导出人员上限')
})
it('只提交真改过的项,值按后端要的口径归一', async () => {
const wrapper = mountView()
await flushPromises()
await rowOf(wrapper, '离职停用')!.find('button').trigger('click')
expect(wrapper.text()).toContain('1 项改动未保存')
api.saveConfig.mockClear()
const save = wrapper.findAll('button').find((button) => button.text().includes('保存并生效'))
await save!.trigger('click')
await flushPromises()
expect(api.saveConfig).toHaveBeenCalledTimes(1)
const [group, values] = api.saveConfig.mock.calls[0]
expect(group).toBe('hub_sync')
expect(values).toEqual({ hub_sync_offboard: false })
})
it('熔断百分比填进去的是数字,不是字符串', async () => {
const wrapper = mountView()
await flushPromises()
const guard = wrapper.findAll('input[type="number"]').find((input) => (input.element as HTMLInputElement).value === '40')
await guard!.setValue('60')
api.saveConfig.mockClear()
const save = wrapper.findAll('button').find((button) => button.text().includes('保存并生效'))
await save!.trigger('click')
await flushPromises()
expect(api.saveConfig.mock.calls[0][1]).toEqual({ hub_sync_offboard_guard_percent: 60 })
})
it('三条熔断底线也在页面上:以前是代码里的常量,想调只能发版', async () => {
const wrapper = mountView()
await flushPromises()
const text = wrapper.text()
for (const label of ['离职停用熔断的人数底线', '部门停用熔断的个数底线', '让位名单的清单人数下限(%)']) {
expect(text).toContain(label)
expect(text).toContain(`${label}的说明`)
}
const floor = wrapper
.findAll('input[type="number"]')
.find((input) => (input.element as HTMLInputElement).value === '20')
await floor!.setValue('8')
api.saveConfig.mockClear()
const save = wrapper.findAll('button').find((button) => button.text().includes('保存并生效'))
await save!.trigger('click')
await flushPromises()
expect(api.saveConfig.mock.calls[0]).toEqual(['hub_sync', { hub_sync_offboard_guard_min_people: 8 }])
})
it('挂在 hub 组下的那一项存回 hub 组:后端按组校验,混在一批里会整批打回', async () => {
const wrapper = mountView()
await flushPromises()
await rowOf(wrapper, '带上已停用的组织')!.find('button').trigger('click')
await rowOf(wrapper, '离职停用')!.find('button').trigger('click')
api.saveConfig.mockClear()
const save = wrapper.findAll('button').find((button) => button.text().includes('保存并生效'))
await save!.trigger('click')
await flushPromises()
const calls = api.saveConfig.mock.calls
.map(([group, values]) => [group, JSON.stringify(values)])
.sort()
expect(calls).toEqual([
['hub', JSON.stringify({ hub_sync_include_disabled_units: false })],
['hub_sync', JSON.stringify({ hub_sync_offboard: false })]
])
})
it('hub 组读不到只少那一项开关,排期与其余落库口径照常摆出来', async () => {
api.getConfigGroup.mockImplementation((group: string) =>
group === 'hub' ? Promise.reject(new Error('没有「系统设置」权限')) : Promise.resolve({
key: group,
label: '',
description: '',
items: itemsFixture().filter((entry) => entry.group === group)
})
)
const wrapper = mountView()
await flushPromises()
expect(wrapper.text()).toContain('同步落库口径')
expect(wrapper.text()).toContain('离职停用')
expect(wrapper.text()).not.toContain('带上已停用的组织带上已停用的组织的说明')
// 排期那一段还得在:不能因为补一组配置失败就把整页打回"暂无数据"
expect(wrapper.text()).toContain('同步频率')
})
it('没有「系统设置」权限时摆得出开关,但按不动也存不了', async () => {
stores.can.mockReturnValue(false)
const wrapper = mountView()
await flushPromises()
const offboard = rowOf(wrapper, '离职停用')!
expect(offboard.find('button').attributes('disabled')).toBeDefined()
await offboard.find('button').trigger('click')
// 按不动 = 一条草稿都不生成,底部那条"未保存"的横条压根不出现
expect(wrapper.text()).not.toContain('项改动未保存')
expect(api.saveConfig).not.toHaveBeenCalled()
})
})

View File

@ -264,6 +264,45 @@
</div>
</section>
<!-- ------------------------------------------------------ 同步落库口径 -->
<section v-if="writeSwitches.length || writeFields.length" class="card p-5">
<div class="mb-4">
<h3 class="flex items-center gap-2 text-sm font-semibold text-gray-900 dark:text-white">
<Icon name="cog" class="h-4 w-4 text-gray-400" />
{{ t('syncSchedule.sectionOptions') }}
</h3>
<p class="mt-0.5 max-w-3xl text-xs leading-5 text-gray-400">{{ t('syncSchedule.optionsHint') }}</p>
</div>
<div class="grid grid-cols-1 gap-x-8 gap-y-4 lg:grid-cols-2">
<div v-for="option in writeSwitches" :key="option.name" class="flex items-start justify-between gap-4">
<div class="min-w-0">
<p class="text-xs font-medium text-gray-700 dark:text-dark-100">{{ option.label }}</p>
<p class="mt-1 text-[11px] leading-4 text-gray-400">{{ option.help }}</p>
</div>
<Toggle
class="mt-0.5 flex-shrink-0"
:model-value="boolValue(option.name)"
:disabled="!canManage"
@update:model-value="(value: boolean) => setValue(option.name, value)"
/>
</div>
</div>
<div class="mt-5 grid grid-cols-1 gap-x-6 gap-y-5 sm:grid-cols-2">
<Input
v-for="field in writeFields"
:key="field.name"
:model-value="textValue(field.name)"
:type="field.kind"
:disabled="!canManage"
:label="field.label"
:hint="field.help"
@update:model-value="(value: string) => setValue(field.name, value)"
/>
</div>
</section>
<!-- -------------------------------------------------------- 执行记录 -->
<section class="card p-5">
<div class="mb-3 flex flex-wrap items-center justify-between gap-3">
@ -305,7 +344,14 @@
</td>
<td class="py-2 pr-3 text-gray-500 dark:text-dark-400">
{{ summaryOf(row) }}
<span v-if="row.message" class="mt-0.5 block text-[11px] text-amber-600 dark:text-amber-400">
<span
v-for="line in detailsOf(row)"
:key="line"
class="mt-0.5 block text-[11px] text-amber-600 dark:text-amber-400"
>
{{ line }}
</span>
<span v-if="row.message" class="mt-0.5 block text-[11px] text-gray-400 dark:text-dark-500">
{{ row.message }}
</span>
</td>
@ -356,7 +402,7 @@ import type { ConfigItem } from '@/api/config'
import type { HubSchedule, HubScheduleJob, HubSyncRun } from '@/api/hub'
import { useAuthStore } from '@/stores/auth'
import { useAppStore } from '@/stores/app'
import { describeCancelResult, stuckRunCount } from '@/utils/hubSync'
import { describeCancelResult, describeRunDetails, describeRunSummary, stuckRunCount } from '@/utils/hubSync'
import { errorMessage, runAction } from '@/utils/oa'
const { t } = useI18n()
@ -416,6 +462,47 @@ const DEFAULT_WEEKDAYS = [1, 2, 3, 4, 5, 6, 7].map((day) => ({ value: day, label
// ------------------------------------------------------------------ 取值与草稿
/**
* 同步往库里写什么、什么情况下宁可不动。
*
* 这一组配置项以前只能由 `PUT /hub/config` 改:清过库、换过站点之后没人说得清自己
* 站在哪一档上,而"离职停用"与"账号让位"这两档一旦开着,下一趟全量就会真的停人改名。
* 标签与说明都取后端给的,口径只在 `dbconfig` 里写一份。
*/
const WRITE_SWITCHES = [
'hub_sync_orgs',
'hub_sync_include_disabled_units',
'hub_sync_bind_local_by_code',
'hub_sync_offboard',
'hub_sync_reclaim_lost_accounts',
'hub_sync_skip_unchanged',
'hub_sync_protect_admins'
]
const WRITE_FIELDS = [
'hub_sync_offboard_guard_percent',
// 三条熔断底线:出出厂值之外没人知道该往哪调,界面上摆出来才谈得上"调"
'hub_sync_offboard_guard_min_people',
'hub_sync_unit_offboard_guard_min',
'hub_sync_roster_floor_percent',
'hub_sync_member_limit',
'hub_sync_email_domain',
'hub_sync_locked_accounts'
]
const writeSwitches = computed(() =>
WRITE_SWITCHES.map((name) => ({ name, label: itemLabel(name), help: itemHelp(name) })).filter((entry) =>
itemOf(entry.name)
)
)
const writeFields = computed(() =>
WRITE_FIELDS.map((name) => ({
name,
kind: itemOf(name)?.kind === 'int' ? 'number' : 'text',
label: itemLabel(name),
help: itemHelp(name)
})).filter((entry) => itemOf(entry.name))
)
function itemOf(name: string): ConfigItem | undefined {
return items.value.find((item) => item.name === name)
}
@ -514,18 +601,11 @@ function statusClass(value: string): string {
}
function summaryOf(row: HubSyncRun): string {
if (row.trigger === 'changes') {
return `${t('hub.changesAppliedCount', { value: row.changes_applied })}${
row.cursor_seq ? ` · ${row.cursor_seq}` : ''
}`
}
if (row.status === 'skipped') return t('hub.skipped')
return [
`${t('hub.created')} ${row.created}`,
`${t('hub.updated')} ${row.updated}`,
`${t('hub.offboarded')} ${row.offboarded}`,
`${t('hub.units')} ${row.units_created}/${row.units_updated}`
].join(' · ')
return describeRunSummary(row, t)
}
function detailsOf(row: HubSyncRun): string[] {
return describeRunDetails(row, t)
}
// --------------------------------------------------------------------- 动作
@ -537,17 +617,26 @@ function resetDraft() {
async function save() {
const names = dirtyNames.value
if (!names.length) return
const values: Record<string, unknown> = {}
// 每一项存回它自己那一组:``hub_sync_include_disabled_units`` 名字像同步项,配置里其实
// 挂在 hub 组下,而后端按组校验配置项,存错组会被当"不认识的配置项"整批打回。
const byGroup = new Map<string, Record<string, unknown>>()
names.forEach((name) => {
values[name] = normalize(name, draft.value[name])
const group = itemOf(name)?.group || CONFIG_GROUP
const bucket = byGroup.get(group) ?? {}
bucket[name] = normalize(name, draft.value[name])
byGroup.set(group, bucket)
})
saving.value = true
const data = await runAction(() => configAPI.saveConfig(CONFIG_GROUP, values))
const saved = await Promise.all(
[...byGroup].map(([group, values]) => runAction(() => configAPI.saveConfig(group, values)))
)
saving.value = false
if (!data) return
// 分了几组就可能只成一部分:先把已经生效的读回来,界面才不会停在草稿上,
// 再把没存进去的那几项留在"未保存"里(错误提示 runAction 已经弹过了)
await fetchAll()
if (saved.some((data) => !data)) return
draft.value = {}
appStore.success(t('syncSchedule.saveDone', { value: names.map(itemLabel).join('、') }))
await fetchAll()
}
async function runFull() {
@ -604,14 +693,17 @@ async function terminate() {
async function fetchAll() {
loading.value = true
try {
const [nextSchedule, nextGroup, nextRuns] = await Promise.all([
const [nextSchedule, nextGroup, nextHubGroup, nextRuns] = await Promise.all([
hubAPI.getSchedule(),
configAPI.getConfigGroup(CONFIG_GROUP),
// 这一组只是补两项落库口径,读不到就当没有:别因为它把整页排期一起带崩
configAPI.getConfigGroup(HUB_GROUP).catch(() => ({ key: HUB_GROUP, label: '', description: '', items: [] })),
hubAPI.syncRuns(20)
])
schedule.value = nextSchedule
// 只留这一页真正会写的项,界面上不摆"看得见改不了"的东西
items.value = nextGroup.items.filter((item) => WRITABLE.includes(item.name))
// 只留这一页真正会写的项,界面上不摆"看得见改不了"的东西;
// 落库口径里有几项挂在 hub 组下,两组一起取才凑得齐
items.value = [...nextGroup.items, ...nextHubGroup.items].filter((item) => WRITABLE.includes(item.name))
runs.value = nextRuns
} catch (error) {
appStore.error(errorMessage(error))
@ -621,6 +713,8 @@ async function fetchAll() {
}
const CONFIG_GROUP = 'hub_sync'
/** 落库口径里有两项(带上已停用的组织、保护本地管理员…)在配置里挂在 hub 组下,取值要一起拉。 */
const HUB_GROUP = 'hub'
const WRITABLE = [
'hub_sync_enabled',
'hub_sync_when',
@ -633,7 +727,23 @@ const WRITABLE = [
'hub_sync_changes_enabled',
'hub_sync_changes_interval_seconds',
'hub_sync_changes_limit',
'hub_sync_changes_full_on_gap'
'hub_sync_changes_full_on_gap',
// 落库口径那一组:以前只能拿 PUT /hub/config 改,界面上看不见,
// 清过库或换过站点的人根本不知道自己站在"会停人改名"这一档上
'hub_sync_orgs',
'hub_sync_include_disabled_units',
'hub_sync_bind_local_by_code',
'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_protect_admins',
'hub_sync_member_limit',
'hub_sync_email_domain',
'hub_sync_locked_accounts'
]
onMounted(fetchAll)

View File

@ -796,6 +796,21 @@ async function load() {
}
}
/**
* 同一个实例里换到另一张待办(直达链接、浏览器前进后退、批完一张接着开另一张):
* 组件不重新挂载,`onMounted` 那一次取数早就过去了,屏上会是上一张单子的内容。
* 这里补取一次,并把上一张留下的意见、标题预告、可退环节、选中的流程节点一起收掉。
*/
watch(taskId, (id, prev) => {
// 离开这一页时参数先变成空,那一档由卸载接手,别拿空 id 去打接口
if (!id || id === prev) return
opinion.value = ''
titleNext.value = ''
goBackTargets.value = []
picked.value = ''
void load()
})
function collectAttachments(): Record<string, unknown>[] {
const fields = formSchema.value?.fields ?? []
const out: Record<string, unknown>[] = []

View File

@ -611,6 +611,10 @@ CREATE TABLE `oa_hub_sync_run` (
`credential` varchar(16) NOT NULL DEFAULT '',
`cursor_seq` bigint unsigned NOT NULL DEFAULT '0',
`changes_applied` int NOT NULL DEFAULT '0',
`renamed` int NOT NULL DEFAULT '0',
`reclaimed` int NOT NULL DEFAULT '0',
`units_rebound` int NOT NULL DEFAULT '0',
`details` json NOT NULL,
PRIMARY KEY (`id`),
KEY `ix_oa_hub_sync_run_status` (`status`),
KEY `idx_oa_hub_sync_run_time` (`started_at`),
@ -786,6 +790,7 @@ CREATE TABLE `oa_notify_delivery` (
`person` varchar(32) NOT NULL,
`person_name` varchar(255) NOT NULL,
`target` varchar(512) NOT NULL,
`target_field` varchar(16) NOT NULL DEFAULT '',
`title` varchar(512) NOT NULL,
`body` text NOT NULL,
`job` varchar(32) NOT NULL,

View File

@ -0,0 +1,28 @@
-- 2026-11-05 生产库结构增量:企业微信推送"按哪一列认人"改成渠道上可配
--
-- 症状:走统一身份 Hub 代发企业微信时,收件人一律先按 users.hub_user_id 认、认不出退回
-- users.account,这个顺序写死在代码里。有的环境同步回来的主键与目录对不上,有的
-- 环境登录账号会被企微「Hub账号」扩展属性改写——谁撞上谁静默收不到提醒,管理员
-- 要等投递记录里攒出一堆 user_not_found 才看得见,而且没地方改。
-- 原因:渠道只配"发到哪 / 发什么事 / 什么形态"三格,唯独"按哪一列认人"没有格子;
-- 投递记录里那一串收件标识也没记它是从哪一列取的,事后无从区分 10086 是 Hub 主键
-- 还是某个人的登录名,界面与「回查送达」都只能按值猜。
-- 范围:只给 oa_notify_delivery 加一列 target_field(记 target 是按哪一列取的:
-- user_id / account,其它渠道留空)。配置本身存在 oa_notify_channel.config 那个
-- json 的 receiver 键上,不动表结构。口径见 backend/app/service/channels.py
-- 的 HUB_RECEIVER_FIELDS 与 docs/hub-integration.md §15.3。
-- 执行:DBA 在生产库上跑这一句。重复跑会在这一句报 1060 Duplicate column name,
-- 是预期噪音。
-- 之后:不用重启,也不用回填。存量渠道没有 receiver 键 = 按默认那一档(Hub 主键优先、
-- 认不出退回登录账号),与改造前行为一字不差;存量投递记录 target_field = '',
-- 读的一路按值猜(纯数字只可能是 Hub 主键),口径与升级前一致。
-- 新配置在「消息通知 → 渠道 → 编辑 → 收件人标识」那一格,旁边直接写着这一档
-- 能发到多少个在职账号。
ALTER TABLE `oa_notify_delivery` ADD COLUMN `target_field` varchar(16) NOT NULL DEFAULT '';
-- 核账:列在;非空的那些就是按新口径发出去的,每一行都说得出自己是哪一列
SELECT COUNT(*) AS deliveries_with_receiver_field
FROM `oa_notify_delivery` WHERE `target_field` <> '';
SELECT `target_field`, COUNT(*) AS rows_count
FROM `oa_notify_delivery` GROUP BY `target_field`;