14 KiB
人员引用口径:库里存的人只认登录账号
起因是一条真实数据。一张表单保存出来的申请人是:
{"applicant": ["管理员\\DSH Hub Admin\\DSH Hub Admin"]}
这格本该回答"这张单是谁的",可它存的是一串派生字符串:部门路径 + 姓名 + 身份名。 它既不是账号,也不是主键,而且三段里没有任何一段能保证一直不变。这篇说清三件事: 为什么它不能当外键、现在的口径是什么、为什么不再有"洗存量数据"这一步。
1. 这串 DN 会漂,而它被当外键铺在了运行态数据上
部门\姓名\身份名 是 O2OA 遗留的身份形状(原来存在 oa_identity.distinguished_name,
拼接函数 app/service/org.py::dn_for)。身份表拿它当"身份证号"没问题——那一行归同步
自己维护,改名时连它一起改,永远自洽。出事的是把它抄到别的表上当引用用:
| 抄在哪里 | 列 | 漂了之后的现象 |
|---|---|---|
| 我发起的 | oa_work.creator_identity / oa_work_completed.creator_identity |
整页空白,一条都不剩 |
| 我的待办 | oa_task.identity / oa_task_completed.identity |
待办点不开,只能重新派 |
| 我的待阅 | oa_read.identity / oa_read_completed.identity |
抄送凭空消失 |
| 通知、评论、会议、日程、网盘共享 | oa_notification.identity 等 |
未读数归零、共享名单失效 |
| 部门主管可见范围 | permissions.scope_person_refs 的白名单 |
主管把改名前的单子全筛没了 |
表单里选人格子 type: user |
work.data.applicant … |
SQL 取数、额度维度、回写映射一起断 |
失效的机制很朴素:查询用的是等号。改名前那一行存的是
优尼森科技\研发中心\一组\张三\zhangsan,改名后拿去匹配的却是
zhangsan(或换成新 DN),两个字符串不相等,SQL 就是不返回,而且一声不响——没有报错、
没有日志、界面上只是"最近没有数据"。同步的引用搬运(app/service/hub_refs.py)
只覆盖配置表(审批岗位、岗位组、环节审批人、流程发起范围、代理、共享名单),
运行态那批表压根不在清单里:历史单据本来也不该被搬——那张单是"当时的张三"发起的。
所以问题不是"搬得不够勤",而是这个值根本不该被当键用。
那串真实数据尤其能说明事。它是 Hub 同步建号之后、部门又改过一次名算出来的:
建号时 DN 末段还是账号(hub_sync._ensure_identity 传的是 person.account),
而部门改名/挪层级时重算用的是身份自己的名字
(hub_sync._sync_identity_rows_of → dn_for(path, row.person_name, row.name),
row.name 就是姓名),于是末段从账号变成了姓名。
一条"外键"在三段里没有一个字节是稳定标识,而且同一条同步链路就会改写它。
2. 口径:写账号、读只认账号、查等号
登录账号(users.account)是本部署对外认人的唯一业务键:数据库上有唯一键
(uk_users_account),财务、HR、上游系统存的员工编码就是它,运维口径承诺不改。
这是整套认人体系唯一需要守住的不变量——守住它,改名、挪部门、调岗都不会让历史数据失联。
| 要做的事 | 用什么 | 位置 |
|---|---|---|
| 写:把一个人存下来 | personref.ref_of(person) → 账号 |
app/service/personref.py |
| 读:手上这串值是谁 | personref.account_of(db, value) / resolve() |
同上 |
| 读:一批值 → 一批账号 | personref.map_accounts() / accounts_of()(一次查完) |
同上 |
| 查:这一列是不是这个人 | personref.where_is() / clause() |
同上 |
| 表单落库前洗那一格 | formruntime.normalize_person_values(db, fields, data) |
app/service/formruntime.py |
| 前端把账号读回姓名 | utils/personLabel.ts,批量问 /org/persons/label |
前端 |
四条规矩:
- 写只有一个形状:账号。别再拼 DN,也别存
users.id。选人控件交出来的本来就是账号; 凡是界面上把人员引用交给后端写的口(代理人、待办交接、部门负责人),后端当场换算成 账号,认不出就 400,绝不把一串对不上人的字符串写进"这活归谁"那一列——那样待办会从 本人的待办和对方的待办里同时消失,只剩一条谁也接不了的单。 - 读只认两种输入:账号,以及
users.id(oa_task.person那一类列历史上就是主键)。 其余一律认不出——身份 DN 不当引用用,多身份(一人多个oa_identity)也不再是本 部署的口径(那张表 2026-10 已整张下线)。既然写侧只有账号一种形状,读侧就不需要为别的写法留活口。 - 认不出就不是一个人。审批人解析、可见范围白名单、共享名单拿到认不出的值就丢掉并 如实报出去(设计器报红、环节走配好的空审批人兜底)。绝不把一串对不上人的字符串当成 一个人——那种待办派给了一个不存在的人,流程就静默卡在环节上。也绝不按姓名猜人: 同名的一抓一把,认错人比查不到人严重得多。
- 认人不看在职状态。停用的人历史单子要打得开、待办要能收场;"只算在职人"是审批人
解析的事,调用处过
org.live_refs。
为什么不存 users.id:那一列同时是给人看的(打印、导出、标题模板),也是给对接方的
(where account = :applicant 这类 SQL 取数、额度维度、回写映射都按员工编码比)。
主键塞进去,这些下游一起报废。id 仍然被"读"认得,仅此而已。
为什么不存姓名:见上面第 3 条。
那张"一人多身份"的 oa_identity 档案副本表已经整张下线(2026-10):它只在展示路径上
被读,认人、算部门、派待办一处都不看它,却要在同步、建号、改部门、删人时处处维护,还要在
每个"问这批人是谁"的批量查询里多排一次队。现在 DN 由 users + oa_unit 现算
(org.dn_for(部门路径, 姓名, 账号)),只给组织树那一行与打印用;库里再无第二处真相。
配完之后变的只有展示:人员列表「身份」列多一个徽章、GET /auth/me 与 GET /org/persons
的 identities[] 多一条。待办、发起范围、审批人解析、选人控件一概不变——它们按账号认人
(上面第 2 条),PeoplePicker 一项的 value 就是 users.account,一人一项;
第二个身份不会让他多一份待办,也不会让选人框多出一个可点的"兼岗"。
2.1 账号是那条不能动的线
换成账号之后,"改名字、挪部门、调岗"都不再影响历史数据,剩下的唯一风险就是账号本身被改:
oa_work.creator_identity、oa_task.identity 这些历史行按口径不跟着搬家(那张单记的是
"当时的那个人",表单数据里还嵌着同一串,搬它等于改写流程实例),所以旧账号上压着的单会从
"我发起的""我的待办"里查不到。
这条线有两道防线。运维口径是正解:登录账号不改——它是财务、HR、上游系统一起认的业务键,
Hub 真要改账号,上游那批数据同样会失联,不该由 OA 悄悄跟着改。同步这一侧只做看得见:
统一身份同步在收尾时数出还压在旧账号上的历史行,报进同步记录(hub_refs.runtime_drift),
不让人第二天自己发现。
3. 没有"洗存量数据"这一步
本系统还在开发期,库里没有需要保住的存量单据,所以换口径就是换代码:写侧一律写账号, 读侧一律只认账号,读侧永远不为旧写法留解析分支。留一支"老 DN 也认"的兼容代码, 代价是这支分支永远没人测、还随时可能把派生字符串重新请回外键的位置。
库里的旧字符串不是靠兼容分支消化,而是靠一次显式的体检 + 换算(scripts/migrate_identity_refs.py):
它只改字符串本身,读侧口径一个字都不动,默认只看不动库。按风险分三档,各开一个开关:
| 档 | 管的是什么 | 命令 | 换算规则 |
|---|---|---|---|
| 配置(默认档) | 审批岗位成员、分组成员、流程发起范围、代理、共享名单、环节审批人 taskValues |
migrate_identity_refs.py [--apply] |
只动现在解析不出人的那几条 |
| 运行态与历史行 | oa_task.identity、oa_read.identity、oa_notification.identity、流转日志…,以及 JSON 格子里挂着的人引用(退回暂存 oa_work.go_back_store.identity) |
--runtime [--apply] |
同上;动的是留痕,所以必须明写 |
| 表单数据里选人那一格 | oa_work.data / oa_draft.data / oa_work_completed.data 里 type: user 的格子(含明细表选人列) |
--form-data [--apply],归档件要再写 --all |
同上 |
第三档最容易漏:哪一格是人按字段类型说的,列名上看不出来,所以前两档那套"某一列存人"
的清单天生扫不到它。最初的故障恰好长在这里——{"applicant": ["管理员\\DSH Hub Admin\\DSH Hub Admin"]}
让 where account = :applicant 永远查不出收款账户,而报回来的只是"没查到数据"。
在办与草稿那一格认不出人,带出、额度、审批人解析会一起空掉,是"现在还疼"的,所以默认档就换它;
办结那一份记的是"当时的张三",允许原样留着,想连它一起换得明写 --all。
三档的换算规则一模一样,也只有两条:DN 末段是库里存在的登录账号 → 换成账号; 末段不是账号但倒数第二段恰好只有一个同名的在职人 → 换成他。其余一条都不改(人已不在库里、 或者同名有歧义),原样报给人看——悄悄改成一个可能不对的审批人是错的,设计器把它报红是对的。
写侧那三条兜底一个字没动:
- 落库前洗那一格:
normalize_person_values只洗type: user的格子(含明细表里的 选人列),换成认得出的账号;认不出的原样留着,绝不照着 DN 尾巴剪一刀——部门改过一次 名之后末段就是姓名,剪完等于把一个人洗成一段中文,比留着一串没用的值更糟。文本格子里 带反斜杠的(a\b\c)一律不碰。 - 认不出不派工:环节审批人算出来是空的,就走这个环节配好的空审批人兜底,同时在设计器 与同步记录里报出来。宁可看得见地"没人办",也不要静默派给一个对不上的人。
- 写入口当场换算:
api/org.py::_account_or_fail是那一类"前端交一个人上来"的接口的 共同前置,换算不出账号就直接 400,让调用方立刻知道自己写错了,而不是把问题留给流程。
常驻门 scripts/check_identity_refs.py 问四件事:
- 改写那几步会不会写歪——
_account_for/_swap_value/_write_cell/_blob_swaps/_live_only各有一条不带库的断言(数组不能退化成单值、明细行整行复制、文本格子里的a\b\c一个字符都不碰、同名不挑人、--apply默认不碰归档件); - 该扫的列有没有漏——拿
information_schema把库里每一列名字像"存人"的列都对一遍: 要么在三档清单里,要么在EXEMPT里写明它为什么不存人引用(*_identity_name那些是 姓名快照、actor/owner_person那几列存的是users.id)。加一列忘了登记,门就红——oa_work.data里选人那一格当初就是这么漏的,那处压着 50 条能换算的 DN; - 三档扫下来可换算的 DN 必须是 0(配置、运行态与历史行、表单数据含归档);
- 换算不出的那些不算失败——人已不在这个库里或姓名撞车,门不许替人挑一个审批人, 由设计器报红、由体检报告交出去。
2026-10-22 这一轮把三档都跑干净了:配置 0 条、运行态与历史行 0 条可换算、表单数据 50 条
(在办 6 + 归档 44)全部换完。库里剩下的 DN 全是换算不出的那一类——
测试经办人、测试总账会计、测试部门主管、QA测试总经理B 这几个人已经不在库里
(QA测试主管 / QA测试员工 / QA测试财务经理 还在,所以按姓名唯一命中换掉了;
测试总经理 与还在的 QA测试总经理 差一个字,不算同一个人,一条都没动)。
这些人哪天重新同步进来,旧行会变成"可换算",门会重新红一次,届时跑一句 --apply 就行。
4. 验收
cd backend && python3 scripts/check_person_ref.py
九段,其中三段专门钉死这篇文档说的三件事:
- 读只认账号与主键——DN、姓名、查无此人的串统统返回空,谁也别想靠派生值认人;
- 写入口只认账号——代理人与待办交接这类接口收到认不出的写法当场 400,不让它落库;
- 认不出的人不派工——环节审批人里混进对不上账号的值就只出认得出的人,全认不出就是 空清单交给兜底,表单来源那一格是 DN 也不派人;
- 同步改名之后历史还在——模拟部门改名挪层级 + 人改名 + 调岗,按账号查"我发起的" "我的待办""部门主管可见范围"照旧命中,同一批数据按 DN 查命中 0 条(反例必须一直在, 否则下次又有人把派生值当键)。