# Helix Changelog > **2026-09-09 — fix(dax): remove scheduled production catalog overwrite (0 migration / 0 API / 0 MCP).** Removed the daily GitHub catalog seed and its automatic commit-mode defaults after it reset production `requestable` settings and invalidated an approved request. Catalog imports are explicit manual operations, dry-run by default. Production workflow was disabled to stop recurrence while this change ships. Validation: deployment workflow contracts, including a manual-only trigger regression. > **2026-09-09 — fix(assistant): 一张被转发进群的帮助卡,点它会指错线程、并许下一个兑现不了的承诺(0 迁移 / 0 端点 / 0 MCP / 0 cron)** 安全扫描顺带扫出来的两处**正确性**缺陷(安全面本身零发现)。帮助卡上的按钮在**转发之后仍然可以点**,而回调带回来的是那个群的 `chat_id`。 这两颗按钮动的都是这个人的**私聊**线程:答案私聊发、工单引用的是他和助手的对话、「你的下一条消息我直接整理成工单」说的也是他在私聊里打的下一句。按群来记的后果很具体:① 菜单里的「新话题」会去清一个群的线程,他自己的那段对话原封不动地留着;② 那个「下一条成单」的标记记在一个**永远不会被兑现**的键上(消费只发生在私聊分支)—— 员工刚被告知它会兑现。 修法是把线程键的优先级反过来:先取这个人的私聊指针,拿不到才退回按钮所在的会话(正常情况下两者是同一个 id,所以这一行是纯保险);并且**只在还没有指针时**才由卡片写它 —— 消息那一侧本来就「只记单聊」。语言判定那一处的顺序**故意保持相反**:它问的是「这个房间在用哪种语言」,工单群里的卡就该跟着群走。 **验证**:2 条用例(群里点开场白仍然接私聊那段对话 / 群里点转人工之后,私聊里的下一条消息仍然直接成单);一处变异验证转红;`test_assistant` 918 passed / 4 skipped。 > **2026-09-09 — fix(assistant): 助手门面四个 PR 的合并后复审 —— 七处修复,其中一处是给「被偷走的 PAT」开的后门(0 迁移 / 0 端点 / **-1 MCP** → 629)** 四个 PR(#3537–#3540)各自绿着合进去了,合起来复审找到七处。三处是**跨 PR** 的 —— 两半各自都对、相交的那一格里躺着缺陷,单 PR 自审原理上看不见。 🔴 **1. 一个中文同事打 `/help`,收到的是一张英文帮助卡。** 帮助卡按 `lang` 渲染是对的;回复语言跟着写来的那句话走也是对的;而 `/help` 恰好是**四个拉丁字母**,足以被判成英文。`/reset` / `reset` / `new topic` 同理。开关词是我们自己印在菜单和说明里的字符串,在任何语言的员工手里都长成那样 —— 它们不是语言信号,现在整批排除在判定之外(`_is_channel_command`)。 🔴 **2. 一段英文对话,点一下卡片上的按钮就回一句中文。** 卡片回调此前一律 `resolve_lang`,而会话语言这个概念是上一个 PR 才有的。新增 `reply_language.for_card`(会话记忆 → 偏好,没有文字可判所以少一步),用在飞书卡片回调、网页线程恢复(刷新之后重画的待确认卡片)和网页「新话题」三处。 🔴 **3. `set_my_language` 这个 MCP 工具是给被偷走的 PAT 开的后门 —— 删掉。** 它的 HTTP 孪生 `PATCH /auth/me/profile` **明确拒绝 PAT**(ADR:一个被偷走的 PAT 不该能把人的语言悄悄换成他读不懂的那种、让他错过通知),而 MCP 的鉴权只有 PAT / MCP-OAuth,从来不是浏览器会话。按 `reveal_my_contact` 的先例改成「非 jwt 一律拒绝」也不行:那样它在任何可达上下文里都不会成功,而且**派生出来的卡片会在员工点完确认之后才拒绝**。工具删除、curated 卡片条目撤回、hint 630 → **629**、目录上界回到 81,并在两处都写下了「下一个人为什么不该再加一次」。改语言的两条路仍在:飞书帮助卡(飞书验签的操作者身份,等价于本人在自己的客户端上点)和网页个人设置页。 **4.** 点开场白那一轮的语言改为从**那句话**判(而不是沿用点击时的渲染语言),顺带让会话语言记忆跟上;并加了一条结构测试:**每一句开场白的三个译文都必须被判回它自己的语言** —— 否则员工点了日文那句会拿回英文答案。**5.** 机器人菜单事件同样没有文字可判,一并改成按会话语言(「英文聊完点开菜单里的『使用帮助』,拿到一张中文卡」是同一个缺陷的第三个入口)。**6.** `_switch_language` 里一处与模块顶层重复的 `session` import。**7.** 一条数按钮的断言在语言行加进来之后没有跟上(已在 #3539 里当场修掉,记在这里是因为它正是那类断言存在的理由)。 **验证**:新增 11 条用例(六个开关词各一条 + 会话不被开关词污染 + `/help` 拿到本人语言的卡 + 点按钮不切语言 + 每句开场白的语言自洽 + 「这条路不该有 MCP 工具」的反向断言);两处变异验证各自转红;`test_assistant` + `test_support` + `test_mcp` 1126 passed(唯一一处红是 `inspect.getsource` 的假红 —— 跑全量时我在改同一个文件,单跑 6 passed)。 > **2026-09-09 — feat(support): 网页与移动端求助页的开场白,改由飞书帮助卡的同一份注册表来给(0 迁移 / +1 端点 / 0 MCP / 0 cron)** 飞书那张帮助卡有八类、每类四句「点一下就问」的开场白;网页 `/me/support` 的空状态是**四个写死在前端 i18n 里**的建议,移动端**一句都没有**(只有一段介绍文字)。两处各写一份的下场是下一次编辑就分叉 —— 而这些句子不是装饰:每一句都是「助手真能回答它」的承诺,写歪一句,员工按下去拿到的是「我查不到」。 现在前端不再自带这份文案,改从 `GET /support/copilot/starters` 拿。**同一份 `assistant/starters.py`,按各自的画布铺开**:聊天里没有横向空间,所以飞书那张卡是两级(选类 → 选句);网页和移动端一屏就能同时给出「有哪些类」和「这一类能问什么」,所以是一行分类 + 下面铺开的开场白。点一句发出去的**就是按钮上那一句**(有一条测试专门钉这个)。 语言按**页面当前语言**取,不是按 `preferred_language` —— 一个今天在读英文界面的人不该在这一块看到中文,而那一列决定的是通知用什么语言。认不出来的语言标签**不** 422:它不是员工打进去的东西,报错只会让整块开场白消失,而原因是一个他看不见的查询参数。 取不到就**不画这一块**,输入框照常能用 —— 没有本地兜底文案:两份文案迟早会分叉。四个 `support.copilot.suggest.s*` 键随之从三个语言包里删掉。 **验证**:后端 4 条(两个面同源、页面语言优先、坏语言标签降级、未登录 401);前端 4 条 DOM 用例(分类来自服务端、换类换句、点哪句发哪句、取不到也不挡输入),并**在既有的 SupportChatPanel 测试里补上了这个新端点的桩** —— 不补的话它会逃出 jsdom 打到本机(#3298 的教训:要打的是挂载的整棵树碰到的每一个端点)。一处变异验证转红(把发出去的句子换成 key)。`pnpm lint` / `pnpm typecheck` / `pnpm test`(108 文件 / 1433 用例)全过;后端 `test_support` + `test_assistant` 995 passed。 > **2026-09-09 — feat(assistant): 语言设错了的人,自己就能在卡上一键改过来(0 迁移 / 0 端点 / +1 MCP → 630)** 上一条把回复语言改成「跟着员工写来的那句话走」。但**通知不跟**,也不该跟 —— 它们的语言由 `identity_persons.preferred_language` 定,而那一列对相当一部分人是**猜**出来的:没有显式偏好时 `resolve_lang` 按国家推断,于是一个在中国办公、只读英文的同事收到的每一封通知都是中文,**而他没有任何地方可以说「我读英文」** —— 网页个人设置页有那个下拉框,但他得先知道有那个页面。 现在改语言这件事出现在他第一次意识到「这东西说的不是我的语言」的那个位置:**帮助卡的底部**。三个名字都用目标语言自己写(中文 / English / 日本語 —— 一个只读英文的人在中文卡上认「英语」两个字比认「English」难),当前选中的前面打勾。**没显式选过的人一个都不勾**:按国家推断出来的那个不是他选的,把它画成选中态,会让「我明明没选过」变成一个没人能回答的问题。 一次点击写进那一列,于是通知、邮件、卡片一起跟着变。**点完清掉这个会话的语言记忆** —— 那一格记的是「他刚才用什么语言说话」,而他刚刚明说了要用哪种;不清的话,下一句「ok」会把他拉回旧语言,而他刚按过按钮,只会觉得开关坏了。 这一列现在有三个写入面(个人设置页 / 帮助卡 / MCP),所以「怎么写」收进了 `app/identity/preferences.py` 一处:校验、赋值、审计(`identity.person.language_set`,带 `source`)只写一遍。**同 PR 补上 MCP 工具 `set_my_language`**(629 → 630),按 curated-card 规矩配了三语标题与 `language` 字段标签、上界 81 → 82 并写了理由 —— 这一条对卡片三语的要求比别的都高:它是整条链路上唯一一个「用你读不懂的语言问你要不要改语言」的确认,标题缺一门,那张卡本身就是他要解决的那个问题。 **验证**:11 条用例(三语按钮齐全与打勾规则、写列、审计、清记忆、无效码、重复设置不写审计噪音、MCP 工具与卡片同源);两处变异验证各自转红(不清记忆 / 不写列);四道 curated-card 闸与 `test_the_catalogue_cannot_grow_unnoticed` 同时绿。 > **2026-09-09 — feat(assistant): 员工用什么语言问,助手就用什么语言答(0 迁移 / 0 端点 / 0 MCP / 0 cron)** 在这之前,助手无论对方写来的是什么语言,一律按 `identity_persons.preferred_language` 解析出来的语言作答 —— 提示词里还专门写了一句「**不要**看他打的字」。那条规则对通知是对的(收件人不一定是刚才说话的人),对对话是错的:一个把 Helix 语言设成中文的同事临时用英文问一句(给外籍同事转述、从英文报错里粘一段),得到的仍然是中文。 现在按三步定这一轮的语言:**这句话本身** → **这个会话上一次用的语言** → **这个人的偏好**。第二步是它能成立的关键 —— 判不出来的句子占相当一部分(「ok」「VPN」、一个裸资产号、一串工单号),而它们几乎总是上一句的延续;没有这一层,一段英文对话里的一句「ok」会把回答翻回中文,员工完全无从理解为什么。 判定只看字符脚本,三条都是踩点:**假名出现即日语**(日语句子必然带假名,而假名不出现在中文里);**汉字与拉丁字母比分量不比有无**(一个汉字按 2 个字母计 —— 只看「有没有汉字」会让「How do I connect to 飞书?」判成中文,而那正是旧提示词那句警告要保住的例子);**太短的纯拉丁串不算数**(`OK` / `VPN` / `hi` 一律返回「判不出来」)。 `resolve_lang` 仍然是全平台唯一的语言权威 —— **它回答的问题没变**(这个人读哪种语言),新加的函数回答的是另一个问题(这一句是用什么语言问的)。通知、邮件、卡片模板一律不动,也**不**写回 `preferred_language`:临时用一次英文不是改偏好。 网页 IT 求助走同一个判定,否则同一个人在两个面上问同一句话会拿到两种语言的答案。🔴 **顺带修掉一处一直是中文的文案**:身份还没解析出来的发件人(没绑定 / 身份对不上)以前一律收到中文的「请先用飞书登录一次 Helix」—— 而收到它的人恰恰是平台还不认识的那个,英文同事读到的是一句他看不懂的指引。 **验证**:28 条用例,含 19 条判定矩阵(混排、弱信号、一个中文名词不该翻车);两处变异验证各自转红(去掉会话记忆 / 退回「永远按偏好」)。其中一条用例第一版**打错了 monkeypatch 的位置**(补的是 `app.core.redis_client.get_redis`,而 `session` 用的是 `from … import` 拿到的绑定),于是真 Redis 照常工作、这条用例验的其实是别的东西 —— 已改成打在 `session` 自己那个名字上,并把这件事写进了注释。ADR 见 DECISIONS 2026-09-09。 > **2026-09-09 — feat(assistant): 飞书助手的「使用帮助」从一堵字墙变成一张可以点的卡,点一句就等于问一句(0 迁移 / 0 端点 / 0 MCP / 0 cron)** 用户的原话是「有更好看的东西啊 不是这样一堆文字」。之前机器人菜单里的「使用帮助」回的是 `msg_type="text"` 的一整屏文字 —— 纯文本渲染不了 markdown,层级只能靠【】和「•」撑,而且读完之后员工仍然要自己想「那我现在打什么」。 现在它是一张**两级卡片 2.0**:一级卡是能力三行(能查 / 能办 / 办不了会说清楚)+ 八类问题的按钮阵 + 一颗「转人工」;点进一类是四句**可以直接点出去的问题**。点一句**就等于把那句话打给助手** —— 同一个限速窗口、同一把每聊天的回合锁、同一条投递路径(这一版把 `handle_message_event` 里那段投递抽成了共享的 `deliver_turn`),所以答案该带参考文档就带参考文档,不会因为「是点出来的」而降一档。 按钮回传的是 `{"c": 类, "s": 条}` 两个 **key**,句子由服务端按当事人的语言从 `assistant/starters.py` 取:载荷小、改文案对老卡片立即生效,而**伪造一个 payload 也只能选到表里已有的那 32 句**,注入不进任意文本。 **分类口径不是新造的** —— 前六类沿用员工已经熟悉的飞书服务台分类(IT Equipment / Account & Access / Network & VPN / Onboarding / Using Lark + Google Workspace + Meetings / Spam & Security),后两类(申请与进度、云与数据权限)是 Helix 才有的能力:服务台答不了「**我的**申请到哪一步了」。 🔴 **顺手修掉一个一直在发生的缺陷:空对话里的「转人工」会开出一张空工单。** `draft_ticket_from_history([])` 的产物是标题「AI 求助升级」、正文只有一行说明 —— IT 拿到手还得回头再问一遍「你遇到什么事了」,而那正是这条链路存在的理由。现在 `escalation.offer_ticket` 在线程为空时先请员工用一句话说明,并记一笔 15 分钟的标记;下一条消息由 `GETDEL` 取走标记后**直接**做成工单,不再过模型(员工已经说了他要人,再让模型接一次话是把他推回原点)。规则放在 `offer_ticket` 里而不是按钮那一侧,所以**打字说「转人工」和点按钮拿到的是同一个行为**。 菜单事件里 `assistant.menu.start` 与 `.help` 现在回同一张卡(飞书侧那两个菜单项已经合成一个),`_START_HELP` 那段死文案一并删掉;卡片发不出去时仍退回原来的纯文本说明 —— 卡片是排版,说明才是目的。 **验证**:23 条新用例,含「每颗按钮的动作都被分派器认领」这条成对契约(对不上的长相是「按钮在,点了没反应」,只在员工的聊天窗里看得见);三处变异验证各自转红。卡片用 Helix 飞书应用凭据**真发给自己**实测,zh / en 一级卡与二级卡均 `code: 0`。 > **2026-09-08 — fix(web): 上一条的「0 处遗留」是假的 —— 审计脚本自己有盲点,漏了 `CountryMultiSelect`(0 迁移 / 0 端点 / 0 MCP / 0 cron)** 紧接上一条。那条结尾写「检测脚本复跑:38 处 responsive,**0 处仍是内容自适应**」—— 这个数字是错的,真实值是 1。 🔴 **错在审计脚本的谓词,不在改动**:它判断「这个 Select 有没有固定宽度」的方式是**在整个 `` 开标签逐个判定后,真实数字是:全仓 38 处 `maxTagCount="responsive"`,其中 **29 处的宽度仍由内容决定**(24 处只有 `minWidth`,**5 处连宽度都没有** —— 后者是最坏形态,连下限都没有)。分布:资产列表 7、财务月结 4、赏金报告 3、闲置电脑 2、云资源目录 2、入职策略 2,以及人员筛选器 / 政策通知 / 用户管理 / 软件成本 / 云子账号申请 / 邮件组日志 / 财务浏览器 / GitHub 组织各 1。 **取证不是照搬上一条的结论,是在第二个页面上重新做了一次 A/B**(`/admin/users` 的用工类型筛选,`.filterSelect` 的 `min-width: 160px`,en-US): | | 40 帧内的不同状态数 | |---|---| | 旧样式(`width:auto` + `min-width:160`) | **40 / 40** —— 196.4px(显示 `Agency-dispatched`)⇄ 160.0px(塌成「+ 1 ...」),每帧都在翻 | | 修复后(固定 `width: 200`) | **1 / 40** | **并且验证了这次采用的机械规则是安全的**:改动一律取「`minWidth: N` → `width: N`」(数值不动,所以塌陷态下的版面与之前逐像素一致)。担心的是「标签比框宽时会不会仍然抖」—— 实测固定 150 / 160 / 200 三档、内容明显超宽时都是 **1 个状态**:塌成「+ 2 ...」后保持不动。**塌陷是稳定的,抖动才是 bug。** 5 处没有宽度的按语境给基:三处在 `Form.Item` 里(人员筛选器、政策通知的关键词 `mode="tags"`、入职策略弹窗的两个)给 `width: '100%'` —— 百分比同样不是内容自适应,一样能断环;`/admin/users` 那处在 CSS Module 里(`.filterSelect` 只设了 `min-width`)**没有改类**,而是就地 `style={{ width: 200 }}` 覆盖 —— 那个类还被同页的单选 Select 共用,它们理应随标签生长。 **没做的事**:除了 `/admin/users`,其余 13 个页面没有逐页目视走查宽度是否好看(缺可复现的数据),所以一律不动数值。若某页塌得太早读不到内容,单独调宽即可 —— 那是观感问题,不再是抖动问题。 > **2026-09-08 — fix(cloud): 「我的云订阅」筛选条选中一个云厂商后整页 60fps 抖动 —— 把 `minWidth` 换成固定 `width`(0 迁移 / 0 端点 / 0 MCP / 0 cron)** 用户报「条件选了多一个就闪烁」,录屏逐帧差分把闪烁定位在筛选条:云厂商 Select 每一帧都在两个状态之间翻转,右侧的「环境 / Owner / 只看我是 Owner」跟着左右跳,第二行整体位移,读起来就是**整页不停闪**。 **机理是一个宽度自反馈环**。antd `Select` 是 `inline-flex`,只给 `minWidth` 时它的渲染宽度由自己的标签内容决定;而 `maxTagCount="responsive"` 又正是**量这个渲染宽度**来决定显示几个标签 —— 两者互为输入。只要有一个标签比下限宽,环就闭合:显示标签 → 宽度 200 → 218.3px → 该行溢出 → flex-shrink 压回 200 → 标签放不下 → collapse 成「+ 1 ...」→ 内容变窄 → 又能长 → 显示标签 → … 🔴 **中文界面把它藏了一年**:`AliCloud (国内)` 只有 128px,压在 200px 下限之内,Select 从不生长,环就从不闭合。英文 `AliCloud (international)` 是 203px —— 报障来自 en-US 界面,而这是**唯一**能看见它的语言。任何「一个标签比 minWidth 宽」的多选筛选都具备同样的条件(Owner 这类「姓名 · 邮箱」标签尤其)。 **取证**:headless Chrome + CDP(桌面端 Browser pane 的页面恒为 hidden,没有 rAF/ResizeObserver,这类重排 bug 在它里面原理上复现不出来),mock 60 行订阅载荷,逐 rAF 帧记录筛选条几何。修复前,单选一个 `AliCloud (international)` 标签时,**1380–1900 之间 261 个视口宽度全部不稳定**(18 帧 18 个状态,即每帧都在翻);修复后同一轮 sweep **0 个不稳定**,且标签完整显示(此前塌成「+ 1 ...」,连自己筛了什么都读不到)。 **改动**:`MyCloudGrantsPage`(云厂商 240 / 环境 200 / Owner 240 / 到期 180 / 已结束原因 260)与其管理面孪生 `CloudScopesPage`(云厂商 240 ×2 / 环境 200)的筛选 Select 一律改为固定 `width`,并把机理与取证写进两处注释。固定宽度让 flex basis 不再随标签数变化,测量第一遍就收敛。 **未处理(需拍板)**:仓库里还有约 12 处 `maxTagCount="responsive"` 搭 `minWidth`,同一条件下都会抖。查法:`grep -rn -B6 'maxTagCount="responsive"' web/src | grep minWidth`。本 PR 只修了报障页与其孪生页,没有全仓铺开。 > **2026-09-08 — fix(ci): go-ci 从 #3527 起连红五轮 —— 两道后端守卫,而 PR 上看不到它们** **go-ci 是 post-merge 的**(PR 上零 check),所以这两条只会在**合并之后**变红,而我在合并前没有本地跑过 `server/scripts/ci/run_backend_validation.py` 里的那几道守卫。#3526 是最后一次绿,#3527(迁移 635)起连红五轮。 **1. `check_tidb_parity` 命中的是我自己的一句注释。** 守卫按**字面量**扫描整个 `sa.Column(...)` 调用体,而我在那个调用里写了一句「用 `id_type_for(父表)` 而不是裸 `CHAR(36)`」—— 于是一句「不要用 X」的解释被当成真的用了 X。代码本身从一开始就是对的(`id_type_for("identity_persons")`)。改法是把那句话换成不含字面写法的说法,并在原地写清**为什么不能写它** —— 加豁免标记是错的:那会把这一段窗口里将来真正的裸类型一起放过。 **2. `check_savepoint_isolation` 命中 `owner_reach.on_leave_today`** 的那个 `try`。这一处是**真·只读**(一条 SELECT,一条都不写),而让整个事务失效的是**失败的 flush**、不是失败的读;把一次纯读包进 savepoint 只是给每一次拉人加一次往返。按守卫自己给的判据(不写库 ⇒ 可豁免)加了 `# savepoint-exempt:`,并写清要挡的失败很具体:休假表/列在这个库里不存在时,正确答案是「当他在」而不是让转人工整条链路挂掉。 ⚠️ **这道守卫拦住的不是形式问题**:CHAR(36)+FK 在 TiDB 上就是 3780,而它**本地 MySQL 复现不出来** —— 若照原样发布,迁移会卡在 635,后面每一条都堵在它后面。这次是守卫先于生产发现的。 **验证**:本地逐条跑通 `check_alembic_chain`(626 revisions,单 head = 636)/ `check_savepoint_isolation` / `check_tidb_parity` / `ruff` / `check_mypy_baseline`(1268 = baseline)/ `uv lock --check` / 那三条 `--noconftest` 守卫用例(3 + 24 + 7 passed)。 > **2026-09-08 — docs(ops): 运维手册漏了两个事件订阅 —— 缺了不报错,只会安静地少两种行为** 「助手进群」那一批(#3521–#3527)加了两个成员事件的处理器(`im.chat.member.bot.added_v1` / `deleted_v1`),而开通步骤里只写了 `im.message.receive_v1`。照着手册做一遍,这两种行为**不会报错,只会不存在**: - 少了 added:机器人静静地待在一个新群里 —— 屋里的人不会去猜「@我 就能问」; - 少了 deleted:台账里那条 `feishu_chat_id` 一直指向一个机器人已经不在的房间,后面**每一次**往它发消息都会失败,而失败原因读起来像飞书故障。 顺带把这一批新增调用的权限要求写清:读群历史走 `im:message`(缺它的表现是「总结不出来」而不是报错)、`GET /bot/v3/info` 不需要权限、解散要求应用是**群主**(Helix 自己建的群天然满足,别人拉机器人进去的群永远不会被解散 —— 收尾任务只认台账里的行)。 > **2026-09-08 — fix(assistant/mobile): 手机上没有「拉个群聊」,而员工基本都在飞书客户端里(0 迁移 / 0 端点 / 0 MCP)** 两处移动端欠账,都在「助手进群」这条链路的正对面。 🔴 **手机上根本没有「拉个群聊 / 进群」。** 桌面工单页、后台队列、助手那张卡都有(那正是拍板时说的「三个面」),而**员工基本都在飞书客户端里** —— 也就是说这条链路存在的理由(「把这件事拉个群说」)在他最常用的那个面上不存在。已经有群时是入口,没有时是「开一个」;结束了的工单只留入口(后端也只在那时放行开群);导航用 `location.href` 而不是 `window.open` —— 飞书的内置浏览器拦弹窗,而一个被拦掉的弹窗表现成「按了没反应」。刻意**没有**「解散群」:那一下不可逆,而它已经有两个家(桌面工单页、群里敲一句「解散」)。 🔴 **手机上处理人对自己名下的工单动不了手。** `can_act_on_ticket` 从这一轮起是「global_admin **或这张工单的处理人**」—— 而「转人工」指派出去的路由负责人**往往不是 global_admin**,这正是当初加上那一半的理由。移动端的 `canAgentAct` 还只认 `global_admin`:他在手机上看到的是一张只读页,而他正是该动手的那个人。 可见性与后端逐字一致(求助人本人 / 能动这张工单的人),所以只读档(auditor / management)读得到这张工单、但不会看到一颗按下去必然 403 的按钮。 **验证**:`pnpm typecheck` + `lint`(含 i18n 三语平价、内链、mobile Tag 色调等 13 道守卫)+ 1426 vitest 全绿。 > **2026-09-08 — fix(assistant): 「催几轮后升级」这个旋钮在设置页上根本不存在(迁移 636 = 一行数据)** `assistant.room_escalate_after_reminders`(默认 3)是升级行为**唯一**的旋钮,而它在 635 落地时只以代码里的默认值存在 —— 平台设置页列的是 `platform_settings` 里**实际有的行**,所以这个键在页面上根本不出现:管理员想把它改成 2 或者 5,没有入口,除非先从运维手册里抄出准确的键名和类型再手工新建一行。 同一批设置里另外五个键(群内应答两个开关、群频次、保留期、静默提问)都是种进去的,唯独这一个漏了。「配置入口指向真开关」是这个仓库反复付过学费的一条:**一个文档里写着、页面上不存在的旋钮等于没有**。 顺带补齐 632–636 在 PLATFORM 迁移索引里的五行 —— 那五条迁移落地时没进索引,而索引正是下一个人判断「这个号被谁占了」的地方。 **验证**:3 条迁移用例(种进去了 / **不覆盖管理员改过的值** / 重复跑是空操作),`tests/test_alembic` 124 passed。 > **2026-09-08 — fix(assistant): 「助手进群」合并后复审 —— 十五处,其中一处是只读角色能建群并把工单指派出去(0 迁移 / 0 端点 / 0 MCP / 0 cron)** 7 个 PR 全部落地之后的一轮对抗式复审。**九处里有七处是「两个 PR 各自都对、合起来才错」的那类** —— 单 PR 自审原理上看不见它们。 🔴 **1. 只读角色能建群、并把工单指派给别人。** `POST /support/tickets/{id}/chat` 只靠 `_load_for_caller(require_owner=True)` 放行,而它的 `is_admin` 里含 **auditor 与 management** 两个只读角色;开群会 `assign`,所以一个只读角色能改变一张工单的归属。**而它的 MCP 孪生从一开始就检查了** ——「两个面对同一个问题给出不同答案」这句话我在 PR2 的 CHANGELOG 里写过,然后在同一个主题里留下了一处。已收成与 MCP 逐字相同的判据(求助人 / `can_act_on_ticket`),并补了一条「只读角色读得到详情、但开群与解散都 403」的用例。 🔴 **2. 一张被重开的工单再也拿不到群。** PR2 给 `ticket_id` 加了唯一约束(对的:一张工单最多一个房间),PR5 让房间可以被解散(也对)。合起来:工单结了 → 群解散 → 员工回来说「还有问题」→ 工单重开 → **永远回不到群里**,只能在工单页上打字,而那正是这条链路要修的东西。现在复用那一行、换上新群的 id,并**清掉上一个房间的收尾字段**(`closed_at` / `close_reason` / `card_message_id` / `escalated_at` —— 留着会让运营台把一个刚开的房间显示成「已解散」,而升级戳留着会让它永远升级不了)。 🔴 **3. SLA job 回滚之后群里仍然出现一句催办。** 群内催办的后台任务在 job 提交**之前**就被排出去(它必须那样:一次飞书往返不能待在那个事务里),所以 job 一旦回滚,处理人什么通知都没收到而群里说催过了。现在任务读**水位**(`last_agent_reminded_at`)作为那次催办唯一的凭据:没有、或者不新鲜(重放)就什么都不做。 🔴 **4. `config` 里的阈值仍然会赢过平台设置。** #3520 的原样重演 —— 我在 PR5 的迁移里把注释写对了(「不播种 config」),但 handler 里那条「显式传了就赢」的路还在。现在**填了就抛**,报错里给出该改的平台设置键,和 #3520 的修法一致。 **5. `truncated` 在刚好取到上限时是假的** —— 于是一份只覆盖后半段讨论的总结会被当成全部,而「只读了最近的一部分」那句话正是为此存在的。 **6. 话题回复被拒时那张卡整个丢了。** 话题回复是**排版**,卡片是**内容**;飞书对「在话题里回一张交互卡片」的支持不是我们能保证的事,而一次排版上的拒绝表现成「按了按钮没反应」。现在退回平铺发送。 **7. 运营台自己拼了一遍 applink** —— 两处拼同一个 URL 会漂,而漂的表现是「进群」点开一个空白页(`openId` 是单聊的形式)。 **8. 群里的限速提示被抑制了一整天。** 额度是**每小时**的,所以上午撞到上限、下午再撞到时下午那次是纯沉默 —— 而屋里的人无从知道「它为什么又不说话了」。改成按窗口(与每人那一侧一致);「开关关着」那句仍然按天(它在管理员改设置之前不会变)。 **9. `str.format` 会静默丢掉模板里没有槽位的关键字** —— #3515 的形状(一张卡承诺给出工单号,而模板里没有槽位,那句话渲染成空值,读起来完全像用上了)。`render_note` 现在反查一遍并记日志,另加一条测试断言三语模板的槽位一致(只有中文有 `{who}` 会让英文读者看到一句没有主语的话)。 🔴 **10. 收尾任务会被一墙长命房间永久饿死。** 「取最老的 50 个开着的房间,再逐个判到期」在一张长命工单(跨月的采购、等外部厂商)上永远不该动 —— 而它的 `created_at` 最老。这样的房间攒到 50 个,这个任务就**再也走不到更新的房间**,而它每天返回 `considered=50, disbanded=0`,读起来完全像「没有到期的」。500 人的公司同时开着 50 张长命工单不是极端情形。到期判断已经推进 SQL(孤儿 / 结了且过期 / 开着且长期没动静三支 OR),顺带省掉每轮 50 次必然 `continue` 的 `db.get`。 🔴 **11. 建群与解散一行审计都没有。** 这条链路上**唯一两件不可逆的事** —— 建群会出现在每个成员的会话列表里,解散会把整段聊天记录一起带走 —— 而「谁解散的那个群」原来问不出来:台账上只留一个 `close_reason`,它对「到期自动清理」和「有人手敲了一句解散」给出同一个答案。现在两件事各留一行(`assistant.room.opened` / `assistant.room.disbanded`,SAVEPOINT 隔离,删失败**不**记),并且开群与随之而来的指派共用一个 trace_id(指派那一条原来传的是空串,`AuditService` 把它换成一个随机 uuid,于是事后追「这个群是怎么来的」会看到两条互不相连的行)。 🔴 **12. 一个没绑定的人可以让机器人在群里无限说话。** 群频次闸排在身份分支**之后**,所以「你还没绑定 Helix / 发件人对不上 / 已离职」这三条路没有上限:每 @ 一次就让房间里多一条关于**某一个人**的通报,而这句话对屋里其他人没有任何意义。改成复用 `_claim_group_decline_notice`(键里带 reason,所以和「群关着」不会互相按住);单聊里照旧每次都说 —— 那里它是给当事人的指引。 **13. 一张结掉的工单还能被反复开出新群**(和第 2 条合起来的产物),而群里每一处写动作都会被终态闸拒绝 —— 那才是「按了没反应」。终态闸加在 coordinator 上(四个入口一起),拒绝里指向真实的下一步:说「还有问题」会重开工单,重开之后就能再拿到房间。同时把「为什么没开成」的 (码, 话, 状态) 收成 coordinator 上**唯一一张表** —— 它原来在 HTTP 路由里、MCP 那侧自己写了一份两分支的 if,于是同一次拒绝在两个面上是两句不同的话,而新增一个 reason 只会在其中一个面上被认出来(第 1 条那个洞是同一个形状)。补了一条反查测试:coordinator 产生的每个 `reason` 都必须在表里。 **14. 兜底升级会把已经在屋里的处理人「再拉一次」。** 「拉他等于什么都没做,而群里会多一句假的『已经升级』」这句判断在备份负责人那一支写了,在**管理员兜底**那一支漏了 —— 而小团队里 `admins[0]` 常常就是这张工单的处理人。假升级本身只是噪音,真正的代价是升级戳一落,这个房间**再也不会真的升级**。 **15. 孤儿房间的清理是唯一一种无人署名的销毁。** 「工单已经不存在了」的房间不走 `disband`(没有工单号可念,告别语也不一样),于是它删掉的那段聊天记录没有任何一行审计。补上 `audit_disband`,`actor_type=system`。 **运营台的写控件对审计员是灰的。** 这一页的**读**是审计档(global_admin + auditor),而每一处**写**在后端都另有一道 global_admin-only 的闸 —— 一颗按下去必然 403 的控件读起来像平台坏了(派生动作那条规矩在前端的同一件事)。灰着 + 一条说清为什么的横幅,三语。 **验证**:新增 22 条复审用例 + 2 条 HTTP 授权用例;**六处变异验证**(摘掉只读角色那道闸、摘掉水位校验、把到期判断退回 Python、摘掉解散审计、摘掉群内抑制、摘掉兜底升级的自指判断)各自转红。assistant/support/alembic/scheduled_jobs/mcp 全绿,前端 lint + typecheck 全绿。 > **2026-09-08 — feat(assistant): 负责人休假两周,那两周里每一次转人工都把员工关进一个不会回话的房间 —— 备份负责人 + 群内 SLA 催办与升级(迁移 635 = 两列 / 0 端点 / 0 MCP / 0 cron)** 「助手进群」主题 PR7,主题收官。 🔴 **转人工的价值上限是「快」,而它有一个一直没人管的失败模式**:主负责人休假两周,那两周里每一次「转人工」都会把员工和一个**不会回话的人**关进一个房间。那比降级成只建工单更糟 —— 因为员工会**以为**有人在看,于是他既不会去催,也不会另找路子。 **所以拉人之前先问一句「他今天在吗」**(`owner_reach`):主负责人今天没有在批准中的休假、并且有企业邮箱 → 拉他;否则拉路由表上的**备份负责人**;两个都不行才降级。三处刻意的判断: - **休假判据与对外可用性接口逐字同源**(`APPROVED / PENDING / PENDING_CANCELLATION` + NULL 保守算「不在」)。两处不一致的后果很具体:对外接口说某人休假中,而 Helix 照样把他拉进群等他回话。有一条测试直接断言两个常量集合相等。 - 🔴 **查不到休假记录 = 在。** 休假数据来自 HRIS 同步,可能压根是空的(同步没跑、这个人不在推送人群里)—— 一个同步故障不该让所有转人工都降级到备份负责人。 - **没有备份时仍然拉主负责人**,而不是降级:一个休假中的负责人好过一个空房间(他回来会看到,而员工至少在正确的房间里);降级的产物只有一个工单号。开场白里会加一句「负责人今天休假,可能回复得慢一些」—— 员工看到一个陌生名字会以为拉错了人,而备份自己也需要知道他是被顶上来的。 **群里的 SLA 催办**:`support.ticket_sla_reminder` 每次给处理人发催办卡时,**群里也说一句**。理由很实在:催办卡片只发给处理人一个人,而这件事的另一方(求助人)就在同一个房间里等着 —— 一条只有处理人看见的催办,对员工而言与「没人管」没有区别,而他会另开一张工单。 🔴 **刻意不新建一套催办阶梯。** 复用那个 job 已有的水位与冷却(`last_agent_reminded_at` / `agent_reminder_count` / `cooldown_hours`):「多久算超时」只该有一处定义,而这类数只能拉长不能收紧 —— 两套一定会漂,且漂的方向是「催得更频繁」。 **催到第 N 轮还没动就升级**(`assistant.room_escalate_after_reminders`,默认 3):把**备份负责人**(退到 IT 管理员)拉进房间,并说清为什么。两条约束:**只发生一次**(`escalated_at` 一列 —— 没有它,每一次催办都会再拉一次人,一个房间会慢慢变成整个 IT 团队),以及**不自动改派**(升级要的是多一双眼睛;自动改派会让原处理人以为这件事不再是他的,那正是催办想避免的结果)。备份就是当前处理人时整件事是空操作 —— 而不是在群里多一句假的「已经升级」。 **验证**:新增 24 条用例 + 3 条迁移用例;**四处变异验证**(NULL 休假状态不再算「不在」、离职负责人照样被拉、升级不看 `escalated_at`、升级不检查「备份就是处理人」)各自转红。 **「助手进群」主题至此 7 个 PR 全部落地**:群通道 → 工单群与群内动作 → 总结与交接 → 闭环 → 生命周期 → 运营台 → 负责人兜底。 > **2026-09-08 — feat(assistant): 「转人工与工单群」有了运营台 —— 四个数、一张清单、一个不可恢复性的告警(0 迁移 / +1 端点 / +1 MCP → 629)** 「助手进群」主题 PR6。`/admin/assistant-handoff` 此前是一张裸路由表 + 一段「最近转人工」的流水,配不上这条链路的重要度:它回答不了「这件事成色如何」,更回答不了「现在该动哪个房间」。 **这一页现在回答四个问题,而且顺序是刻意的**(概览 → 房间 → 路由 = 有没有问题 → 哪一个 → 根因在哪): 1. **转人工在把人拉进来吗** —— 近 30 天转了多少次、其中多少次真的拉起了群(比例**在服务端算一次**,两个面共用一个数;而它会被拿去和上周比)、剩下的为什么走了降级。 2. **模型分得准吗** —— 每一类判中多少次、平均置信度,直接长在路由表的行上:改 hint 的人当场看得到这一类的历史成色。 3. **这些房间现在什么样** —— 开着多少、多少超过 14 天没动静(**和收尾任务用同一个阈值**,否则页面标红的和任务实际去问的不是同一批)、多少在等收尾(**和默认视角的筛选是同一个谓词** —— 点开「等收尾 3」看到 5 行,是让人不再相信一个页面的最快方式)。 4. 🔴 **过程留下来了吗** —— 「开着的房间里,讨论还没落到工单上」的数量。群一解散聊天记录就没了,所以这是这一页**唯一关于可恢复性**的数;它因此不是表里一枚安静的图标,而是一个会变红的数字。它只数**还开着**的房间:已经解散的那些数它没有意义(木已成舟),而混进来会让这个告警永远下不去 —— 一个下不去的告警很快就没人看了。 **房间清单一行给出全部处境**:工单号+状态、求助人/处理人、群状态+来源(转人工/求助人开的/处理人开的)+停滞天数、有没有过程记录,然后是进群 / 看工单 / 解散。解散按钮**只在工单已结且群还开着时出现**(后端也只在那时放行),而「还没有记录」的行在二次确认里会额外警告一次 —— 那正是人在这一刻会犹豫的原因。 **一次请求一个快照**:概览和清单在同一个响应里。分成两个请求的话,「共 40 个群」和下面 37 行来自两个时刻,读的人会以为丢了三行。 **验证**:新增 15 条读模型用例;**四处变异验证**(把「只数开着的」放宽、空窗口报 0% 而不是「没有数」、降级分布与分类统计各自漏掉窗口)各自转红。⚠️ 后两处第一次是绿的 —— 我的窗口用例只断言了 `handoffs` 一个数,而窗口是**三条查询**各自带的;补齐之后才钉住。前端 1426 条 vitest + lint 全绿,其中 **statusColor 守卫抓到我手搓了一张状态→颜色表**(平台已有唯一一张,两份会漂:同一个 `in_progress` 在两页上是两个颜色,读的人会以为它们是两种状态),已改为复用 `statusColor()`。 > **2026-09-08 — feat(assistant): 工单群会自己收尾了 —— 结了的解散、没人管的问一句,而记录绝不跟着房间一起消失(迁移 634 = 一行 cron + 两个设置 / +1 端点 / +1 MCP → 628)** 「助手进群」主题 PR5,主题至此收官。 **为什么需要它**:群是**不可撤销地**建出来的,而且会一直留在每个成员的会话列表里。工单结了之后那个房间就只是噪音 —— 但没有人会想起来去删它。第一批工单群上线一周后,负责人的飞书里就会有一排「IT 求助 · …」,其中大多数早就结束了。 **新 cron `assistant.ticket_chat_sweep`(每天 03:20)做两件事,两种温度:** - **结了的群 → 解散**(保留 `assistant.ticket_chat_retention_days`,默认 7 天,0=永不)。 - **没人管的群 → 问一句**(`assistant.ticket_chat_idle_nudge_days`,默认 14 天,0=不问)。刻意**不自动关单**:自动关掉一张还开着的工单,会让「已关闭」这个状态不再代表任何东西。所以只问一句,并给出一条出路(「解决了 …」),并且问过就算一次活动 —— 否则每天都会再问一遍。 🔴 **删之前工单上必须有过程记录。** 房间的聊天记录跟着解散一起消失,而那段过程是这条链路最值钱的产物(交接、知识库语料、复盘都读它)。所以解散前先补一段小结;**模型不可用时留着房间** —— 记录比房间干净重要,而写一段占位小结是这条链路上最坏的失败。这一格单独计数(`kept_for_record`):它和「没到期」长得一样(都是 `disbanded == 0`),而原因完全不同 —— 合在一起就再也看不出「这个任务其实什么都没干成」。 🔴 **删失败绝不标成已删。** 那会让台账说「群没了」而群还在,于是没有任何一条路径会再去清它。单个房间失败不算这次运行失败(下一次重试);**全部都失败才抛** —— 那不是抖动,是权限没了或凭据坏了,而一个安静地每天什么都做不成的清理任务比没有这个任务更糟。 **三个入口手动解散**:群里说「解散群」(工单终态是硬闸,而且这一闸排在授权之前 —— 对一件还没有结论的事说「你没权限」是误导)、门户/后台工单详情的按钮(带二次确认,只在终态出现)、MCP `disband_ticket_chat`。 🔴 **`disband_ticket_chat` 进了 `derived_actions.OPT_OUT`。** 不可逆动作不上聊天卡片面 —— 这条规矩本仓早就写着,而「一句话触发的不可逆」和「确认一下参数」不是同一类风险:点错的代价是一段再也找不回来的过程记录。 **机器人被移出群** 现在会把台账行落成 `closed`(PR1 只记了审计):往一个已经把机器人踢出去的房间发消息只会失败,而失败原因读起来像飞书故障 —— 这件事必须落成状态,不能留给下一次调用去发现。 **cron 行刻意不带 `config`。** 2026-09-08 刚踩过反过来的那一半(#3520):播种进 `scheduled_jobs.config` 的一把钥匙赢过了平台设置,于是设置页上的改动被静默无视一周。这一行两个阈值只从平台设置读,迁移测试里有一条断言直接钉住「config 必须为空」。 **验证**:新增 18 条生命周期用例 + 5 条迁移用例;assistant/support/alembic/scheduled_jobs 共 1808 条全绿。⚠️ **既有的「API 进程必须注册 worker 的每一个 handler」那道闸抓到我漏了一处** —— 新 handler 只加进了 `worker.py`,而手动触发按钮跑在 API 进程里,少这一行的表现是「Handler 未注册」而错误信息指向一个不存在的重命名。这正是那道闸 2026-08-28 建立的原因;**三处变异验证**(不看 `_ensure_record` 的返回值就删、删失败仍标已删、去掉终态闸)各自转红。⚠️ 写这一版时**第一次跑就抓到自己的一个真 bug**:`_ensure_record` 原本返回 `None`,于是「模型不可用」这条路上房间照样被删了 —— 而那正是这个 PR 最想守住的东西。 > **2026-09-08 — feat(assistant): 工单群里能把事情收掉了 —— 解决、确认关单、重开、评价,四步都在房间里(0 迁移 / 0 新端点 / 0 新 MCP / 0 cron)** 「助手进群」主题 PR4。一个只能开始不能结束的房间,产出的是一堆永远「处理中」的工单和一屋子等着的人。 **处理人的主路径是打字**:`解决了 <怎么解决的>` —— 那一句直接成为工单的结案说明。处理人自己写的一句话永远比 AI 整理的更准,而它同时是这条链路上最有价值的知识语料(下一个遇到同样问题的人拿到的就是它)。说明取的是**原文**而不是归一化后的字符串:大小写、错误码、专有名词都是它的一部分。光说「解决了」不够 —— 空的结案说明等于没有结案说明,助手会直接说「那一句会成为这张工单的结案说明」。 **按钮那条路先给人看一眼。** 「我弄完了」→ 读一遍群 → 整理一段结案说明 → **发在群里等确认**,而不是直接结案。那段字会成为工单上的正式记录,而一段没人读过就写上去的说明会被下一个人当成事实。确认时校验**哈希**:「你确认的」必须和「写进去的」是同一段 —— 助手确认卡为这件事立过同一条规矩,这里照办。群里没有可整理的讨论时如实说「你自己写一句」,而不是拿一句「已解决」凑数。 🔴 **「问题解决了」只有求助人能按。** 这两颗按钮(确认关单 / 还有问题)的授权判据**不是**「处理人」,而是「这是你的工单」—— 处理人替他按第一颗,等于自己给自己发合格证,而工单的满意度和「真的解决了吗」这两个数从此都不可信。IT 管理员放行(后台一直如此)。 **三档满意度发在群里**,只有求助人本人能评,口径与飞书服务台对齐(1/2/3),`via='feishu_group'`。评过之后那张卡**重画成回执** —— 只剩三颗按钮的卡片会让人以为可以再评一次。在**群外**结案(后台点了「解决」)时,群里也会收到这张卡:员工就在这个房间里,而那是这段处理的收尾。 **卡片按钮改成一台状态机,最多三颗。** 四颗在手机上会折行(前三颗挤一行、第四颗孤零零掉下去,2026-09-07 的真机截图)。未认领 → 我来处理 / 标为高优先级;有人处理 → 我弄完了 / 标为高优先级;已解决或等回复 → 问题解决了 / 还有问题;已关闭或已撤回 → 只剩刷新。⚠️ **`resolved` 不是终态** —— 那时候正需要求助人说一句。 🔴 **慢的那一下不能把群里那张卡换掉。** 飞书把回调的返回当成这条消息的新内容,而超预算时 `handle_card_action` 返回的是 `handoff.in_flight`,不发布它就会拿一张通用的「正在处理」卡替换掉群里唯一能看到工单状态的东西。所以每一次工单卡点击都在任何慢活(读群、跑模型)之前先把**当前这张卡**发布成 in-flight。顺带给 follow-up 加了一条抑制:群里的点击不再往操作者私聊补一整张工单卡。 **验证**:新增 19 条用例;assistant/support/notifications 全绿;**四处变异验证** —— 哈希校验、求助人闸(关单)、求助人闸(评价)、in-flight 发布,各自转红。⚠️ 其中**两处第一次做变异时是绿的**,暴露的是我自己的两个测试写弱了:哈希那条测的是「压根没有说明」(走的是另一个分支),慢点击那条挑的按钮会在到达慢活之前就短路返回。补强之后才真的钉住 —— **变异验证的价值正在这里:它测的是测试,而不是代码。** > **2026-09-08 — feat(assistant): 群里的讨论终于会落到工单上 —— 「总结」读一次房间、写一段结构化记录,「交接」把三件事收成一条命令(0 迁移 / 0 新端点 / 0 新 MCP / 0 cron)** 「助手进群」主题 PR3。 **问题**:工单群里发生的才是真正的处理过程 —— 问题怎么被复现的、试过什么、卡在哪、最后是什么解决的。而工单上只有最初那句提问和最后一句「已解决」。中间那段是这条链路上信息密度最高的部分,却只存在于一个迟早会被解散的房间里。于是三处同时受损:**交接的人要从头问一遍、知识库拿不到「这类问题怎么修」的语料、复盘时没有任何过程可看。** **`总结`** 读一次群 → 四栏结构化小结(问题 / 已经做了 / 待办 / 结论)→ 发在群里,**并逐字写进工单时间线**。一份文本两处用:两个版本的小结会让「群里说的」和「台账上写的」对不上,而那正是台账存在的意义。 **`交接给 @某人`** = 总结 + 转派 + 拉人,一条命令。分开做的结果是常有人只做了其中一件(通常是只改了 assignee),而接手的人拿到一张没有过程、也进不去现场的工单。总结做不成也照样交接,但会说清少了什么 —— 别让接手的人以为工单上有一段他还没读的过程记录。 🔴 **「被叫到才读」是产品性质,不是优化。** 助手不订阅群里的消息;`总结` 是**唯一**会触发读取历史的路径,而每次读取自己落一行审计(哪个房间、多少条、谁让读的),**正文不进审计**。一个默默记录它看得见的一切的机器人,和一个被叫到才应答的机器人,不是同一个东西 —— 而员工能不能分辨这两者,决定了他们在群里说不说真话。机器人自己说过的话也**不进总结的输入**:那是这段讨论的产物,让模型把自己的旧话当成事实来源是最典型的自我强化。 🔴 **模型不可用时什么都不写。** 一段编出来的「已尝试重启网关」比没有总结更糟:它会被下一个人当成事实,而没有人会回头去核。提示词里最强的一条也是这个 —— 「只写记录里出现过的信息,没提到的写未提及」。 **新的消息种类 `note`,而不是复用 `system`。** 两处考虑:① `add_reply` 会把状态推到「等你回复」并暂停 SLA —— 用它写小结会让一张正在被处理的工单突然显示成等员工,所以新增 `SupportService.add_note`(不改状态、不动 SLA);② `system` 在前端是**一句居中的小灰字**,一份六行的结构化小结用那个样式渲染是读不了的 —— 所以时间线上多了一种「记录」块:左对齐、保留换行、留出行距。消息**怎么被读**是它是什么的一部分。 **踩到并修掉一个具体的坑**:`chat.created_at` 是 server_default 列,行在本 session 里 insert 时它从未被取回过,一读就是一次惰性 IO —— 异步路径上直接 `MissingGreenlet`。而这个 `since` 参数**本来就不需要**:一个 Helix 为这张工单开的房间,它的全部历史就是这张工单的讨论。 **验证**:新增 16 条用例(读群 / 总结 / 交接 / 审计 / 渲染);**三处变异验证** —— 模型不可用时改成写占位小结、不再剔除机器人自己的话、去掉交接的授权闸,各自转红。⚠️ 有一条用例专门盯「**被拒的命令不该顺手读一遍群历史**」:授权闸放在读取之前,否则一次被拒的操作仍然完成了一次读取。 > **2026-09-08 — feat(assistant): 工单群成了工单的第二个面 —— 群里能认领、转派、拉人、改优先级,而处理人终于动得了自己名下的工单(迁移 633 / +1 端点 / +1 MCP → 627 / 0 cron)** 「助手进群」主题 PR2。PR1 让助手在群里说得了话,这一版让**群里的话能推进这件事**。 🔴 **先修掉一个一直在的洞:「转人工」拉了人,却没把工单交给他。** 群拉起来了、负责人在里面聊着,而工单在队列里仍然「无人认领」—— SLA 的首次响应永远不会被记上,看板上它是一条没人管的记录,而实际上有人正在处理它。**把人拉进房间和把活交给他,必须是同一个动作。** **新表 `assistant_ticket_chats` 是「工单 ↔ 群」的唯一注册表。** 为什么不是 `assistant_handoffs` 上的一列:后者记的是**一次事件**(某条回复被转人工了,模型判成什么类、拉没拉起群),写完不再变;而群是一个**有生命周期的对象**(加人、挂着一张要原地刷新的卡、结案后会解散),而且它不再只从「转人工」来 —— 求助人能在工单详情页开一个,处理人能在后台开一个。塞进 handoff 行就得先造一个「没有 message_id 的 handoff」,那是一句谎话。`ticket_id` 与 `feishu_chat_id` 双唯一:一张工单最多一个房间(建群不可撤销,两个讲同一件事的房间会让人各说各话),一个房间也不可能是两张工单的。**历史的转人工群整批回填** —— 不搬的话它们从这一版起会掉进「任意群」那条默认关着的闸,屋里的人第二天开始得不到任何回应。 **群里那张工单卡就是这张工单。** 编号 / 状态 / 处理人 / 优先级,加「我来处理 · 标为高优先级 · 刷新」三颗按钮,走平台自己的卡片渲染器(状态决定头色/徽章/图标)。工单在**任何地方**变了状态(后台、门户、MCP、群里),这张卡原地重画 + 群里留一句话 —— 卡片说「它现在是什么状态」,那句话说「刚刚发生了什么」,两者不能互相替代。终态的卡上不留那两颗会被拒的按钮:一颗按了必然被拒的按钮读起来像平台坏了,而不像这件事已经结束了。 **群里的命令走字面匹配,不交给模型**:`状态` / `认领` / `转给 @某人` / `拉 @某人 进来` / `优先级 高|紧急|普通|低` / `帮助`。理由和「新话题」「转人工」是同一条:一个把「转给张三」理解成「给张三发条消息」的模型,代价是一张工单挂在错的人名下,而没有人会立刻发现。**被 @ 的人取自验签过的 `open_id`,不取自正文那三个字**;认不出登录身份就用通讯录把 open_id 换成邮箱再找人。认不出来的句子照常交给模型 —— 命令是快捷方式,不是围墙。 🔴 **RBAC 变化:`assignee` = 这张工单的处理人。** 后台六个动作(认领/转派/改属性/回复/解决/重开)此前门在 `global_admin` 上,而转人工指派的路由负责人往往不是 —— 群里那些按钮对他全都是按了就被拒。判据收成支持域里的**一个函数** `can_act_on_ticket`(管理员 or assignee),HTTP、群命令、卡片按钮、MCP 四个面共用它;两个面对「谁能动这张工单」给出不同答案,是这类改动最容易留下的洞。**读面没有跟着放宽**(队列仍是管理员的),只有工单详情跟着放宽 —— 能动手就该看得见。求助人**不在**这一档:一个能改自己工单优先级和处理人的求助人,会让优先级这个字段失去意义。 **三个面都能开群**:门户工单详情、后台工单页(同一个页面组件)、以及 MCP `open_ticket_chat`(627)。它们走同一个 coordinator —— 三份拷贝会各自漂:一份忘了指派、一份忘了发卡、一份忘了记台账。求助人开群而工单还没人认领时,对面取**兜底路由的负责人**(「没分类的 IT 事情找谁」的既有答案),而不是随便挑一个管理员。拉不到第二个人就**不建群**并说明原因:只有一个人的群比没有群更糟。 **状态同步只排后台任务,并且重读。** 诱惑是在改状态那一刻顺手发一条飞书请求 —— 那把一次外部往返放进了还没提交的事务里(本仓为此吃过 2013),而且调用方一旦回滚,群里就挂着一张描述从未发生过的事的卡。任务自己开 session、重新读工单当前的样子再重画:一次失败的刷新只是慢一步。 **验证**:新增 24 条工单群用例 + 6 条授权用例 + 3 条迁移回填用例;既有 handoff 用例迁到真工单后全绿(**两条老用例当场抓到我的两处回归**:转发失败不再贴回答、群名丢了类别 —— 老用例挑的例子正是新逻辑的反例)。**三处变异验证**:`can_act_on_ticket` 恒真 → 授权用例红;摘掉 handoff 的指派 → 新用例红;摘掉 coordinator 的指派 → 开群用例红。⚠️ 第一次摘 handoff 指派时整个工单群套件**全绿** —— 那正是「这条路径没被覆盖」的信号,补完用例才红。 > **2026-09-08 — feat(assistant): 助手终于在群里说话了 —— 「转人工」把人拉进房间,机器人却在里面装哑巴(迁移 632 / 0 新 MCP / 0 API 契约)** 生产现场:Helix 为「转人工」建了群「IT 求助 · 云 · 冯帅」,把员工和负责人拉了进去,员工在群里 @ 机器人问「看一下群里的聊天 然后总结一下什么问题」和「解决完了 关了工单和解散群吧」—— **两句都石沉大海**。 **根因不是权限。** `im:chat`(建群/加人/转发/解散,2026-09-07 实测五个动作全 code 0)和 `im:message` 都在。是 `parse_message_event` 的第一屏就写着 `if chat_type != "p2p": return None` —— 群消息被认领、ACK、然后丢掉,连一行审计都不留。所以现象是「已读不回」,而任何一处日志都查不到它。 **这一版把群做成通道的一等公民,而不是单聊的一个特例。** **「这句话是在跟我说吗」只有一个可靠答案:我被 @ 了。** 判据刻意**不是**「飞书把消息投给了我们」—— 那取决于应用当前持有哪些权限,而权限会变;一个今天成立的推断,明天多开一个 scope 就变成「机器人开始回答它偷听到的每一句话」。`GET /bot/v3/info` 拿到本应用的 bot `open_id`(Redis 缓存 1h),与 `event.message.mentions[].id.open_id` 比对。身份接口抖了就降级成「有任何 @ 就应答」——**没有任何 @ 仍然不处理**,那条线不因降级而移动。 **答复回到问的那个房间。** 新增 `channel.ReplyTarget` 值对象取代散在各处的 `open_id=`:入口处解析一次,十来个发送点(答案、限速提示、「我还在处理你上一条」、不支持的消息形状)全部指向同一个目标。两个 kwargs 的写法把这件事的正确性摊到每个调用点,漏一处就是「群里的问题被私聊回答了」——在群里看起来仍然是死的。工单群平铺发,任意群走**话题回复**(`reply_in_thread`),否则一屋子人看到的是一堆没有上文的答复。 **群里不念私事。** 系统提示词追加一段群守则(`extra_system`,不是第二套提示词 —— 群里和私聊必须是同一个助手,只是多知道「有旁人在听」);确认卡与个人记录一律私聊,群里只留一句「已私信」。三处刻意的收口:`assistant:active_chat` 不被群发言改写(否则员工点「新话题」清掉的是别人也在的那段),裸资产号的回购捷径群里不触发(它的前提是「刚才我私下给过你这个号」),在工单群里打「转人工」回一句「这个群就是转人工的结果」而**不建第二张工单**。 **两个开关 + 一个额度,都种进 `platform_settings` 才算数。** 工单群默认**开**(平台把两个人拉进房间然后自己装哑巴,是最难解释的行为),任意群默认**关**(多一个群能 @ 它就是多一片触达面,该由管理员显式打开),`assistant.group_turns_per_hour` 默认 120 —— 十个人在一个群里各问六句,每人都没超,群超了。设置页列的就是这张表,**不种行就等于没有开关**:管理员只能靠读文档知道它存在。迁移幂等,已存在的行不覆盖(一次发布把管理员的决定改回默认值,是这类种子最典型的伤害)。 **`assistant_conversations.chat_kind`** —— `dm` / `handoff` / `group`。为什么不能靠 join 推:工单群的 `chat_id` 在 handoff 表里查得到,但**任意群压根不在任何表里**,于是它和私聊在数据上长得一模一样;而一句私聊的回答只有一个人看见,一句群里的回答有一屋子人看见。同一个值也进审计 `detail.group_kind`,两处取自同一组常量而不是长得一样的字面量。 还认领了 `im.chat.member.bot.added_v1` / `deleted_v1`:进群时自我介绍(该应答的群才发 —— 开关关着还自我介绍等于承诺一件做不到的事),被移出时记一行 `assistant.chat.membership`,因为群没了之后每一次往它发消息都会失败,而失败原因读起来像飞书故障。 **验证**:新增 28 条群通道用例;既有 543 条助手用例全绿;**三处变异验证**——把「没有 @ 就不处理」改成放行、把 `@_user_1` 的剥离改成 no-op、把 active_chat 的单聊守卫拿掉,各自钉住的用例立刻转红。⚠️ 期间自己撞了自己一次:两个 pytest 会话用了同一个 `PYTEST_XDIST_WORKER`,产出 116 个 setup ERROR + 死锁 —— 与断言失败长得完全不同,是库撞车的形状。 > **2026-09-08 — fix(github-org): 坐席阈值设成 1,周报却按 10 报了余 4 的组织 —— 播种进 cron config 的那把钥匙赢过了平台设置(迁移 631 = 一行纯数据 / 0 新 MCP / 0 API 契约)** 生产实测:`github_org.governance_digest` 今天 09:30 **首播**,发出的唯一一条待办是 `pingcap-inc` 余 **4** 个坐席。而平台设置 `github_org.seat_warn_threshold` 从 2026-09-01 起就是 **1** —— 界面上的待办清单按 1 算,这个组织根本不在里面。**同一个问题两个答案,而设置页那一侧是被无视的那个。** **根因是取证出来的**(生产 TiDB 只读):`platform_settings` 里 `github_org.seat_warn_threshold = '1'`(2026-09-01 12:55),而 `scheduled_jobs` 里那一行的 `config` 仍是 `{"seat_warn_threshold": 10}`,`last_run_at = 2026-09-08 01:30 UTC`、`run_count = 1`。两条改动隔了一周,谁都没和对方对上:583 号迁移播种这一行时把 10 写进了 config(当时那是唯一能调它的地方);#3391 把阈值抬成平台设置、优先级定成「调用方显式传的 > 平台设置 > 代码默认」,**但没有取走已经播下去的那份 config** —— 而 handler 正是把 config 当「调用方显式传的」用。所以 #3391 的 CHANGELOG 里那句「下周一那封摘要按现状不会发出」,在生产上是反的。 🔴 **#3391 修的正是这个坑的镜像,而它给自己留的那把「临时排查」钥匙,唯一一次真实生效就是错的。** 所以这次不是把种子改掉了事,而是把这条路关掉:迁移 631 从那一行的 `config` 里删掉这个键(其余键原样保留,幂等,坏 JSON 跳过不动),handler 里**填了就抛**,报错文案直接给出该改的地方。刻意不是「安静忽略」—— 一个被安静忽略的 config 键,表现同样是「我改了配置但行为没变」,只能靠读源码发现;抛出去会立刻触发平台的失败通知。之后阈值只有一个来源。 ⚠️ **既有的同族测试原理上看不见这个。** `test_the_ui_and_the_digest_read_the_same_threshold` 比的是 `collect_action_items` 与 `build_digest` —— 两个消费者拿到的是**同一个输入**;真正给出第二个答案的是 **handler**,而没有任何用例走过 handler。所以新用例从 handler 进(平台设置 1 + 组织余 4 ⇒ `skipped == "no_action_items"`;config 里带这个键 ⇒ `ValueError`)。**一致性测试要从「输入被组装的地方」进,不是从两个消费者之间进。** **验证**:`tests/test_github_org/test_governance.py` 24 → 25 条全绿;变异验证 —— 把 handler 恢复成读 config 的旧写法,新用例立刻转红。迁移在本地 `helix` 库上真跑过一次(628 → 631),那一行的 config 由 `{"seat_warn_threshold": 10}` 变成 `{}`。 > **2026-09-08 — fix(assistant): 「380838443567 这个云账号谁负责」答的是审批流程的负责人 —— 编号先落到行上(迁移 630 = 一行 cron / 0 新 MCP / 0 API 契约)** 生产实测(2026-09-07):员工给了一个**真实存在**的云账号号码(发布后取证:12 位 AWS 账号 id,`pingcap-dbaas`,prod,53 名成员,负责人李卓然 —— 当天我在这条记录里写成了「阿里云账号」,是错的),助手回答的是两条**审批流程**的负责人 ——「开通云账号(项目)申请」和「AWS/GCP/Azure/Alibaba Production SSO Permission Application」,并注明「平台根据审批记录推断」。 **根因是取证出来的,不是推的。** 那句「(平台根据审批记录推断,尚未本人确认)」只由 `flow_grounding.py:167` 拼出,全代码库别处没有 ⇒ 那段回答确定来自审批流程接地块。链路:「谁负责」是 `flow_grounding._ASK_PATTERNS` 的字面分支 → 60 条审批流程进了这一轮 prompt → 模型从一份名字里带「云账号」的现成清单里挑了两条,**压根没查那个号码**。而能查:`list_cloud_scopes.search` 的谓词是 `display_name.ilike OR external_id.ilike`,`external_id` 就是账号号码。 ⚠️ 与 #3512 是**两种不同的形状**,不要混:#3512 修的是「调了 `list_cloud_scopes` 但不传 `search`,然后声称没有找到」;这一次它一次工具都没调。 **修法:`app/assistant/identifier_grounding.py` —— 服务端自己把编号查成行。** 和 `flow_grounding` 的模块头是同一条道理:**system prompt 是请求,不是保证**。「问题里有编号请先按编号查」这句话,模型在手边已有一份看起来很像答案的清单时就是会不照做。而编号判得准,所以服务端抽出来、自己查掉、把行摆进 prompt —— 对的那一行已经在它眼前,没有「挑一个错答案」的余地。 覆盖五类编号:云账号 / 订阅 / 项目 id(纯数字 ≥9 位、UUID)、云资源 id(`i-` / `vpc-` / `sg-` … 前缀白名单)、IPv4、域名、资产序列号。日期(8 位)、邮箱、普通词都不触发查询。 🔴 **RBAC 不写第二遍。** 查询一律通过新的 `mcp_bridge.call_readonly_tool()` 以**提问者本人**的身份跑真实只读 MCP 工具,而不是在接地里写 SQL —— 每道门都已经在工具体内(非云读角色只看得到自己拥有或参与的 scope)。抄一遍谓词就是给自己开一条**静默正确**的越权读路径。也刻意**没有**「行存在但你看不见」这类提示:那本身就在泄露存在性;看不见 = 查不到,照旧走转人工/工单。 **查到行就撤掉审批流程清单。** 那正是错答的成因:两份都像答案的材料摆在同一轮里,等于让模型再猜一次。「这个账号谁负责」和「开通这类账号走哪条流程」是两个问题。查不到时**什么都不加**,行为与改动前逐字一致(护栏用例:「开通云账号要走什么流程」必须仍然拿到流程清单)。 ⚠️ **原本这个 PR 也修了 #3512 带进来的「自限定工具拿到零行」那处回归,但并行会话的 #3518 先落地了,而且做得更彻底**(判据是 `_accepts_narrowing(schema)`,还顺带把重试建议改成按 schema 生成)。所以合并时**采用了 #3518 的实现,撤掉了我这一版**;这里只保留 `mcp_bridge.call_readonly_tool()` 这一处新增。两边同一天独立撞上同一处红,说明的是同一件事:**本仓 PR 上零 check、`go-ci` 不跑 pytest**,一条红能一直红着。 **验证**:24 条新用例(含成对的 RBAC 闸:普通员工查不到 / 这个账号的负责人查得到);变异全部转红(去掉流程清单抑制 / 抑制改回「一律撤」/ 去掉 `truncated` 守卫 / 数字下界 9→8 / 命中总数只报展开行数 / 去掉键名优先 / 摘掉评测确定性判据 / 把新用例挂进已存在套件 / cron 的 `config.suite` 写成 `regression`)。 **发现一个要解决一类 —— 评测台加了第三个套件 `object_lookup`「对象定位」(6 条,新增类别 `CAT_OBJECT_LOOKUP`)。** 题库里此前没有任何一条「员工点名一个具体对象」的用例,而这一类的失败方式独一无二:**回答看起来完全合理,只是说的是另一个东西**,评委很容易放过。所以这一套带**确定性**判据 —— 「尚未本人确认」/「平台根据审批记录推断」只由 `flow_grounding` 拼出,出现在一条「某对象归谁」的回答里就等于发生了替换,`must_not_mention` 直接判红,不依赖任何一行具体数据存在。事故原句原样入库(改写它就丢掉了这条回归证据:「谁负责」是 `_ASK_PATTERNS` 的字面分支)。 🔴 **而一个套件只是 `active` 还不会跑 —— 所以同 PR 加了迁移 630 的那一行 cron**(周一 04:40 上海,排在回归评测 03:30 之后:两跑占用员工同一个模型后端)。每周那道 `assistant.eval_regression` 任务只跑 `config["suite"]` **一个**套件,默认 `regression`。少了这一行,新加的 6 条用例是一套**永远不会亮红灯的闸**,而那比没有更糟:它会让人以为这一类已经守住了。实现是**第二行 cron + 同一个 `handler_key`**(`scheduled_jobs` 把 `name` 与 `handler_key` 分两列正是为此),零行新代码;已核对 `previous_terminal_run` 的基线带 `suite_id` 约束、告警的 `related_resource_id` 是 run.id,两个套件不会互相串味或互相去重。 ⚠️ **为什么是新套件而不是往回归套件追加**:`seed_builtin_suites` 对**已存在**套件追加的用例一律落 `draft`(刻意的 —— 悄悄变宽的闸会移动部署自己的基线),而 draft 不跑。新套件首播全部 `active`,当天就真的在跑。第 6 条是护栏(「开通云账号要走什么流程」——句中无编号,流程清单正是答案),把抑制写宽就红。 ⚠️ **自审改掉了抑制的第一版写法**(它是「查到行就一律撤掉流程清单」):「380838443567 这个云账号怎么申请权限」问的是**两件事** —— 那一行是「哪个账号」的答案,流程清单是「怎么申请」的答案,一律撤等于把员工真正问的那一半扔了。现在 `flow_grounding` 的问句词表拆成 `_PROCESS_ALTERNATIVES` / `_IDENTIFICATION_ALTERNATIVES` 两组、并集**算出来**(两条手写长正则一定会漂移),只有**纯认领**问句才撤。 **顺带补齐一处取证面**:编号预检索跑过的工具名现在会出现在这一轮的 `tool_calls` 里(与 `kb_prefetched` 同一个道理)—— 否则管理员看到的是一条报出了账号负责人、却没有任何来源的回答,读起来像凭空编的。 > **2026-09-08 — fix(assistant): 超限拒绝对「没有筛选参数的工具」是死胡同 —— 判据从「这次传了什么」改成「这个工具能收窄吗」(0 迁移 / 0 cron / 0 新 MCP / 0 API 契约)** `test_an_oversized_result_is_marked_partial_not_silently_sliced` 在 `main` 上是**红的**(在 2bc131e52 复现,单跑也红,不是顺序污染)。这条红不会有人被动发现:本仓 PR 上零 check,`go-ci` 是 post-merge 且**不跑 pytest**,所以它能一直红着。 先判方向:红的是**测试**还是**代码**?查 `git log -S` 定位到 #3512(2026-09-07)—— 它给桥层加了「没给收窄条件的超限调用返回零行」,带生产取证和完整推理,是**有意的契约变更**;那条老用例断言的是变更前的「部分结果 + 警告」。所以老用例编码的是旧契约。**但它挑的工具恰好证明了 #3512 漏掉的另一半**:`list_my_assets` 的真实 schema 只有 `page` / `page_size`。 🔴 **对这类工具,拒绝是一条走不通的指令。** `oversized_refusal()` 的 hint 说「请带上收窄参数重试 —— 通常是 `search=…`」,而这个工具的 schema 里没有那个键:模型照做只换来一条 `invalid_arguments`,第二次仍然零行,而 hint 又明令禁止说「没有找到」。员工问自己的设备,结果既没有数据、也不许给结论。**实测这不是个别情况:只读目录 360 个工具里 118 个是这个形状**(每一个 `get_my_*` / `list_my_*` —— 它们本来就按调用者收窄,没有第二个维度可给)。 所以两边都改。**代码**:新增 `_accepts_narrowing(schema)`,判据取**工具自己的 schema**(`BridgedTool.schema`,而不是本次传参),只有「工具能被收窄 **且** 一个收窄条件都没给」才返回零行拒绝 —— #3512 要挡的 `list_cloud_scopes`(有 `search`)照挡,`list_my_assets` 回到「部分结果 + 警告」。顺带把部分结果里的重试建议也按 schema 分成三句(`_retry_advice`):可筛的说筛,只能翻页的说翻页,**一个入参都没有的(如 `whoami`)只能说「剩下的取不回来,当未知,别当不存在」** —— 原来那句固定文案同样以「a search term」开头,是同一个缺陷换了个措辞。**测试**:老用例按真实契约拆成三格(不可收窄 → 部分结果 / 可收窄且没给 → 零行 / 给了 `search` 仍超限 → 部分结果),两条断言用**生产真实 schema** 而不是替身自带的形状,并各带一句「前提变了就重写这格」的护栏。 **验证**:`tests/test_assistant/test_mcp_bridge.py` 29 格 + #3512 的 13 格全绿;ruff / mypy(该文件 0 error)干净。**四处变异全部转红且只红对应的格**:① 把判据改回 #3512 的形状(忽略 schema)→ 不可收窄那格红;② 整条拒绝分支去掉 → 可收窄那格红;③ `_accepts_narrowing` 恒真 → 三格红;④ 重试建议改回单一固定文案 → 不可收窄那格红。 > **2026-09-08 — docs(help): AI 助手图补上「能力从哪来」—— 一个注册表节点回答「有了 CLI 和 MCP 为什么还要 agent」(0 迁移 / 0 cron / 0 新 MCP / 0 API 契约)** `/help#ai-copilot` 那张图把「知识库 / 只读工具 270+ / 自助流程 60+」画成了 agent 自己的能力。这在事实上是反的:那三个框就是**平台自己的 MCP 工具注册表**(`server/app/mcp/tools.py`,`_REGISTERED_TOOLS_COUNT_HINT` 现为 626),`helix` CLI 和任何第三方 MCP 客户端消费的是同一份 —— legend 里其实写了这句,但**图上看不见**,于是每个看图的人都会问同一个问题:「我们已经有 CLI 和 MCP 了,为什么还要做 agent?」 补两个节点:`REG`(平台工具注册表,实线进 agent,边标「助手的能力来自这里」)和 `OTHER`(虚线框,helix CLI / 你自己的 MCP 客户端)。**虚线那条是有意的存根**,不在这里重复 `/help#ai-choose` 的六路径矩阵 —— 这张图要说的只是从属关系。配一条 legend「同一套能力,三种用法」把真正的区别写死:走 CLI/MCP,自己装客户端、自己配令牌、自己决定调哪个工具,**写操作在客户端调用的那一刻就执行了**(CLI 只对危险子集做本地 TTY 确认,那是客户端侧的保证);走助手,什么都不用装,而且它**一次写都不能自己执行**,只能生成一张卡 —— 这个保证在服务端。所以两者不是二选一:agent 正因为站在这份注册表上,新流程上线当天就会用(`mcp_bridge` 是**进程内借用**注册表,不走 MCP 的线)。 🔴 **顺手修掉一个已经过时的精确数字。** legend 里写死「共 480 个」(zh/en/ja 三份),而注册表已到 626 —— 这是这一段里唯一写成精确值的地方,其余都按本页既有约定写成「270+」这类模糊值(`HelpCenterPage.tsx` 的注释就记着上一个精确值「~320」一个月内就过期了)。改为「600+」,回到只会朝安全方向过期的写法。 **验证**:用仓库锁定的 mermaid 11.16.1(不是 CDN 上的 10.x)+ `MermaidDiagram` 的同款 init(`securityLevel: strict` / `htmlLabels: false` / `curve: basis`)离线渲染了改后的图,确认新节点不破坏原有两条泳道的布局;`pnpm lint`(含 i18n 三语齐全 / 动态命名空间 / 混排四道 guard)、`pnpm typecheck`、`pnpm test`(107 文件 1426 用例)、`pnpm build` 全绿。 > **2026-09-07 — fix(assistant): 转人工建群后那张卡承诺的工单号是空的 —— `str.format` 吃掉了没有槽位的关键字(0 迁移 / 0 cron / 0 MCP / 0 API 契约)** 生产上被看到的形状:员工问「380838443567 这个云账号谁负责」,助手没答上来,按「云」转人工。答复卡上留下一句「已转人工，正在建单，**工单号稍后单独发给你**」,紧接着单独发来的那张 `已转人工处理` 卡写的是「已按「云」把你和 XXX 拉进一个群…不用再复述一遍。**工单号:**」—— 冒号后面什么都没有。工单确实建了,但号码在员工能看到的**任何一个地方都没出现过**。 根因是 `str.format` 的静默:`_HANDOFF_BODY_CHAT` 的 zh / en / ja 三种文案都以「工单号:」这个悬空标签结尾,**都没有 `{number}` 槽**(号码是后面用 f-string 追加的,单独成行、放在 code span 里,好让员工选中复制)。建群分支却写成 `.format(owner=…, label=…, number=number)` —— 多出来的关键字被 `str.format` **丢弃且不报错**。另外两条分支(没拉到人 / 建工单按钮)用的是 f-string 追加,所以号码只在**建群成功**这一条路上丢,而它恰恰是转人工按钮的主路径。 🔴 慢路径把这条缺陷从「少个号码」放大成「号码从未送达」。建工单要向每个 IT admin 走飞书 + SMTP 扇出,经常超过飞书 3s 的回调预算 —— 超时后原地那张卡就**永远停在**「稍后单独发给你」,不会再被改写(`_deliver_followup` 的设计:结果作为**新消息**发出,不回写旧卡)。于是唯一该带号码的那张卡,正是丢掉号码的那张。截图里两张卡同时出现,就是这条路径。 **修法是把三个分支收敛到一个 `_with_ticket(body, number)` 辅助函数上**,而不是给模板补一个 `{number}` 槽:三处各自拼字符串是这个缺陷能存在的原因,补槽位只修当下这一格,下一条文案照样能忘。建群分支的 `.format` 只留 `owner` / `label`,追加号码交给辅助函数。 **回归测试**(`test_handoff_ticket_number_2026_09_07.py`,10 格):三条建单分支 × zh/en/ja 都断言号码出现在跟进卡上,外加一格钉住「加号码不能把负责人和路由名挤掉」。变异验证做过:把建群分支改回 `.format(number=…)` 的旧形状,**恰好三格转红**(建群 × 三语言),其余七格全绿 —— 复现出的卡片文案与生产截图逐字一致。 > **2026-09-07 — feat(security): 英文漫画落地 —— 21 条素材的英文画面 + 4 条新漫画(0 迁移 / 0 cron / 0 新 MCP / 0 API 契约)** #607 的翻译器做了它能做的那一半:把每条漫画的标题 + 摘要机器翻成 en / ja,而**把中文 `image_keys` 原样复制过去** —— 模型重画不了漫画。它自己的 docstring 写着「英文读者拿到英文标题 + 中文画面」。于是线上 30 条已发布漫画,英文读者看到的是英文外壳 + 读不懂的画面。 用户拿来 25 张英文漫画(1600px 竖版长图,每张 1.0–1.7 MB,`awareness_material` 用途上限 10 MB)。**`secaw_materials.localized` 本来就是按语言存到画面这一层**(`image_keys` / `cover_key` 在每种语言的 block 里,`service.pick_block` 解析出一个 block、只对它自己的 key 签名),所以这是**数据操作,不是代码改动**。 **21 条合并 + 4 条新建。** 判断依据是逐张比对:抽查 `01_Spot_a_Phishing_Email_in_3_Steps.jpg` 与线上「3 步识破钓鱼邮件」的原图 —— 同一主题、同样的三步结构、同样的扁平矢量风格与绿色配色、连钓鱼钩的视觉母题都一致,是**同一篇的英文版**。 🔴 **标题只有 7/25 完全一致,所以刻意不做模糊匹配。** 其余差在空格、标点或用词(三步 vs 3 步 / 完美的密码 vs 好密码 / 社交网络：七不发 vs 朋友圈七不)。而线上有**四条**不同的社交主题漫画 ——「差不多」会把英文页挂到错的那一篇上。映射表逐条人工核过写死在脚本里,**解析不到就报错,绝不跳过**。两处需要判断的:04 的英文版同时覆盖社会工程与 CEO 诈骗,并到在线那条、已归档的「什么是 CEO 诈骗」保持归档;16 的「七不发 ↔ 七不」并到「朋友圈七不」。 **`cover_key` 和 `image_keys` 一起改。** 封面是学习中心卡片的缩略图 —— 只换内页会得到「英文正文 + 中文缩略图」的卡,读者在点进去之前就读不懂。 **日文指向英文画面**(用户 2026-09-07 决定)。这与平台自己在 `core.locale.FALLBACK_CHAIN` 里的理由一致:对日本读者,英文比中文更接近。 **4 条新建**(AI 工具泄密 / 公共 WiFi / 移动介质 / 居家办公)—— 这四个主题线上没有中文漫画。按用户决定「只有英语的就都显示英语的」,三种语言的 block 都指向英文画面,zh / ja 的标题与摘要由我撰写,所以卡片本身读得懂,只有页面是英文。 ⚠️ **刻意没动 `mt_langs`。** 线上每条已发布漫画这一列现在都是空的 ⇒ 读者看不到「机器翻译」提示 —— 这是我接手前就有的状态,这次既没造成也没改变。**现在把标记加上会是错的**:漫画版的那句提示说的是「图片仍为中文」,而这恰恰是本次唯一变成假话的一句。要恢复这个徽章,得先把提示文案拆成「标题是机翻」和「画面是外语」两件事,那是代码改动,不是数据改动。 **幂等**:上传的 key 以源文件名结尾,所以「这条素材是不是已经有这张图」可以从存下来的 key 直接回答 —— `en.image_keys` 已以该文件名结尾就跳过,不重传不重写。第二遍实测 `merged=0 created=0 skipped=25`。 **取证**(生产):21 条素材的 en 画面 ETag 与本地源文件 md5 **逐条相等**,`cover_key` 与 `ja` 对齐 21/21;素材引用的 56 个对象在 S3 全部存在;在生产容器里用真实端点走了一遍 zh/en/ja —— 同一条素材分别解析出 `zh` / `en` / `ja` block(`fallback=False`),en 与 ja 的页面和封面都指向 `01_Spot_a_Phishing_Email_in_3_Steps.jpg`,预签名 URL 取回 HTTP 206、`image/jpeg`、JPEG 魔数 `ffd8ff`。⚠️ 中间有一轮把 **HEAD 打在 GET 签名的 URL 上**,三种语言一起 403 —— 预签名把 HTTP 方法签进去了,那是 `SignatureDoesNotMatch` 而不是 ACL 失败;换成带 Range 的 GET 即通。判据:线上原有的中文对象**同样** 403,一个「我没动过的东西也坏了」的信号应该先怀疑探针。 合并后仍有 **10 条漫画只有中文画面**(让黑客远离你手机里的数据、网络社交隐患多 上/下、一图读懂《网络安全法》、手机面临的威胁及防护要点、保护好电脑、一图读懂大数据、社交网络上的安全、你的弱密码谁都猜得到,以及已归档的什么是 CEO 诈骗)。 > **2026-09-07 — feat(assistant): 转人工路由把「云与网络」拆成两类(迁移 629 / 0 API 契约 / 0 cron / 0 MCP)** 627 播种的 8 个类别里,`cloud` 叫「云与网络」—— 一条路由、一个负责人。而这两件事**不是同一个人管的**:云(云账号、服务器、域名、DNS、证书、云上权限、云成本)是冯帅,网络(办公网、WiFi、VPN、专线、网络故障)是孟凡生。 合成一类的后果不是「分类不准」,而是**一半的问题一定被拉给错的人**:模型判对了类别(它确实是「云与网络」)、路由也按表找对了负责人,然后办公室 WiFi 连不上的人被拉进了一个只有云负责人的群 —— 每一步都「正确」,结果是错的。 **为什么走迁移**:后台 `/admin/assistant-handoff` 只能改**已有行**的负责人 / 提示词 / 启用,没有「新建类别」的入口(刻意的 —— `category_key` 是分类台账里的稳定标识)。所以「多出一个类别」必须是一次迁移。 **三条纪律**:① 不覆盖已经指派好的负责人 —— `cloud` 的 owner 只在**为空**时按邮箱补上,`network` 已存在就整行不动(负责人是运营数据,管理员改派过不该被一次发布改回去);② 显示名和提示词**无条件**改 —— 留着那句「云与网络」等于让模型继续把网络问题判给云;③ 降级不删有台账引用的行(`assistant_handoffs.route_id` 有 FK,删行撞 1451),改成停用。 🔴 **提示词里那句排除比列举更重要**。两条 hint 各自都写上「什么不属于我、该走哪一类」(云:「办公网、WiFi、VPN、专线…走「网络」」;网络:「云上的服务器、域名、DNS、证书…走「云」」)。分类质量**全部**来自 hint,而两个相邻类别之间,模型真正需要的是边界而不是各自的清单。测试断言的正是这一点(对方的词只允许出现在那句「走「X」」里)。 **验证**:6 条迁移用例(两类落库 + 负责人不被覆盖 + 可重跑不重复不改派 + 邮箱解析不到留空 + 降级保留被引用的行 / 删无引用的行);4 处变异全部转红(去掉 `owner_person_id IS NULL` / 只改名不改 hint / 去掉 `WHERE NOT EXISTS` / 降级无条件删行)。 > **2026-09-07 — fix(assistant): 「查不出来」和「叫我转人工却没有按钮」—— 两条生产落空,取证到根因(0 迁移 / 0 API / 0 cron / 0 MCP)** 用户在飞书里问「380838443567 这个云账号谁负责」,两轮都落空,并问了三个问题:为什么查不出来、为什么第一次没有按钮、云的能力是不是没加给 agent。**先取证再动手**(生产 `assistant_messages.tool_calls` + `cmdb_cloud_scopes` 只读查询): **① 「查不出来」的真因是查找方式,不是缺能力。** 第二轮模型**三次**调用 `list_cloud_scopes`、**一次都没传 `search`**,然后回答「在当前可查询的云账号列表中,没有找到」。而那个账号 `pingcap-dbaas` 在库里、有负责人(李卓然)、状态 `active` —— 它只是按 `display_name` 排在第 **197** 位,而工具一页给 200 行、共 **271** 行。 桥层**本来就**在字符截断时给了警告,措辞还很直白(*Do NOT tell the employee something does not exist based on this call. Call the tool again with a narrower argument (a search term…)*)—— **模型照样无视**。所以修法不是「警告写得更狠」,而是让那个错答案**拿不到素材**:没给任何收窄条件的超限调用返回 `oversized_refusal()` —— **零行数据** + 一条「你没有看到任何数据,绝对不能据此回答『没有找到』」的指令。翻页参数(`page`/`page_size`/`limit`/`offset`/`cursor`)**不算**收窄,因为那正是失败时的形状。给了收窄条件的调用仍走原来的「部分结果 + 警告」。 **② 第一轮没有按钮,是字数门槛误伤。** 那条回复是「这个问题有点复杂,建议「转人工 / 开工单」让 IT 同事帮你处理。」—— **34 个字**,低于 `MIN_CHARS_FOR_CARD` 的 40,于是被判成「短句走纯文本」。**唯一一条明确叫员工去按按钮的回复,恰恰是不带按钮的那一条**,员工只能重新问一遍(用户就是这么发现的)。字数门槛的本意是「别给『好的,已记下』套卡」,对这一类完全不适用 —— 现在 `should_render_as_card` 先看 `recommends_escalation()`(三语关键词:转人工/开工单/建工单/file a ticket/チケット…),命中就一定出卡。短确认句仍走纯文本。 **③ 「云的能力没加给 agent」是误判。** 实测:助手**已经**能看到 **360 个只读 MCP 工具,其中 64 个是云 / 网络 / 成本类**(`list_cloud_scopes` / `list_cloud_servers` / `cost_*` / `cloud_resource_directory_*` …)。桥层按 `mutates=` 这条 ground truth 自动借用整个 MCP 注册表,新工具当天就可用,不需要维护名单。当时缺的不是能力。 **验证**:13 条新用例;3 处变异全部转红(去掉「叫人转人工必出卡」/ 让翻页算收窄 / 拒绝载荷退回「给一半」)。 > **2026-09-07 — fix(assistant): 转人工路由的配置接口会说「已保存」而没保存;顺带补上读/写分层那条真正的边界测试(0 迁移 / 0 cron / 0 MCP)** 复审第三轮,盯新加的那个配置接口。 **① 说「已保存」却没保存。** `display_name` 原来是「凑不齐 zh/en/ja 三语就跳过」—— 接口返回 **200** 而那一行根本没改,管理员以为自己保存了。群名是员工和负责人都看得见的东西,三语必须齐;改成 **422** 并说清缺什么。**一个说「已保存」却没保存的配置面,正是这一整轮在别处反复修的同一类谎。** **② 手打错一个 id 变成 500。** `uuid.UUID("not-a-uuid")` 抛 `ValueError`,裸着冒出去就是一个 500 —— 而这是配置面上一次普通的输入错误,管理员该看到「这个 id 不对」。改成 422。 ⚠️ **③ 一条权限测试原来是空转的。** 我写的是「员工读不到也改不了」,而员工在**读和写两端都**被拒 —— 所以把写面放开给 `auditor` 时那条测试照样绿:它根本没覆盖读/写分层这件事。真正的边界是「**审计员要能看、但不能改**」(这一整个 admin 面就是给 global_admin + auditor 的,而改派负责人是一次运营决定,不是审计动作)。补上之后,把写面放开给 auditor 的变异当场转红。 **验证**:7 条接口用例;4 处变异全部转红(畸形 id / 部分显示名 / 兜底不互斥 / 写面放开给 auditor)。 > **2026-09-07 — fix(notifications): 回执对账的预算数的是「行」而不是「件」—— 一次全员 fan-out 就能把整轮饿死(0 迁移 / 0 API / 0 cron / 0 MCP)** 复审第二轮。`reconcile` 的 `limit` 加在**行**上,而同一件事往往有很多行(多个收件人 × 多个渠道)—— 一次全员安全宣贯是 400 多行、**一件事**。于是那一件事就能吃掉整轮 500 的预算,这一轮里所有别的主题一个都看不到。 而对账是回执的**保证**那条腿:它一饿死就等于悄悄不再覆盖任何东西,**而且不会报错** —— 运行摘要里 `scanned` 照样是 500,看起来在干活。 改成在 SQL 里按 `(resource_type, resource_id)` 分组,`limit` 因此数的是「件」:一件事有 5 行也只占 1 个额度。顺带钉住顺序(原来没有 `ORDER BY`,取哪些由引擎决定):按最近发送时间倒序 —— 刚发出去的那些最可能有人正要去点,优先让它们的卡片变对。运行摘要里 `scanned` 仍是行数(运维读它判断体量),新增 `subjects` 是件数。 ⚠️ 这条的**变异验证第一版是抛硬币**:测试里 fan-out 的 5 行和另一件事的 1 行时间戳全都相同,取哪几行由引擎决定,于是「退回按行取」的变异跑出来是绿的。把 fan-out 的行造得**更新**之后才成为确定性判据(错误实现下预算被它整轮吃光,那件安静的事一行都进不来)。 **顺带记一次误判**:同一轮的全量跑出了 `1 failed / 633 errors`,集中在 zoom / 坐席等**与本次改动毫无关系**的文件上。按 memory 里那条判据(成批 setup ERROR + 集中在无关文件 = 撞库,不是断言失败)先数进程 —— 确实有**另一个会话**的 pytest 在并行跑。换一个隔离键(`cardv43`,43%16=11)重跑:**3301 passed / 0 failed**。 > **2026-09-07 — feat(security): 每日一题按员工语言出题;安全内容(题库译文 / 新题 / 宣贯素材 / 问答)以数据导出 + 灌入脚本落库(迁移 628 / 0 cron / 0 新 MCP / 0 API 契约破坏)** #607 修的是「英文界面右下角的宣贯气泡是中文的」,结论是**链路没坏、内容缺语言**。这个 PR 处理同一条反馈里没人提的另一半:**安全每日一题整个题库只有中文**。题干、四个选项、答完之后的解析都存在只装一种语言的平面列里 —— 一个读英文界面的员工点开「安全每日一题」,拿到的是中文题 + 中文选项 + 中文解析,而他答错与否会进排行榜、进部门擂台、进「安全意识参与度」那份合规证据。 **一、语言:`secquiz_questions.localized`(628)。** `{"en": {prompt, options, explanation}, "ja": {…}}`;**中文不在里面** —— 三个平面列继续当基线。与 `secaw_materials.localized`(三语都在 JSON 里)不同,两个原因:这一列加在已有 309 行上,搬一次等于重写每一行 + 每一个读者(排行榜/擂台/素材小测/MCP/装备墙都读这张表);而 `correct_key` 与语言无关,它必须紧挨着唯一一份权威选项表。 🔴 **选项 key 是契约,文案不是。** `correct_key` 记的是选项 key(`"A"` / `"ABD"` / `"T"`),而读者是从**我们渲染给他的那一份**列表里选的。所以一个 key 集合与基线不一致的 block 不是这道题的译文,是**另一道题** —— 拿它渲染就是「用读者没见过的选项判他对错」,比中文题摆在英文界面上更糟。`localization.block_for` 在读路径拒掉它并回退到基线选项(题干仍用译文,读者至少读得懂题);`validate_block` 在写路径把同一条规则前移成编辑器里的 422;灌入脚本对导出里的每一条也过同一个校验。**变异验证**:去掉 key 比对 → 两条读路径用例当场转红。 **语言由服务端决定一次**,顺序是 `?lang=`(前端 i18next 当前语言)→ `Accept-Language` → 本人 `preferred_language`(经 `core.locale.resolve_lang`)。第三级不是可选的:MCP 面和任何将来的通知卡片都落在那里,回退到中文基线等于在每一个非浏览器面上把原 bug 重造一遍。客户端**永远拿不到** per-language map —— 读者选的选项和判卷用的答案键必须来自同一次解析。缺语言时回报 `is_fallback_lang`,桌面与移动端各渲染一条「今天这道题还没有你所选语言的版本」的提示:一道语言不对又不解释的题,和一个坏页面无法区分。素材小测走同一套解析(`questions_for(lang=)`;管理台与错题率报告传 `None` 保持中文基线 —— 那两处要看的是作者写的原题)。 ⚠️ **中文改了、译文没跟着改 = 比没译文更糟。** 管理台保存时若 `prompt`/`options`/`correct_key` 变了而调用方**没有**显式带 `localized`,存量译文被**丢弃**并记一条 info 日志 —— 保留它们会让英文读者看着旧题面、被新答案键判分。管理台因此长出三个语言 tab(中文=基线,en/ja 只翻三段文字;选项输入框按基线 key 逐个渲染、占位文字是对应中文原文 —— 让选项 C 的译文紧挨选项 C 的中文,这是「对得上号」唯一能被人眼审出来的排法),保存时**总是**显式回传三种语言的状态。 **二、内容:不进仓库,走导出 + 脚本(用户决定,2026-09-07)。** 第一版把译文/新题/素材/问答写成 7 个数据模块 + 迁移 628 —— **10,430 行数据对 1,833 行功能**,用户的判断是「数据往库里堆就行,不需要合并 12,000 行代码」。于是:数据导出成一份 JSON(`~/.helix-content/security-content-2026-09-07.json`,875 KB,不在仓库里),仓库里只留 [`scripts/load_security_content.py`](../server/scripts/load_security_content.py) —— 四步「不存在才写」,每步都幂等,导出里的每条译文再过一遍 `validate_localized`;用 pymysql 同步驱动,从本机对 TiDB 也能直接跑(asyncmy 会静默挂死,见 prod-access 笔记)。**代价**:内容不进 review 与版本历史,重建环境要多跑一步;**收益**:PR 从 12k 行缩到 1.8k。本地实测:清空 `localized` 后跑一遍 337/337 补齐,第二遍全部 skipped,`COUNT(DISTINCT)` 不变。 那份导出里是什么:**309 道存量题的 en + ja**(逐题写的,按 `prompt` 匹配 —— 题干全库唯一);**+28 道新题**(三语):AI 使用 / 研发与供应链 / 云 / 事件上报 / 合规隐私 / 出行远程 —— 原题库这六面**一条都没有**(提示注入、语音克隆、公开桶、0.0.0.0/0、密钥进仓库后的处置顺序、上报后不要自己清理、DSR、边检设备);**+12 条三语宣贯素材**(`article`,已发布;刻意不是 `comic` —— 漫画每一页是 S3 对象,脚本造不出来,漫画走管理台上传);**+35 条答复库条目**(22 员工可见的安全问答 + 13 条 `employee_visible=0` 的合规证据口径,带 `backing_control_keys`)。 🔴 **写这批答复之前把线上 109 条的 `question_zh` 全读了一遍,近义重复一条没写。** 初稿里有 13 条撞了既有条目(公共 Wi-Fi、个人网盘、装软件、点了钓鱼链接、设备丢失、调岗权限、引入 SaaS、密钥进仓库、尾随进门、MDM 能看到什么……),全部删掉,换成库里确实没有的面。**FAQ 里的重复不是「更多内容」,是更差的检索** —— 同一个问题返回两条答复,员工不知道该信哪条,而两条会各自老化。 **三、顺带一处诚实的数字。** `/security-quiz/admin/coverage` 现在同时回报语言覆盖率(`per_lang_pct` / `fully_localized`,只算 active 题 —— 归档题永远不会再被指派,让它进分母只会让缺口看起来永久更差)。放在参与率同一个 payload 里是刻意的:**「94% 的人答了题」在其中三分之一是用非母语作答时,是一句比看起来更弱的合规主张**,而这正是安全团队引用的那份证据。 **验证**:`tests/test_security_quiz/test_localization.py` 19 条(语言解析优先级 / ja→en→zh 回退链 / 只有解析的 block 不算存在 / 对错题可省选项 / 选项永不退化成空 / key 漂移在读写两侧的两种处置 / 拒绝把中文当译文写入 / 白名单丢弃多余键)+ 素材小测既有用例全绿 + alembic 链 98 条单头;前端 lint / typecheck / 1426 tests / build 全绿;本地 DB 三语题 337/337,同一道题按 `preferred_language` 分别渲染 zh/en/ja 实测通过。 > **2026-09-07 — fix(cards+assistant): 卡片这一轮的复审与安全扫描 —— 6 个真问题,其中一个会让生产部署直接失败(0 迁移新增 / 0 API / 0 cron / 0 MCP)** 五个 PR 合完之后按要求做整体复审 + 安全扫描。**六个真问题**,逐个修掉并各配一条会转红的回归测试。 **① 迁移会在生产部署时失败(最严重)。** `627_assistant_handoff_routes` 用裸 `sa.CHAR(36)` 声明带 FK 的 id 列。裸类型继承**表**的默认 collation,而 TiDB 在 collation 不一致时以 **3780** 拒绝建 FK —— `assistant_handoffs` 恰好**混了三个父表**(assistant_messages / identity_persons / 本表),正是 2026-07-29 那次部署失败的同一个形状。**本地 MySQL 8 复现不出来**(两个父表同 collation)。仓库早有 `check_tidb_parity` 闸抓这个,而它住在 `tests/test_core` —— 我逐 PR 只跑了 notifications / assistant / alembic / cmdb / permission,**从没跑到它**。改用 `id_type_for(父表)`(它连 collation 一起返回)。迁移尚未部署到任何环境,所以就地改号内容是安全的。 **② 富文本回复可以让锚文本撒谎。** 新的 `post` 通道用 `md` 元素渲染 markdown,而这条通道送的是**模型写的字**,模型上下文里有第三方文本(知识库正文、工单标题、工具结果)—— 一篇被写坏的 KB 文档可以让助手用**自己的口气**发出 `[点此重置密码](https://evil)`。仓库对此已有明确立场:`email_layout` 给邮件渲染 markdown 链接时**刻意用主机白名单并写明「比飞书卡片更窄」**,理由正是「不能把卡片那个已知隐患原样引进第二个渠道」。富文本是**第三个**渠道,照同一条规矩办,并**复用那一份白名单**(不抄第二份);白名单外的降级成「文字:URL」——目标仍然可见,只是锚文本不能再撒谎。 **③ @ 提及在富文本里会变成可见垃圾。** `render_feishu_mentions` 产出原生 `` 标签,而 `md` 元素里的 `<` / `>` **必须**转义(否则就是内联 HTML 注入面)—— 于是 `张三` 会渲染成 `<at …>` 给员工看。答案卡那一侧早有守卫,富文本这一侧没有。现在带提及的回复一律退回纯文本(那条路**能**正确渲染 ``):少一点格式,好过一行可见的转义垃圾。 **④ 健康指标会永远涨,等于没有指标。** `stale_actionable_count` 只判 `related_resource_type IS NOT NULL`,而平台绝大多数通知是**信息类**的(动态、庆祝、生命周期周知)——它们带 resource_type、也永远不会被结案(那是对的:「今天是你入职三周年」没有「结局」)。收窄到 `RESOLVERS ∪ OPT_OUT` 那一集。 **⑤ 建好的群被报成「没有群」。** 开场白/转发原来和建群在同一个 try 里,任一失败就 `return None` —— 员工被告知「没拉到人」,而飞书里躺着一个两个人都在的**孤儿群**没人提起。群本身才是有价值的产物;开场白和转发是锦上添花。 **⑥ 铃铛自己跟自己矛盾。** 红点(`unread_actionable`)排除了已结案行,而分组视图的 `unread_by_bucket` 没排除 —— 同一个面板里红点说 0、「待处理」那一组说 1。两处必须用同一个判据。 **验证**:3299 条后端用例(notifications / assistant / alembic / scheduled_jobs / permission / core)全绿;6 处修复各配一条回归测试,**每一条都做了变异验证**(退回旧行为 → 转红)。前端 lint / typecheck / 1426 条 vitest / build 全绿。 > **2026-09-07 — feat(cards): 按钮在手机上折行、在桌面上空半屏 —— 两次真机截图各修一处;续期审批卡按新版式重写(0 迁移 / 0 API / 0 cron / 0 MCP)** 用户连发两张真机截图。**手机**那张:答案卡四颗按钮挤在一个 `flow` 行里,前三颗一行、第四颗孤零零掉到第二行;而 `🎫` 在按钮尺寸下被飞书渲染成一张彩色的「演唱会门票」小图,比没有更糟。**桌面**那张:我把动作行改成 `bisect` 等分之后,两颗按钮被推到卡片左右两端,中间空掉半屏 ——「这也好丑啊 空这么多」。 两处都是**只有在真机上才现形**的问题:flow 布局按可用宽度贪心排列(桌面够宽,看不出会折行),bisect 按整卡宽度等分(手机够窄,看不出会拉开)。最终形状是**两行,每行两颗,都走 flow**:两颗短按钮在窄屏放得下、在宽屏紧挨着。动作按钮**去掉 emoji**(标签本身已经说清是什么),评价按钮改成更短的「👍 赞 / 👎 踩」——它们并排在自己那一行,长标签会把行挤到折行。`mode="bisect"` 留在渲染器里但当前无调用方,并写明为什么不适合答案卡。 **续期审批卡按新版式重写** —— 就是用户最初拿来对照的那张。标题从 `[待审批·云权限续期] 施宏伟 申请续期 PingCAP SCC 1 项权限` 变成一句人话「施宏伟 Jacky Shi 申请续期 PingCAP SCC 的 1 项权限」:方括号前缀那些信息现在由状态徽章(待处理)和副标题(云权限续期 · 订阅名)承担,**邮件主题仍保留前缀**(邮件客户端靠它扫一眼分类)。正文原来把「多少项、多久、什么原因、哪些角色」全塞进一段散文;现在时长进事实盒右侧(它是决定答不答应的那个数字)、申请人/原因进事实行、角色清单折叠(1 项直接铺开、6 项折起来带计数,由渲染器按行数自己决定)。两种长度都发真卡验过。 顺手修掉一处**原语误用**:软件权限审批卡把「申请人」和「权限」放在 `card_stats` 里,而 stat 网格是给**数字**的(浅底格子 + 大号粗体值)—— 于是「申请人 = 张三」被渲染成一个大号粗体的名字,读起来像一个指标。改成事实行,并补上「原因」(它原来只在邮件正文里有)。 ⚠️ 写这张卡时又踩了一次「推断的形状」:我给事实行加了「原到期日」,而 `CmdbCloudGrantRenewalRequest` **没有** `current_expires_at` 这一列(到期日在 grant 上)。查了模型才发现,于是**删掉那一行**而不是为一行装饰性事实多查一次库 —— 正文那句「驳回后按原到期日正常回收」已经把它要传达的东西说清了。 **验证**:84 条权限 + 续期用例全绿;新旧两种长度的续期卡、两行按钮的答案卡都发到飞书真机验看。 > **2026-09-07 — feat(assistant): 助手的话终于有格式了,「转人工」也终于真的转人工(迁移 627 / +3 API / 0 cron / 0 MCP)** 用户看着答案卡说了两件事:「有用/没解决/转人工 按钮太大了」,以及「转人工实际的功能是建工单,所以我觉得有 4 个比较合理 —— 有用/没解决/建工单/转人工。转人工应该根据问题 AI 分一个类…拉负责人和提问者建一个群把聊天转过来…这种哪些类型的可以在后台配置」。 **按钮大小先修掉了**(那是我自己上一个 PR 造成的:我把它们拉成了通栏等分)。现在分两档:转交是**动作**(描边小按钮)、评价是**注脚**(无边框更小),按自然宽度排 —— 答案本身才是内容,按钮是它的注脚。参照的是用户给的飞书安全中心那张卡的分层。 **一颗按钮拆成两颗。** 原来那颗写着「转人工」而做的一直是**建工单** —— 名字和行为对不上,员工按下去的预期落空。现在 `🎫 建工单` 是异步、有台账、有 SLA;`💬 转人工` 是同步:AI 归类 → 按路由找到那一类的负责人 → 建飞书群把员工和负责人拉进来、**原样转发**那条回答。**转人工也会建工单** —— 群里的活必须在台账上有一行,否则它就是一件没人能查、没有 SLA、交接就消失的活。两颗共用同一个 `_escalate(with_chat=…)`:那里的 rollback / MissingGreenlet 纪律很微妙,第二份拷贝一定会漂。 **权限是用户当场开的。** 建群要 `im:chat`,探针一开始返回 `99991672` 点名缺哪个 scope;用户开通并发布版本后重测,建群/发消息/加人/**转发历史消息**/解散五个动作全部 code 0 —— 所以「把聊天转过来」不必退化成贴一段文字摘要。 **分类与路由刻意分开。** 模型只把问题归到一个**已存在的** `category_key`(闭集,返回值再校验一次——它发明一个键等同于「没分类出来」),「这一类找谁」由 `assistant_escalation_routes` 表决定。于是模型判错的后果是「找错了人」——一个人能一眼看出并改派的错,而不是「凭空产生一个没人负责的类别」。置信度 <0.5 走兜底,但分类结果照样记进 `assistant_handoffs` 供复核。**后台可配**:`/admin/assistant-handoff` 配类别、负责人、给模型的说明、启用、兜底(读 global_admin + auditor,**写只有 global_admin** —— 审计员的职责是看,改派是运营决定)。种子 8 个类别、负责人**一律为空**:刻意不猜任何人的邮箱,未指派会在页面顶部报警。 **降级是正式路径,不是兜底。** 没指派负责人 / 建群失败 / 开关关掉 —— 三种都**仍然建工单**,台账记 `degraded_reason`,给员工的话是「已转 IT,工单号 X」。**拉不到人时说拉到了,是这条链路最坏的失败。** **富文本。** 助手的普通回复原来走 `text` 消息,而 `to_feishu_text` 把模型写的加粗/链接/列表**全部剥掉**(纯文本渲染不了,留着标记更难看)。代价是助手每句话都是一坨没层次的字,而它回答的常常是「你有 2 台电脑,分别是…」这种天生有结构的内容。现在有标记且够长的回复走 `post` 的 `md` 元素(实测:加粗/链接/列表/行内代码);短句仍走纯文本,富文本失败退回纯文本。 ⚠️ **两次变异幸存,各暴露一个真问题。** ① 「两个人都在群里才算拉到人」那道闸**从来没被走到过**:第一版测的是「负责人邮箱为空」,而那一侧在更早的 `not owner.work_email` 就降级了 —— 真正能走到它的只有**提问者**那一侧(`work_email` 是 NOT NULL 但**空字符串合法**)。改成空提问者邮箱后,把 `< 2` 改成 `< 1` 当场转红。② `no_owner` 有两处冗余判断互相遮蔽,单摘一处仍绿 —— 整条防线一起摘才转红(这是 memory 里记过的形状,这次又撞上)。 **验证**:17 条 handoff 用例;7 处变异转红;568 条助手用例全绿;前端 lint / typecheck / 1426 条 vitest / build 全绿(菜单可达性闸要求新页面显式归组,顺带更新了叶子集快照 —— 只多我这一页)。 > **2026-09-07 — feat(notifications): 回执的第二条腿 —— 23 种 actionable 卡片全部表态,加一条 15 分钟对账(迁移 626 / +1 cron / 0 API 契约 / 0 MCP)** 上一个 PR 把回执做出来了,但只接了一条流程(云权限续期)。一个 46 处 actionable 卡片调用点的平台里,「记得在终态迁移处加那一行」注定会漏 —— 而漏掉的后果是一张**永久**骗人的卡片。所以这个 PR 做的是**覆盖**和**保证**。 **清单不是手写的。** 用 AST 扫全仓 `NotificationEnvelope(... card_actions=...)` 的构造点,算出 **23 种** 出现在带按钮卡片上的 `resource_type`。每一种必须落在 `RESOLVERS`(能从状态列问出结局)或 `OPT_OUT`(写明为什么状态解析对它是错的)之一 —— **新增一条 actionable 流程会自动进闸**,不需要谁记得回来登记。形状抄的是仓库既有的 curated-card 纪律。 **10 条有解析器**:工单、权限、云权限续期(按 request_group 聚合)、云访问 grant、SSO 授权、建号任务、实习考勤、服务器负责人确认、离职 IAM 残留、访问认证。**13 条 opt-out**,每条都写明理由,并有天花板防止它悄悄变长。 🔴 **最容易写错的一类,值得单独说**:有些卡片问的问题**两种答案都不改变那一行的状态**。API Key 闲置提醒问「留着还是释放」,选『留着』之后那一行还是 `active`;坐席闲置回收同理;数据访问到期卡的「续期」只把 `expires_at` 推后。给这类写一个「status==active 就算结案」的解析器,会在卡片**发出去的那一刻**就把它判成已结案 —— 比不做回执更糟。同理 `cmdb_cloud_access_grant` 的 `active` **刻意不在**映射里(那个 resource_type 上既有「批准申请」也有「即将到期」两种卡)。这三条判断各配了一条会说话的测试,而不是只留一句注释。 **新 cron `notifications.card_settlement_reconcile`(每 15 分钟)** 是保证那一条腿:扫「未结案、而它说的那件事已经有结局」的行,补上。两边都幂等,抢到同一件事也只有第一次做实事;扫描有界(≤500 行,只看 5 分钟前~30 天内 —— 5 分钟是给内联快路径留的窗口,30 天是因为更老的行绝大多数属于「回执上线前发的、我们根本不知道它后来怎么了」那一批,迁移刻意不回填)。健康指标 `stale_actionable_count`(>30 天仍未结案)每轮记入运行摘要。 ⚠️ **一个自己造出来又自己发现的空转闸**:第一版把状态映射藏在 `_lazy()` 返回的闭包里,于是「解析器只能产出终态」那道闸对十条里的九条**平凡通过** —— 它读不到闭包里的 dict,什么都没检查,而且是绿的。改成 `StatusMap` 的 dataclass 字段后那道闸才真的生效,并额外断言「被检查到的条数 ≥ 总数-1」防止再次空转。同类的还有 AST 扫描本身:如果 `NotificationEnvelope` 改名或 `card_actions` 换参数名,扫描会安静返回空集合、每条覆盖断言平凡通过 —— 所以先钉了一条「至少扫到 20 种」的下界。 **验证**:37 条覆盖闸 + 12 条对账用例。**8 处变异全部转红**:映射改成黑名单 / 行不存在判成 done / 不给内联留窗口 / 扫描无界 / OPT_OUT 也进扫描 / 删掉一条 RESOLVERS 条目 / 解析器映射到非终态 / grant `active` 当成结案。 > **2026-09-07 — fix(alembic): main 上一度有两条 `revision = "624"` —— 改号,并补上那条从来不存在的单头闸(0 API / 0 cron / 0 MCP)** #3501(下线阻断清理)和 #3503(通知回执)在同一小时里各自抢了迁移号 **624**。两边都按 `origin/main` 查过号 —— 但查号和合并之间隔着几十分钟,而**git 对两个不同文件名不会报任何冲突**,于是两个 PR 都干净地合了进去。`alembic heads` 于此给出两个头,`alembic upgrade head` 在下一次部署时会直接失败(生产尚未部署,所以没有造成线上影响)。 后合并的那条(通知回执)改成 **625**,`down_revision` 指向 624。它的四列全部带存在性守卫,所以在任何已经 stamp 过 624 的本地库上重跑都是 no-op。 **真正的教训不是撞号,是没有闸。** 撞号发生时 `tests/test_alembic` 的 **94 条全绿** —— 那些用例逐个验证具体迁移的幂等与回填,没有任何一条断言「整条链单头」或「revision 唯一」。这次是人眼在写下一个 PR 时偶然看见的。新增 `test_revision_chain_is_single_headed.py`(4 条):revision 唯一、恰好一个头、`down_revision` 都指向真实存在的迁移、恰好一条基迁移。**不用 alembic 自己的 API**:`ScriptDirectory` 遇到重复 revision 只发一条 `UserWarning` 然后照样返回两个头,而 pytest 默认不把 warning 当失败 —— 断言必须落在「文件系统上这组迁移是不是一条链」上。已用变异复验:把 625 改回 624 → 当场红,并点名两个冲突文件。 ⚠️ 这个文件的**第一版把 5 条健康的迁移报成了异常**(「两个头 029/625」「032 断链」)。原因是正则只认 `revision = "…"`,而仓库里还有 `revision: str = "030"` 这种带类型标注的写法 —— 那些迁移既不进 revision 集合、也不算被引用,于是凭空造出多头和断链。**先去读了 029/030/031/032 四个文件才下结论,没有去「修」一条本来健康的链** —— 一个闸的第一版报出的异常,要先怀疑闸自己。`down_revision` 也可能是元组(merge 迁移),一并处理。 > **2026-09-07 — feat(notifications): 卡片回执 —— 审批过了,那张卡就地变成它自己的台账(迁移 624 / 0 API 契约 / 0 MCP)** 用户的原话:「helix 的推送没有任何回执的能力,这个审批过了,还是去审批」。确实如此:一条通知说的是「有人在等你做 X」,而在此之前**没有任何东西回来说 X 做完了** —— 一张已经批准的续期审批卡在飞书里原样挂着一颗活的「去审批」按钮,点下去落在一个早已翻页的页面上。卡片是一份意图的快照,而且是永久的。 **地基先实测**:`PATCH /im/v1/messages/{id}` 用 Helix 现有应用权限即可原地改写已发出的卡片(同一条消息二次改写也接受),不需要新 scope、不需要过飞书版本审核。 `settlement.settle(resource_type, resource_id, outcome, actor)` 是唯一入口,连接键是 46 处 actionable 卡片本来就都带着的 `related_resource_type/_id`。`outcome` 取 `card_design.SETTLED_STATUSES` —— 和卡片头部状态**同一套词表**,所以回执长什么样由记录下来的事实派生,而不是在渲染时再选一次。回执卡是重新写的:一句「由 冯帅 于 09-05 15:20 已批准」、两行事实(处理人/处理时间)、领域补充的一句话,主按钮换成次要的「查看详情」——原来那颗「去审批」必须消失,它邀请的是一次会被拒绝的点击。 **顺序是不变量,不是实现细节**:先在行上盖 `settled_*`(本地写,决定铃铛红点与收件箱),再去 PATCH 飞书卡片(外部调用,失败只记日志)。反过来会得到最坏的结果 —— 卡片变成绿色「已批准」而铃铛里那条还写着「去审批」,两个面对着同一件事说不同的话。有一条测试专门钉这个:卡片改写失败时结案记录**仍然**落地。 **三个面里只有两个需要改。** 飞书卡片要 PATCH;铃铛读 `notification_outbox`,靠盖戳(`unread_actionable` 排除已结案行 —— `read_at`「我看过了」和 `settled_at`「那件事完了」是两件不同的事,一条从没被点开的通知说的事情完全可能已经批准)。而**移动端行动收件箱本来就是自愈的**:`mobile/action_inbox.py` 按设计读每个域自己的待决状态,「别处做出的决定会在下一次刷新时反映出来」——原计划里「三个面都要接」这句是错的,读代码之后改掉了。 **边界**:邮件发出去改不了,回执只在卡片 + 铃铛两面成立;刻意**不**补一封「已处理」邮件 —— 审批完再收一封邮件是打扰。 首个接线点是云权限续期的批准/驳回。批准侧只在 `applied and not failures` 时结案:部分失败的行仍然 OPEN、还在等重试,把卡片改成「已批准」会告诉审批人一件没做完的事已经做完了。 **验证**:`test_settlement_2026_09_07.py`(15 条)+ 一条接线测试(原语再好,没人调用就等于没有)。**变异验证 7 处全部转红**:顺序反过来 / 幂等闸摘掉 / 不校验终态 / 红点不排除已结案 / 回执卡保留原主按钮 / 回执不按读者语言渲染 / 批准分支的 settle 摘掉。其中「保留原主按钮」那次**第一版变异是无效的** —— 我把 `url` 改回去了,但多 CTA 分支本来就压过单 `url`,那次改动根本没渲染出按钮;把次要按钮一起摘掉才真的走到那条分支并转红。1535 条 cmdb 续期 + 通知用例全绿;前端 lint / typecheck 全绿。 > **2026-09-07 — feat(cmdb): 「下线」卡在「订阅里还有资源」时,Helix 自己清理 —— 弹窗先把要删的东西摆出来,确认之后不再往回报错(迁移 624 / 1 新 cron / 1 新只读端点 / 0 API 契约变更 / 0 MCP)** 用户点「下线 it-team-us」(Azure subscription,本月花费 $0.00,下线理由填的是「从未使用过」),Azure 回 `400 ResourcesExistingOnSubscription`,Helix 把它翻成一段带 `az group list … | xargs az group delete` 的红色弹窗甩回去。用户的原话是对的:「我要下线,不应该是你把里面的资源先清理了再做下线?不要告诉员工说报错。」 `decommission_reconcile.py` 的模块开头两个月前就写下了同一条原则 —— *One click is the whole interaction … Reporting work back to the person who asked you to do it is not diligence* —— 但它只覆盖了**云端接受之后**那一半(关闭失败自己重试、彻底删完通知点击的人)。缺的恰好是**前置条件**这一半。GCP 的 `liens_exist` 是同一个形状(让人去跑 `gcloud alpha resource-manager liens list`)。 **顺带修掉的是一个更安静的问题:「从未使用过」这个判断本身是错的。** 直连生产资源目录核过,这个订阅下有一个 `lifecycle_status=active` 的存储账号 `billingexport123`(westus2,当天 06:30 的同步还看到它)。$0.00 花费不等于订阅是空的 —— 一个几乎空的存储账号一个月就是几分钱,正好对上图表纵轴的 $0.01。**在此之前 Helix 没有任何一个面会在下线之前反驳这个前提**,Azure 是第一个反驳它的。现在弹窗会先说:这个订阅里还有 1 个资源组,内含 `storageAccounts billingexport123`,下线会一并删除。 三段: 1. **驱动新增一对方法** —— `preflight_close_scope`(只读枚举)+ `clear_close_blockers`(按 key 删)。Azure:三次 ARM 只读(resourcegroups / 订阅级 resources 一次拉完按 RG 归组 / **管理锁**),清理时**先删锁再删资源组** —— `CanNotDelete` 锁会让资源组删除 409,忽略锁的清理在空的测试订阅上会过、在真正需要它的订阅上会失败。GCP:liens 的 list + delete(同步返回,无需等待)。`preflight` 的失败**永远是 `checked=False`,不是空清单** —— 「读不到」和「读了,是空的」是这套机制存在的全部理由,前端的「没有需要清理的资源」文案只在 `supported && checked` 时才出现。剩下四家云(AWS / 阿里云 / 腾讯 / UCloud)继承基类的 `supported=False`,弹窗如实说「这家云不支持预检」而不是假装空。 2. **同意就是边界** —— 弹窗把看到的 blocker key 一起提交(`confirmed_blocker_keys`),后端**只删这个清单里的东西**。确认之后新建出来的资源组不在清单里,于是 409 `SCOPE_CLOSE_BLOCKERS_CHANGED`、清单刷新、请人重新确认,**一个字节都不删**。Azure 侧还有一道 `key_scope_mismatch`:任何一个 key 不指向正在关闭的那个订阅,整次调用拒绝(不是跳过那一个 key)。 3. **异步收尾靠新 cron** —— Azure 资源组删除返回 202 之后在 `Deleting` 里待几十秒到几十分钟,点击那一刻不可能等到结果。`cmdb.decommission_cleanup_resume`(`*/5`)反复推进:重读 blocker → 删还在的(仍然只在确认过的 key 里)→ blocker 空了才重试 close → 成功就走**既有**的落库 + 停 grant + 审计路径(actor 记的是当初点击的人,因为这是在完成他的动作),并给他发**一条**完成通知。预算 72 次 ≈ 6 小时用尽 → `stalled`;碰到 Helix 删不掉的东西 → `blocked`;两者都只通知一次并离开重试队列。 **`status` 故意全程不动**(还是 `active`):给它加一个 `decommissioning` 值会连坐到每一处读它的谓词(申请权限、闲置巡检、成本归属、7 处前端面),而其中大多数问的是另一个问题。在飞的下线存在迁移 624 的 8 个新列上,列表页与详情页从它们渲染「下线中 · 正在清理资源」的胶囊 —— 没有这个胶囊,点完之后页面看起来跟什么都没发生一样。同 PR 给闲置巡检加了一条 `decommission_pending_since IS NULL`:正在被 Helix 清空的 scope 不该再问它的负责人「这个好像没人用了,考虑下线?」。 **桌面端两个下线弹窗合并成一个共享组件** `DecommissionScopeModal`(列表页 + 详情页此前是两份近似副本,预检只会加到其中一个上);移动端管理页把 blocker 摘要塞进决策抽屉的描述里并同样传 key —— 一个不可逆动作的确认弹窗,是最不该有两份的东西。 **验证**:`test_close_scope_preflight_cleanup.py`(12 条,含锁先于资源组、204 幂等、409 具名失败、跨订阅 key 整体拒绝、GCP lien)+ `test_scope_decommission_cleanup.py`(14 条,含「未确认的 blocker 什么都不删」「不带 opt-in 时旧的 502 行为逐字不变」「读不到 preflight 绝不推进到 close」「预算用尽只通知一次且离队」)。**变异验证**:把 `plan_blocker_cleanup` 的 unseen 分支短路 ⇒ 3 红(纯函数 + 点击路径 + resume 路径各一);把锁排序去掉 ⇒ 1 红。既有 165 条 decommission/reconcile/driver 测试全绿,`tests/test_scheduled_jobs` 420 条全绿。**踩过一次**:`decommission_cleanup` 起初 `from app.core.database import async_session_factory`,import 时就把工厂对象绑死了,conftest 换的是模块属性 —— 于是 4 条 resume 测试的 session 全落到 **dev 库**,报「unknown column」(那个库没跑过迁移 624)。改成每次通过模块解析。**端到端(删完真的能 cancel)只能拿真订阅验证,尚未做** —— it-team-us 里那个存储账号在用户点头之前一根头发都没动。 > **2026-09-07 — feat(notifications+assistant): 全平台飞书卡片换到 schema 2.0,「这张卡是什么状态」成为一等概念(0 迁移 / 0 cron / 0 API 契约 / 0 MCP)** 起点是用户拿另一个团队的机器人卡片做对照:那张卡有图标、副标题、状态徽章、浅底信息盒、可折叠长尾和一颗通栏实心主按钮;Helix 的续期审批卡是「一行标题 + 一段散文 + 一个描边窄按钮」。差距不是审美,是**代差**:平台一直在发飞书卡片 **v1**,而 v1 只有 `markdown` / `hr` / `note` / `action` 四种块 —— 头部没有副标题位、没有徽章位、没有图标位,关键事实只能塞进散文,长清单只能全铺开,按钮不能通栏。 **先把可行性打穿再动代码。** 用 Helix 自己的飞书应用凭据逐个真发实测(校验器一次只报一个错,只能一个一个试):2.0 的 `header.subtitle` / `text_tag_list` / `icon`、`column_set` + `background_style`、`collapsible_panel` + `border.corner_radius`、`button` + `width:"fill"` + `behaviors`、`markdown` 的 `text_size` / `text_align` 全部可用;而 **`note` 和 `action` 两个元素被 2.0 删除了**(飞书 `200861` 拒收**整张卡**,不是降级渲染),`column_set.padding` / `.corner_radius` 与 `collapsible_panel.background_style` 非法(但 `column.padding` 合法)。**最扎人的一条**:2.0 里 `primary` 渲染成**描边**,实心的叫 `primary_filled` —— 这就是线上「去审批」看起来像脚注的真因,而代码里明明写着 `style="primary"`。上线前把新渲染器的真实产物按 8 种形态(全原语审批卡 / 多 CTA + 统计网格 / 朴素信息卡 / EN / JA / 庆祝色覆盖 / 注入载荷 / 回执)各发一张到飞书,全部 `code 0`。 **核心改动是把「颜色」换成「状态」。** 旧模型按模板配 `header_color`,于是「这张卡是什么状态」与「它该是什么颜色」是两个各自维护的概念,徽章和图标无处挂靠。现在 `card_status` 一次决定头色 + 徽章 + 图标,解析顺序是「产生者显式 → 模板表 → **通知类别的 bucket** → info」。第三跳是这次最有杠杆的一行:ACTION bucket ⇒ `pending`,于是**全平台 46 处 actionable 卡片自动带上「待处理」徽章**,不需要 46 个产生者各自记得去要一个;而徽章和铃铛红点(`unread_actionable`)派生自同一个事实,不可能互相矛盾。庆祝类的暖色分级、Day-1 卡呼应欢迎邮件报头这些**刻意**偏离状态色的,留在 `COLOR_BY_TEMPLATE`。 **新版式原语**:`CardFactBox`(唯一一个浅底信息盒 —— 左边是主体、右边是那个决定答案的数字;两个盒子就不再是强调而是墙纸)、`CardFact`(`👤 **申请人**　施宏伟` 的事实行,取代散文;「时长 90 天、原因 need billing details」从一段话变成可扫的几行)、`CardCollapse`(长尾折叠,标题带计数,**不足 3 行时直接铺开** —— 把一行藏在点击后面是花一次交互换零信息)、`CardBadge`。四者都**冻进 `card_payload`**:漏冻一个字段不报错,只会让重试投递悄悄退化,那正是当年续期卡丢掉「一键续期」按钮的机制。 **卡头图标不能写死。** 飞书 `image_key` **按应用隔离**,而 dev / prod 是两个不同的自建应用 —— 把某次上传的 key 写进源码,等于生产上每张卡的图标静默变空。新增 `card_icon.py`:PNG 作为仓库资产随代码走(由 `helix-favicon.svg` 光栅化,和浏览器标签页图标同一个标志),key 以 `(app_id, 内容 sha256)` 缓存在 `platform_settings`,换 logo 只需替换 PNG,上传失败降级成「没有图标」+ 10 分钟冷却,缓存写入走独立 session。语义态(已批准 / 告警)用飞书标准图标**压过**品牌 logo:绿色「已批准」卡如果图标还是中性 logo,就把颜色和徽章刚建立起来的状态信号又丢掉了 —— 品牌身份在聊天里由发送方头像承担。 **助手的卡片并入同一个渲染器。** `confirm_card` 原来在成品卡上做手术(按 tag 找 `action` 元素再插按钮),而 2.0 没有那个元素;`_closing_card` 手搓 v1 dict,而它是用来**替换**一张 2.0 卡的(两种 schema 不能混)。现在两者都走 `_build_interactive_card`,回调按钮通过新增的 `callback_actions` 参数**穿过**渲染器而不是事后拼接。确认卡的参数行从 `CardSection` 换成事实行,并挂上 `pending` 态 —— 助手的卡不再看着像另一个产品。⚠️ 回调 payload 在 2.0 里从顶层 `value` 移进了 `behaviors[].value`,而**换渲染器之前发出去的卡片还会在聊天记录里躺几个月**,所以 `_action_value` 两种形状都读:老卡上的按钮被点时照样能用。 **前端同步**:`FeishuCardPreview` 跟着改成新语言(副标题进头部、状态徽章、通栏实心按钮),并在文件头写明它是 `card_design.py` 那张表的**镜像** —— 一张表两处实现已经骗过一次 HR(预览画橙色、真卡发蓝色)。徽章文案三语补进 i18n(`feishuCard.badge.*`),其中 ja 的「注意」与 zh 字节相同被 i18n parity 闸挡下,改成「要注意」并同步回后端令牌表,两个面继续说同一句话。 **验证**:新增 `test_card_design_2026_09_07.py`(50 条)+ `test_card_icon_2026_09_07.py`(10 条),既有 19 条断言 `card["elements"]` 的用例改读 `tests/support/card_shape.py` 的取值器(schema 形状只假设一处)。**两轮变异验证**:去掉 bucket 派生 / 把 `primary` 映射回描边 / 冻结触发条件漏掉 `card_facts` / 事实盒不转义 / 副标题回到正文 —— 五处全部转红。图标那组**第一版是假绿**:用「先 resolve 一次让它自己写缓存」来构造前置状态,而 `_persist` 提交在自己的 session 里、调用方 session 的 REPEATABLE READ 快照看不见那一行,于是缓存命中那条路根本没被走到 —— 删掉 `app_id` 校验它照样绿。改成在调用方 session 里直接 seed 后,三处缓存失效变异全部转红。后端 1428 条通知/助手/HR 用例 + 前端 lint / typecheck / 1414 条 vitest / build 全绿。 > **2026-09-07 — fix(web): 申请云访问的「附加角色」从来没有过它宣称的那扇门 —— 把文案改成真的,顺手把 31 个 AWS 权限集的混合态收敛掉(0 迁移 / 0 cron / 0 RBAC / 0 MCP / 0 API 契约变更)** 接着 #3498 的自审。我在上一轮的汇报里告诉用户「被关掉的角色仍然能在『附加角色』里搜到,因为那个框按设计是全量目录」——**这句话是错的**,我信了代码注释而没有去看那次真实的 wire 调用: ```ts async listScopeRoles(scopeId, includeAdminRoles = false) // 没有 promoted_only ``` 后端 `GET /scopes/{id}/roles` 的默认值是 `promoted_only=True`,而**前端从来没传过 `false`**。所以两个下拉框吃的是同一份「管理员精选」列表,`extraRoleOptions` 里那句 `!r.is_promoted ? '[内置]'` 是**恒假的死代码**。 真正的缺陷因此不在行为上,在**文案上**: | 键 | 它说的 | 事实 | |---|---|---| | `curatedHint` | 「主角色精选 {{promoted}} 个。**其余 {{total}} 个厂商内置**可在下方『附加角色』里找到」 | `total` 就是 payload 长度 = 精选数本身。用户截图里是「精选 14 个。其余 **14** 个」—— 同一个数印了两遍,而「其余」其实是 0 | | `noRolesInFilter` | 「如需补充权限,请在下方『附加角色』里**从全量目录挑选**」 | 那个框里只有同一批精选角色;真没有精选角色时,这句话把人指向一扇不存在的门 | | `extraRolesHint` | 「从**全量目录(含数百个厂商内置)**里挑」 | 同上 | | ja-JP 的 `curatedHint` | 「主ロール**精选** {{promoted}} **个。其余** {{total}} **个厂商**組み込み可在下方…」 | 半句中文半句日文的混排残留 | **一个宣称了自己没有的门的选择器,和一个没生效的 demote 是同一类缺陷** —— 用户这一轮的原话就是「不要有这种问题」。所以修文案而不是加门:两个下拉框都来自精选集这件事本身是对的(用户刚花力气把角色藏起来,再给一条通往未策展目录的路是自相矛盾的),「附加角色」的用途是**一次申请多个角色、走同一张审批单**。三语文案改写、死代码与 `builtinRoleSuffix` 键删除、组件顶部那段描述「全量目录」的注释改成描述真实链路,并写下如果哪天真要恢复 power-user 路径,诚实的形状是 `promoted_only=false` **加上**排除 `promotion_overridden_by_admin && !is_promoted`(「从没被精选进来」仍可达,「管理员明确拿掉的」不可达)—— 这正是 #3498 那个新列让人能表达的区分。 **不变量钉在了后端**(正确的那一层):把 `promoted_only` 的默认值变异成 `False`,#3498 的 `test_demoted_role_leaves_the_employee_dropdown_on_a_new_scope` 立刻转红(其余 8 条不动)—— 也就是说「员工下拉框只给精选集」这条现在有测试守着,不是靠前端少传一个参数的巧合。 **顺手把 31 个 AWS 权限集的混合态收敛掉了(生产数据,已执行)。** 上一轮我把它记成「方向得由管理员定,数据上分不开」。**再量一次就分开了**:那 31 个键上,`is_promoted=0` 的 2110 行 `first_seen_at` 落在 2026-04-29 … 06-15,`is_promoted=1` 的 990 行落在 **06-15 … 09-03** —— 一条干净的时间分界线,和 12 个阿里云键**同一个机制**(审计里 2026-06-11 / 06-30 三条 demote,`rows_affected` 分别是 71/72/72,之后新接入的 AWS 账号原样复活)。所以方向不是猜的,是数据自己说的。经生产端点 `promote-by-key` 统一为「否」(4123 行,审计 `cloud.role_catalog.demote`)。 **现在全平台混合态 = 0 组**(修复前 43 组:12 alicloud_intl + 31 aws)。顺带记一笔量到的事实:那 31 个键上员工自助 grant 只有 7 条(5 active),而 554 条是云侧已存在、被 grants_sync 镜像进来的 `discovered` 行 —— 统一为「否」不动任何既有授权,只影响之后从下拉框里新发起的申请。 **验证**:前端 `pnpm typecheck` + `pnpm lint`(13 道守门,含 i18n 三语 parity 与混排守卫)+ `pnpm test`(105 文件 / 1414 用例)全绿;后端一次变异验证如上。 > **2026-09-07 — feat(cmdb): 一个 `$0` 必须自己说清是「真的没花钱」还是「我们没取到账单」—— 三个 GCP 项目静默显示 $0 整 25 天（0 迁移 / 0 cron / 0 RBAC / 0 新 MCP 工具）** 用户在订阅详情页看到 `Digital BI` / `Digital Infra` 本月花费 `$0.00`，而近 6 月柱状图是 $2824 / $3042 / $3346 / $3757 / $1700 —— 他自己的判断是「我把它们挪到了带折扣券的账单里，所以实付是 0」，并顺带问：这个页面是给普通员工看的，本来就该显示没有折扣没有抵扣的钱吧？ **折扣口径这一半是对的，而且早就对了。** 抽屉默认 `measure='list'`，取 `CASE WHEN cost_bucket='usage' THEN COALESCE(amount_usd_list, amount_usd) ELSE 0`；2026-07 口径改造之后 GCP 的 usage 行存**税前毛额**，代金券 / CUD / 合同折扣全是独立负数行、落在非 usage 桶里被 `ELSE 0` 乘掉。生产数据逐月对过：Digital BI 5 月折前 $3,042 而实付 $1,196（$1,612 赠金 + CUD + 合同折扣），页面显示的正是 $3,042。**折扣券打不进这个数字**。 **真因是取数断流，不是口径。** 逐层查到源头：三个项目（含 `gcp-digital-bi-dev`）在 **2026-08-14** 被挪到账单账号 `0125F7-277DBE-14DC04`，而 GCP 集成 `config_public.billing_bq_table` 只列了旧账单账号的三张导出表。直接打 BQ 复核：这三张表里这三个项目的 `max(DATE(usage_start_time))` = **2026-08-13**，之后一行都没有；`gcp-digital-bi` 下的 `gcp_billing_v2` / `gcp_billing_detailed` 两个 dataset 里**也不存在**新账单账号的导出表，而 Helix 的 SA（`pch-resource-manager@gcp-digital-infra`）在 `gcloud billing accounts list` 里根本看不到这个新账号。所以 8 月那一格 `$1,700` 是被砍在 8/13 的整月（比 $0 更危险 —— 它看起来像个正常数字），9 月是零行。**同期同集成另外 34 个项目一路同步到 9/05**，另外 5 个也停了的项目（`greg-kubernetes` / `dbaas-key` / `dbaas-central` / `dbaas-staging` / `gcp-dm-dev`）经核对是 `billingEnabled: false`，那些 0 是真的。 **25 天零告警**，三道闸各自都有正当理由放过它：日环比尖刺告警要有「今天」才能比，`cost_chain_crosscheck` 是明细链路与日汇总链路互查而这次两条一起断，闲置扫描在「30 天一行都没有」时**刻意**弃权（分不清闲置和没数据）。页面上唯一的信号是 `summary.data_available`，而它对「真的没花钱」和「没取到账单」**都是 false** —— 读者只能猜。 新增 [`cost_coverage.py`](../../server/app/domains/cmdb/cost_coverage.py) 作为这个判断的唯一出处，`billing-detail` 响应多一个 `coverage` 块，五态：`complete`（$0 是真的）/ `gap`（同集成已到 X 而本订阅停在 Y，且它连续计费 ⇒ 低估约 `estimated_missing_usd`）/ `pipeline_stale`（整条链路滞后，**先判它** —— 否则一次云级故障把它下面几十个订阅一起标红）/ `no_history` / `indeterminate`。关键信号是**同集成新鲜度**：它到了今天就证明 BQ/API 那一跳是通的，于是同集成下某个订阅停在三周前只能是它自己的事。四个消费面（桌面抽屉、订阅详情总览、移动端、同名 MCP 工具）共用同一个响应，前端表述收在纯函数 [`costCoverage.ts`](../../web/src/lib/costCoverage.ts) 里（桌面与移动组件库不同，所以共享的是函数不是组件），三处措辞不可能各自漂移。旧的 `noFactsForMonth`（「本月暂无成本数据」）退为老响应的回落文案。 **两条有意的自我限制。** ① 「连续计费的订阅被真的关掉计费」与「导出表配漏了」在数据上形状**完全相同**（两条链路同源，没有第二个信源可复核），所以 `gap` 的文案只陈述观测到的事实并列出三种可能原因，不断言「我们取数失败了」；② 断续计费的订阅（不是每天都产生费用）缺几天是常态，对它判 `indeterminate` 而不是 `gap` —— 宁可说「判不了」，也不制造一个每天早上都在喊的信号。反过来，`complete` 且总额为 0 时页面会**主动说出**「本月确实没有花费，账单数据已同步到 X，每天都有账单行」—— 用户问题的另一半，不写出来读者仍然只能猜。 **验证**：[`test_cost_coverage.py`](../../server/tests/test_cmdb/test_cost_coverage.py) 11 条表驱动 + 4 条真 DB 端点（核心那条复现事故形状：同集成一个健康订阅同步到今天、一个停在上月 14 号，断的判 `gap` 且 `missing_days` / 估算金额精确，**健康的那个必须仍是 `complete`**）；[`costCoverage.test.ts`](../../web/src/lib/costCoverage.test.ts) 8 条。**做了变异验证**:把「同集成新鲜度」那一跳的过滤条件从 `integration_id` 改成 scope 过滤(最像的那个真实 bug)⇒ 端点层 2 红,纯函数层全绿 —— 这正是纯函数测试原理上看不见、必须落真 DB 的那一格。`pnpm lint / typecheck / test / build` + `tests/test_cmdb` 相关 39 条 + `tests/test_mcp*` 136 条全绿。 **仍需人工处理(不在本 PR 范围)**:新账单账号 `0125F7-277DBE-14DC04` 的 BigQuery 账单导出**尚未开启**,开启前 Helix 拿不到这三个项目 8/14 之后的账单;且 GCP 的 BQ 导出**不回填历史**,8/14 → 开启日这一段(折前约 $5k)只能从 Cloud Billing 报表或经销商发票另补。见 ROADMAP 未完成清单。 > **2026-09-07 — fix(cmdb): 云角色「默认下拉?」关掉的角色在下一个子账号上原样复活 —— 决定改记在 `(租户, role_key)` 上(迁移 623 / 0 cron / 0 RBAC / 0 新 MCP)** 用户的话:「这些明明我设置了不出现在下拉框里。怎么还在。」截图里两半互相矛盾:目录页 `DBaaS-Prod-Admin-Role` 的「默认下拉?」是**否**、覆盖 Scope **8/29**,而 申请云访问 的主角色下拉框里它就在第一屏。 **先量了再判**(直连生产 TiDB): | 事实 | 数 | |---|---| | 2026-06-11 的三条 `cloud.role_catalog.demote` 审计 | 每条 `rows_affected=**21**` | | 今天 10 个 `DBaaS-Prod-*` 角色键各自的状态 | 21 行关 / **8 行开**(`BaiLian`、`rds-secret` 是 25 关 / 4 开,demote 于 07-09) | | 那 8 行的 `first_seen_at` | **2026-06-13 … 08-24 —— 全部晚于 demote** | | 那 21 行的 `first_seen_at` | 全部 ≤ 2026-06-09 | `is_promoted` 是 `(integration, scope, role_key)` 上的列,而管理员在目录页做的决定是**租户级**的(`promote-by-key` 的整个用意就是「一次点击管住 29 个子账号」)。它只能改**点下去那一刻已经存在的行**;之后每个新发现的子账号由 `roles_sync` / 单 scope 预热插入**新行**,新行取驱动默认值 —— 七个云驱动对自定义 / CloudSSO 角色**一律** `is_promoted=True`(`alicloud_intl` 直接写死 True,azure/aliyun/tencent 是 `is_custom or key in promoted_keys`)。**所以这不是被同步覆盖,是被新行绕过。** **为什么三个月没人发现**:目录页把 `is_promoted` 按**跨 scope 一致值**上报(`promoted == total`),8/29 于是显示成「否」—— 和「全部关掉」长得一模一样。开关已经在「否」位,**再点是开**,页面上没有任何动作能表达「把剩下那 8 个也关掉」。写侧漏了持久化,读侧把漏掉的后果藏起来了。 **修法两半**: 1. **决定改记在 `(租户, role_key)` 上** —— `cmdb_cloud_roles.promotion_overridden_by_admin`(迁移 623,姿势抄既有的 `governance_overridden_by_admin`)。promote / demote(两个端点)置 1;**roles_sync 与单 scope 预热每次跑先读一次这张决定表**,拿它给新行播种,并把跨 scope 漂移的行重新盖回去(每个方向一条 Core UPDATE,日志 `roles_sync re-stamped N role row(s)`)。软删行一并纳入 —— 一条被 sweep 关掉、下次同步复活的行必须带着决定回来,而不是带着驱动默认值。「重置为默认」是唯一**清掉**这个标记的地方(它的语义本来就是「忘掉我的编辑」),而且它连软删行一起清 —— 只要留下一条带标记的软删行,同步就会继续重新应用这个刚被丢弃的决定,并在下次复活那行时把它带回来。 2. **把混合态说出来** —— 目录接口新增 `promotion_mixed`(`0 < promoted < total`),页面加「各 scope 不一致」筛选、行内黄色标签「N 个 scope 仍在显示」、以及一个 Popconfirm 的**「统一为否」**(单行 + 顶部横幅批量,分片 200 键以内)。 **回填只做能证明的那一半**。`is_custom=1 AND is_promoted=0` **一定**是管理员关的:七个驱动没有一个会让自定义角色以 `is_promoted=False` 插入,`重置为默认` 的目标值 `is_custom or key in defaults` 对自定义角色也恒为真 —— 没有非管理员写者能产出这个组合。命中 12 个 alicloud_intl 角色键(正是被报的那 12 个,260 行)+ 64 个 azure、11 个 gcp 自定义角色键(它们本来已经全 scope 一致,打标只是让决定变持久,重述会找到 0 行要改)。**发布后第一次 `roles_sync` 会把 108 行拉回「否」**(10 个 DBaaS 键各 9 行 = 8 个活跃子账号 + 1 个已软删的;`BaiLian` / `rds-secret` 各 5 行)—— 这个数是发布前对着生产只读算出来的,发布后可以拿它对账。**没回填的那一半**:31 个 AWS permission set 处于 32/100 的混合态,方向大概率也是「关」(2026-06-30 有两条 `rows_affected=72` 的 demote 审计),但 `is_custom=0` 的行「部分 scope 关着」在数据上和驱动默认值**分不开** —— 猜一个方向去改 100 行的授权可见性不是迁移该干的事,交给上面那个「统一为否」按钮,由管理员点一次。 **验证**:9 条新回归(`test_role_promotion_survives_new_scope_2026_09_07.py`),覆盖批量同步 / 单 scope 预热 / 已漂移行被拉回 / 重置为默认真的忘掉 / 目录报混合态 / **员工下拉端点 `GET /scopes/{id}/roles` 上那个角色真的不见了**。其中 3 条是**反向断言**(没做过决定的角色照旧取驱动默认值 / 重述不许碰没被决定的角色键 / 重置为默认连软删行一起清)—— 前两条守的是这次「谁有权写 `is_promoted`」的放宽,第三条是我自审时发现的真缺口:软删行上留一个标记就能让被丢弃的决定复活,变异验证当场证明它当时**没有任何测试覆盖**。七次变异逐个杀掉预期的那一条(去掉决定读取 → 4 红;去掉重述 → 只有「已漂移行」红;INSERT 改回驱动值 → 3 红;去掉 `promotion_mixed` → 目录那条红;决定泄漏到所有角色键 / 重述丢掉键过滤 / 重置漏软删行 → 各 1 红),恢复后 sha256 逐字节核对。既有 `test_role_curation_and_groups` 等 5 个文件 103 通过;`tests/test_cmdb` 在最终代码上 2167 通过(中途有一轮报 1 red,是 `test_lifecycle_gates_2026_07_31` 那条**读源码**的守卫 —— 我在它跑到一半时改了 `lifecycle_service.py` 上方两行,`inspect.getsource` 的行号窗口整体偏移;不动源码重跑全绿。教训:源码断言型测试在跑的时候不要编辑被它读的文件);mypy ratchet 1268=1268、alembic 单头 623、savepoint / tidb-parity / 定时任务 四道守卫绿;前端 `pnpm typecheck` + `pnpm lint`(含 i18n 三语 parity)绿。 > **2026-09-07 — fix(notifications+identity): 一次全员安全宣贯里 6 个人的飞书没送达 —— 一个真投递缺陷,加上「这个人是顾问还是正式员工」在全平台无处可看(0 迁移 / 0 cron / 0 API 契约变更 / 0 MCP)** CEO 诈骗宣贯发给 416 人,410 全通道送达,6 人 `partial`(邮件到了、飞书没到)。逐个查清,三类原因互不相同: | 类 | 人 | 真因 | |---|---|---| | 飞书上根本没有账号 | 1111 / akiko / kazumasa.takeshita / thanh.quach | 直连飞书 tenant API 核过:租户根部门 `member_count=449` 与 Helix 通讯录快照的 449 条 user 记录一致(名册完整),这四人在任何地址下都不存在。kazumasa 额外试过他在汇联易/AWS 里的 `kazumasa@`、两个 `.com.cn` 变体和日本手机号,全 miss。不是缺陷 | | 有飞书号但账号邮箱字段是空的 | julia | `user_id 6ga587cb` / `open_id ou_5d0156…`,在职,`email=""`。Helix 只有 `resolve_open_id_by_email` 一条解析路径,空邮箱永远查不到。同一根因让她在飞书通讯录同步里是 `matched_person_id=NULL` 的孤儿、坐席对账也数不到她。已直接把 `julia@pingcap.com` PATCH 进她的飞书账号(用户确认),`batch_get_id` 当场能解到她 | | 飞书侧一次性抖动 | anne.wu | `POST /im/v1/messages` 返回 `code 2200 Internal Error`。她 open_id 正常、有 feishu 登录身份、08-25/07-31/07-21 的卡片都送达过,60 天发件箱里 2200 只此一条 | **真缺陷在第三类,而且它跟这次宣贯无关**:`_deliver` 只要有一个通道成功就把行冻结在 `partial` + `next_attempt_at=NULL`,重试 worker 又把 `partial` 整个排除在池外 —— 于是**一次瞬时的飞书错误 = 那张卡片永久丢失**,一次尝试之后再无退避,而宣贯控制台把 `partial` 计作「送达」,那个人还被记成已触达。冻结对**永久**失败是对的(`open_id not found`:人不在通讯录,重试五次也变不出来),对瞬时失败是错的。现在这个区别写在 `next_attempt_at` 上:**armed = 回来重试,NULL = 终态**;判据收进一个 `retry_due_clause(now)`,worker 的 id 扫描与逐行复检共用它,两处不可能再漂移。`_deliver` 本就只发 `delivered_channels` 里没有的通道,所以重试只补飞书卡片、不会重发已送达的邮件。**存量 partial 行全带 NULL,一条都不会被唤醒**(它们的瞬时窗口早就过去了,重投等于送陈年通知)。 **这不是一次性事故。** 按新判据回扫近 60 天的 `partial` 行:**8 条**是瞬时失败被冻死在 `attempts=1` 的,平均每周一条 —— 2026-08-26 两条 `40003 Internal Error`(资产盘点提醒), 2026-07-16 一条 `9499 too many request`(云负责人半年确认),以及最刺眼的 **2026-08-22 03:00:01 同一秒五条 `Expecting value: line 1 column 1`**(飞书返回空 body): 模板是 `scheduled_job.failure`,也就是**告警系统自己的告警**,收件人是五个 IT 管理员(含用户本人)。 邮件都落了,所以「保底 webhook」按契约正确地没有触发 —— 但值班真正在看的那张飞书卡片被丢了, 而且再也没有重试。这 8 条全部带 NULL,不会被这次放宽唤醒(它们的瞬时窗口早就过去了), 它们的价值是证明这条链路每周都在静默掉卡片。 **第二件事是用户当场提的**:「在咱们系统里 某个人是顾问 外包还是正式员工 没有一个清晰的地方可以看到」——确实如此。`identity_persons.employee_type_code`(SF `EmpJob.customString25`)从 HRIS 同步建起来就在存,但 `web/src/` 里零引用,唯二的消费者是两张指向别处的翻译表(飞书 `employee_type` value-map、离职通知的两码白名单),用户详情页上离这个问题最近的是 RBAC「角色」标签 —— 它回答的是另一个问题,却因为这个问题没有位置而一直代班。新增 `app/identity/employee_types.py` 作为码→含义的唯一出处,**存 slug 不存标签**(SF 拥有词表,而且 2026-07-15 已经把 1074/1075 的标签对调过一次而码不变;标签落库那天就会静默反转)。落地四面:用户详情「用工类型」行、用户列表新列 + 多选筛选(`GET /users?employee_type=1073,1074`)、共享 `PersonFilterEditor` 新增维度(于是宣贯受众 / 同步范围 / 身份消费方都能按用工类型圈人)、`person_visibility` 三处白名单同步放行。**未映射的码渲染成原始码**而不是空格 —— 可见、可搜,HR 拿着它就能去问 SF。 顺带修了宣贯控制台:目标行以前只有一个 `partial` 标签,现在带上**哪个通道没送达**和厂商原话(`Feishu open_id not found for email …` vs `Feishu API error 2200`)—— 这次的诊断得手工查发件箱才能做出来,下次一眼可见。 **验证**:`test_partial_transient_retry_2026_09_07.py`(5 条)+ `test_employee_type_filter_2026_09_07.py`(19 条)。**两处防线各自做了变异验证**:去掉 `_deliver` 的 arming ⇒ 2 红;把 `partial` 从 `retry_due_clause` 摘掉 ⇒ 另 2 红 —— 两处冗余会互相遮蔽,只摘一处仍有测试是绿的,必须整条防线一起摘才看得清。`employee_type_codes` 同 PR 补进 5 个 `CandidatePerson` 构造点 —— **这里踩了一次**:五个里四个喂的是 ORM 对象,只有 `directory_service.resolve_in_scope_person_ids`(Directory/SCIM 拉取侧的授权边界)喂的是窄 `select(列, 列, …)` 的 Row,读一个没 select 的列直接 `AttributeError`,把整个对外人员面打挂(`test_people_github_api.py` 24 条全红,已补 select 列)。漏传是静默的、读窄 Row 是炸的,加字段时两种形状都要逐个核,并加了一条把它和 `presets.EMPLOYEE_TYPE_CODE_TO_FEISHU` 钉在一起的测试。生产侧已把 anne.wu 与 julia 的飞书卡片补发(只补飞书通道,邮件未重发)。 > **2026-09-07 — fix(cmdb): 同一个 Owner 筛选,管理员看到 7 个、员工看到 12 个 —— 员工侧云订阅目录漏了一条 scope_type 闸(0 迁移 / 0 API / 0 cron / 0 RBAC / 0 MCP)。** 用户在「云子账号 / 订阅」按 Owner=倪捷 筛出 **7** 行,在员工侧「我的云订阅」同一个 Owner 筛出 **12** 行。两处筛的是同一个字段(`owner_person_id`),差额来自两侧对 `scope_type` 的口径不一致。 直连生产核对(该 Owner 名下共 13 行):5 行 `legacy_billing_unit` + 1 行 `closed` 的 `azure_resource_group`,`13 - 5 - 1 = 7`(管理员),`13 - 1 = 12`(员工)—— 数字一分不差地对上。 - `GET /cmdb/scopes`(管理员)自迁移 466 起默认 `scope_type != legacy_billing_unit`,其 `requestable=true` 分支进一步收窄到 `TENANT_LEVEL_SCOPE_TYPES`; - `GET /cmdb/my-subscriptions?include_requestable=true` 里的 `_requestable_directory_rows()`(员工侧目录)**只**排了 `standalone_iam`,于是把成本归集行和 AOAI 资源组行当成可申请的云账号发给了每一个员工。 **比数字对不上更糟的是那颗按钮**:这些行都是 `environment='dev'`,所以 `requestable` 算出来是 true —— 员工看到「快速申请」,点下去被 `_refuse_ungrantable_scope_type` 以 `CLOUD_SCOPE_NOT_GRANTABLE` 拒掉。正是 CLAUDE.md 里「确认后才拒绝的卡片」那一类。生产面:28 行 `legacy_billing_unit`(12 个 Owner)+ 2 行 `azure_resource_group`,对**每个**员工可见;所幸至今无人对它们发起过 grant。 修法**不是给目录打一个补丁**。顺着这一类往下查,「这个人负责哪些 scope」在 5 个模块里被写了 **7 遍**,对同一个人给出 **3 种**答案: | 界面 | 修复前的谓词 | |---|---| | 员工可申请目录 | `!= standalone_iam` | | 离职 blocker 扫描 | 只有 `deleted_at IS NULL` | | 离职预览 | 只有 `deleted_at IS NULL` | | 转岗 / 角色变更持有物 | 只有 `deleted_at IS NULL` | | 经理「团队云资产」**列表** | 只有 `deleted_at IS NULL` | | 经理「团队云资产」**计数徽章** | 只有 `deleted_at IS NULL` | | 离职残留对账 | closed + decommissioned(**最正确的那一份**) | | 归属完整性(「没人负责」透镜) | closed + decommissioned + 排除 GCP billing | 已产生的真实代价(生产实测,不是假设): - 离职 blocker 扫描对 `azure_resource_group` / `legacy_billing_unit` 也建了 `cloud_scope_owner` blocker。 🔴 **更正(发布后核对生产得出)**:本段初版写的是「2 条**谁也解不掉**的 blocker,**卡住离职流程**,需 operator 手工跳过」—— **三点都不成立**。实测全库 `cloud_scope_owner` blocker 共 16 条**全部 resolved**(11 transferred / 5 revoked_manual),**全库未解决 blocker 数为 0**,相关流程全 `completed`;我点名的两条都由 T+0 `force_transfer` 自动解决(15 分钟 / 3 天)。且其中一条建于 2026-08-05,**当时 scope 还是合法的 `standalone_iam`**,是迁移 466 在 8-12 重定型后它才回头显得像垃圾 —— 创建那一刻它是对的。真实代价是 force-transfer 把成本归集行/已下线资源组的「负责人」转给了接手人:无意义的归属 churn 与噪声,不是卡流程。修复消除的是未来同类噪声(库里还有 22 条 closed-but-owned scope)。 - 「归属完整性」透镜的 **cloud_scope 输出 8 行,8 行全是 `legacy_billing_unit`** —— 也就是这个「谁来负责这个没人负责的东西」透镜当前 **100% 是误报**。(初版写 7 行:漏算了「owner 存在但已离职」那一类,该透镜同时报 NULL owner 与非在职 owner;按真实谓词复算是 8。)迁移 466 给这些行定型正是为了让它们不需要 owner,所以管理员点开也永远清不掉,和它旁边那条 GCP billing account 排除项防的是同一种「永久假阳」。 - 员工「我的云订阅」多出 30 行(28 `legacy_billing_unit` + 2 `azure_resource_group`),每行还带一颗点下去必被拒的「快速申请」。 现在收敛成 `cmdb/models.py` 里的**两个**具名谓词,六处全部改为调用: - `owner_governed_scope_criteria()` —— 「拥有它是一份活的、可交接的责任吗」:`deleted_at IS NULL` + `status != closed` + `decommissioned_at IS NULL` + `scope_type IN TENANT_LEVEL_SCOPE_TYPES`。用于离职 blocker / 离职预览 / 转岗持有物 / 经理团队视图(列表**和**徽章)/ 离职残留对账 / 归属完整性透镜(后者在其上再叠自己的两条排除:GCP billing account、阿里云 RD master)。 - `employee_directory_scope_criteria()` —— 「能不能作为云账号展示给员工去申请」:`active` + `TENANT_LEVEL_SCOPE_TYPES - {standalone_iam}`。两处与上面刻意不同的地方都在 docstring 里写明了理由(suspended 不该拿去申请;`standalone_iam` 是页面路由决定,不是可授权性决定),免得下一个人以为是漂移又「顺手统一」掉。 **为什么是函数而不是六份 WHERE**:谓词的副本会静默漂移,因为它们互相不一致时没有任何东西会失败。新增 `test_scope_visibility_contract.py` 用同一份 fixture(1 个真账号 + closed / legacy / RG 三种真实垃圾形状)同时驱动全部七个界面,让它们**一起**红。变异验证做了两轮:把共享谓词还原成 `deleted_at IS NULL`,四个跨域用例同时转红;单独把归属完整性透镜改回手写谓词,对应用例转红。恢复均即绿。 管理员台账**故意**比员工宽,这一点被写成断言而不是等式:契约是**包含**(`employee ⊆ admin`),不是相等 —— 管理员仍然看得到 `azure_resource_group`(真实 Azure 对象,绑着 API Key)和 `standalone_iam`,`legacy_billing_unit` 也仍可用 `include_legacy_billing` 调出来。被永久钉死的是**用户报告的那个方向**:员工页面显示出管理员自己看不到的行。 生产可见性不收窄:真实子账号、prod 行(仍然「可发现但不可申请」)、GCP billing account 行为全部不变。 > **2026-09-07 — fix(security_awareness): 重复发送闸的窗口按「两次触达的时刻」算,不是按「孪生行多久前被碰过」(#3492 的自审续修,0 迁移)** #3492 的 `_refuse_duplicate_send` 第一版把孪生活动的 `updated_at` 和 `now` 比,两头都错: | 假阳性 | 形状 | |---|---| | 改个名字就能封住半小时 | `updated_at` 会因为**跟发送无关**的原因跳动 —— 改标题、改截止日期。一个三个月前发过的活动今天被重命名一次,就在接下来 30 分钟里挡住一个合法的新活动 | | 排下周反而被拒 | 同素材同受众、**排在下周**的第二波是明摆着故意的(调度器收一个日期就是为了这个),却因为「上一波是 20 分钟前发的」被 409 | 改成比**两次触达的时刻**(`sent_at`,还没发的用 `scheduled_at`),窗口不变(30 分钟)。顺带把 `scheduled` 也纳入孪生状态 —— 「同一个 09:00 上膛了两次」是同一类重复发送,而按状态过滤的旧版**原理上看不见**(两个都还没发出去)。错误文案区分「已发过」和「已上膛」。 三条回归钉住这三点(排下周放行 / 同一小时上膛两次 409 / 改名不封新活动),`test_security_awareness` 170 通过。 > **2026-09-07 — refactor(web): 按用户指示撤回上一轮的两次「折叠」,删掉「常用」轨;顺手把 `getOpenKeys` 改成读菜单树(0 迁移 / 0 API / 0 cron / 0 RBAC / 0 MCP / 0 页面删除 / 0 路由改动)** 上一轮(2026-09-06 第八轮)重组管理端侧栏时,我把两组折进了邻居,并加了一条按人统计的「常用」轨。用户三条指示,全部照办: | 指示 | 之前 | 现在 | |---|---|---| | 「常用不需要 删除了」 | 侧栏顶部一条按访问次数排序的快捷轨 | 整条删除(`menu/recentPages.ts` + 测试 + `localStorage` 读写 + `MainLayout` 里的 rail / `labelForPath` / `reachableKeys` / `recordVisit`),三语各删 `nav.recentlyUsed` | | 「数据仓库单独拿出来,不要和云资源混在一起」 | 数据仓库 3 项并入**云与数据**(11 项) | **数据仓库**恢复为一级组(3 项),云资产回到原来的 8 项与原标签 | | 「人员与身份还是分开,不要合在一起」 | 身份与 SSO 6 项并入**人员与身份**(11 项) | **用户管理**(4 项)与**身份与认证**(7 项)各自成组 | **折叠撤回,拆分保留。** 上一轮真正解决问题的是把 **平台运维**(健康台 / 对账 / 定时任务 / 审计)和 **IT 服务**(服务台 / 知识库 / 助手评测 / 流程审批)从两个杂物组里拆出来 —— 那两组此前各自在干三种活。这次只撤销「折叠」这一半:一级从 14 行变 16 行。**规格里现在没有 `DISSOLVED` 也没有 `RELABEL` 了** —— `regroup.ts` 只会重排和重新填充分组,不再解散分组,标签一律由菜单构建器自己给。 **邮件组跟着身份走,没有跟着回 HR 工具。** 上一轮把它移出 HR 工具的理由(邮件组不是 HR;动态邮件组的成员资格直接按部门/职级规则算,是目录对象)与这次的撤回无关,所以它落在**身份与认证**里而不是回到 8 项的 HR 工具。 🔴 **顺手修掉一个上一轮遗留的真缺陷:`getOpenKeys` 把分组用手抄了一遍。** 它是一串 `pathname.startsWith(...) → return ['组名']` 的分支,写于菜单还是 1,500 行 JSX、测试里跑不起来的年代。上一轮页面换了组,**这些分支一条都没跟着改**:深链到 `/admin/audit` 展开的是**系统配置** —— 一个已经不含它的组;`/admin/scheduled-jobs` 同理;`/admin/support`、`/admin/health`、`/admin/reconciliation`、`/admin/assistant-eval`、`/admin/helpdesk-analytics` 压根没有分支,落地时侧栏整个是收起的、选中项看不见。现在先从**实际渲染的那棵树**里查这一页的祖先链(`groupChainFor`),查到就用;查不到再走那串分支 —— 它们继续服务那些**本来就没有菜单项**的路径(`/admin/leaver-blocked`、`/admin/connectors`、`/compliance/*`、`/auditor/*` 等),那些仍然需要手写映射。这样「页面换组 → 展开错组」这一类漂移从根上消失了。 **验证**:`pnpm typecheck`(`tsc -b`,不是空转的 `tsc --noEmit`)/ `pnpm lint`(eslint + 13 道守门,含 i18n 三语 parity —— 删 key 要三个包同步,否则这道闸会红)/ `pnpm test`(105 文件 1414 用例)全绿。重组测试同步改成断言**没有任何分组被解散**(逐个核对构建器产出的每一组仍是一级行,并显式点名 `data-warehouse` 与 `identity-sso-group`),行数断言从「与重组前相等」改成「构建器行数 + 拆出的组数」。跑起来把重组后的整棵树打印出来核对过:16 个一级组,数据仓库与身份与认证各自独立,`/admin/email-groups/groups` 在身份组内,叶子集合与重组前逐一相同。 > **2026-09-07 — fix(security_awareness): 第一次全员宣贯(416 人)暴露的四个缺陷,全部只在受众足够大时才出现(0 迁移 / 0 新 cron / 0 新 API / 0 新 MCP / 0 新 RBAC)** 用户点了「发送给 416 人」,然后:**抽屉没关、自己也没收到**,问的是「这个是有 bug 吗 不能多次打扰到用户 处理这种会发员工发消息的都要保证这个原则」。 **先量了再判**。直连生产 TiDB,当时那一刻:1 个活动、416 条台账(person 重复行 **0**)、416 条 outbox(收件人重复条数 **0**)、其中 191 已投递 / 5 部分 / 1 投递中 / 219 待投,`last_del` 就在查询的那一秒 —— **不是重复发送,是它还在发**。发送最终干净跑完(03:06:28 → 03:21:57,**15.5 分钟**,410 delivered + 6 partial,零重复;6 条 partial 是 `akiko@` / `1111@` 这类账号飞书查不到 open_id,邮件已送达)。用户没收到是因为投递按 work_email 字母序、轮到 `shuai.feng@` 还没到。抽屉没关是因为 nginx `/api/` 的 `proxy_read_timeout` 是 **300s**,浏览器在第 5 分钟吃了 504,而后端协程没被取消、继续在发。 四个缺陷,一个 PR 全关: | # | 缺陷 | 后果 | |---|---|---| | 1 | `/send-now` 在**请求内** await 整段 fan-out(416 人 × 2 渠道 ≈ 832 次外部调用) | 必然超过任何 HTTP 超时。管理员拿到失败 toast、发送其实在跑,而**他的下一步动作才是真正的风险**:抽屉是 `destroyOnHidden`,重开再点走的是 `create` 不是重试 ⇒ 第二个活动 + 416 份重复必读 | | 2 | 状态在 fan-out **之后**才翻 `sent` | 每个员工面都闸在 `status=='sent'`,于是在整段 drain 期间**卡片已到手的人打开素材看不到确认按钮**,`acknowledge` 回 409 `SECAW_CAMPAIGN_NOT_OPEN`。实测 15.5 分钟里 264 个人握着一张要他们确认、平台却不让确认的卡片,`opened_at` 也一并丢了(同样闸在 live 状态上)。用户当轮的第二个反馈「我其实已经确认过了无法再次确认了」就是这一条 —— 生产上他 03:19:32 打开素材,而状态直到 03:21:57 才落定 | | 3 | `queued_at` / `last_sent_at` 是 drain 跑完后的一条**批量 UPDATE** | drain 死在 90% 时 416 行全是空的:漏斗读 0,而「谁已经发过」无从判断 ⇒ 恢复只能重走全体 | | 4 | 补偿是 `except Exception`,且无条件把状态放回 `scheduled` | `CancelledError` 是 **BaseException**(部署换容器 / 客户端断连,正是真实会发生的那种)⇒ 跳过补偿、活动永久卡在 `sending`,而 `dispatch_due` 只捞 `scheduled`、全仓没有第二处移出 `sending` ⇒ 覆盖率冻在 0、`close()` 永远拒绝。反过来,一次 drain 阶段的失败会把已经 `sent` 的活动放回 `scheduled` ⇒ **下一跳重走全体受众、每人再发一份** | 修法: 1. **`/send-now` 改 202**,只 `schedule()` + commit,fan-out 交给 `core.background.spawn` 上的 `run_campaign_dispatch_in_background`(自带 session + `innodb_lock_wait_timeout=120`,形状抄资产盘点的 `run_start_notifications_in_background`)。**丢任务不丢发送**:活动先 commit 成 `scheduled` 再 spawn,十分钟一跳的 `campaign_dispatch` 是地板。**`/resend`(催办)同样改 202** —— 上线第一天「还没确认的人」就是绝大多数受众,那是同样大小的扇出;但**拒绝仍然同步**(新 `require_resendable`):202 之后在后台 409,等于一次静默无效的点击。前端:抽屉 `closable={!saving}` + `maskClosable={false}` + 取消按钮 `disabled`,toast 从「已发送」改成「已发出 —— 正在逐人投递,漏斗数字会在几分钟内补齐」(三语)。 2. **状态在 phase 1(台账落库)之后立刻落定** `sent` + `sent_at`,审计行也移到这里(崩了也留下痕迹)。416 人的 phase 1 是 ~20 秒,那个「不能确认」的窗口从 15.5 分钟缩到 20 秒。 3. **逐人落戳**,靠 `fanout.enqueue_then_drain` 新增的 `on_enqueued(env, outbox_id)` 钩子 —— 在该行 commit **之前**调用,所以戳和 outbox 行同一个事务。原子性是重点:分开写会出现「有行没戳」或反之,而拿戳当「谁还没发」就会漏发或重发。 4. **`except BaseException`**(原样重抛),**只把还停在 `sending` 的**放回 `scheduled`;`dispatch_due` 每跳先扫 `sending AND updated_at < now-15min` 重新上膛,恢复跑只发 `queued_at IS NULL` 的人且**不**加 `resend_count`。另加 `_refuse_duplicate_send`:同素材+同受众+同强度+同完成口径+同渠道、30 分钟内已发过 ⇒ 409 并报出上一个活动的名字;**刻意不把活动名算进指纹**(算进去等于「你有没有顺手改标题」),故意的第二波传 `force=true`。`str(CancelledError())` 是空串,所以理由回落到类名 —— 否则「取消」和「干净跑完」在控制台里长得一样。 **顺带修掉的一处共享原语的不诚实**:`enqueue_then_drain` 的 `failed` 原来**只数投递失败**,phase 1 写不进去的那些人只反映在更小的 `enqueued` 上 —— 于是 4 个人的扇出会返回 `{"enqueued": 3, "delivered": 3, "failed": 0}`,只有想到「拿 `enqueued` 和自己传进去的列表长度相减」的调用方才看得出丢了人,而全仓只有 `me_universe.wrapped_push` 一处真的这么减了(其余全没有)。现在 `enqueued + failed == len(envelopes)` 恒成立,`wrapped_push` 那行手写的减法同 PR 去掉(否则双数)。这条是被新加的宣贯测试逼出来的:`last_dispatch_error` 读的就是 `failed`,不改的话「有人没入队」永远不会写进活动的失败原因。 **验证**:`tests/test_security_awareness` 166 通过 + `tests/test_notifications` 全绿(含 3 条新加在 `test_fanout_rollback_revive.py` 的 `on_enqueued` 契约测试)。新增 8 条回归,**八个变异逐一验过**(状态翻转移回 drain 之后 / `BaseException` 改回 `Exception` / 去掉 `already_queued` 过滤 / 去掉 stale 自愈 / 去掉重复闸 / drain 失败又去 re-arm / `send-now` 改回请求内 await / `on_enqueued` 不调用)—— 每一个都让对应用例转红。顺带两条测试侧的教训写进 PLATFORM:① 这个套件的 fan-out 替身必须履行 `on_enqueued` 契约,`AsyncMock(return_value={...})` 会让台账全空;并查出一条**自证式断言** —— `_fanout_patch(enqueued=2)` 喂进去的 2 又被 `assert employee_pushes == 2` 读回来,而当时库里只有 1 个人,那条断言在任何受众规模下都成立(含 0),已改成两个真人 + 断言 `outstanding == 2`。② 202 化之后 spawn 出来的任务会和每条断言赛跑(实测 27 个用例红),套件改用 autouse fixture 把 `spawn` 换成记录器、由 `conftest.send_now` 显式驱动两半。 **顺带清掉的生产数据**:按用户要求删除两个 `【测试】/【测试二】` 活动(各 1 条台账、均已确认)。API 刻意拒绝删除有台账的活动(台账是证据),所以走直连 TiDB 一次性删除 —— 先把两行 + 台账 dump 成 JSON 备份,再在同一个事务里补两条 `security_awareness.campaign.delete` 审计行,然后删。它们 `status='closed'` 而 `COUNTED_STATUSES` 含 closed,所以本来会一直挂在合规覆盖率报告里。 > **2026-09-07 — fix(data-access): 个人与 SA 自助申请统一为 Owner-only 审批（0 migration / 0 API / 0 cron / 0 RBAC / 0 MCP）。** 个人申请的仓库模板已是 Owner-only，本次补齐 SA：删除 `requester_line_manager_review` 的定义节点、Helix mapping、推荐审批顺序和三语节点文本，只留下动态 `data_owner_review`；同步三语数仓指引与帮助。正常 Owner 批准后继续由原 callback 生成 binding/effect、scheduler 自动授权，不添加经理、工作负载经理或 SA 技术负责人审批。退役的 Group 新申请不重开、历史 mapping 不改，旧实例不伪造批准。回归直接检查两种自助流程最终构建的 Feishu POST payload、repo mapping 与运行时 mapping 一致，且没有任何额外审批节点。**发布边界**：代码合并本身不会修改飞书生产模板；仍须发布/readback 两种 definition 并 upsert 对应 mapping，历史经理节点上的在途单需单独处理。 > **2026-09-07 — fix(hr): 邮箱名对账上线至今在生产上只报过一条,而那一条是误报 —— 三层同修 + 把脏数据从 IT 的收件箱搬回 HR 的看板(0 迁移)** 用户收到一张卡:「Koji Betsuyaku — koji.betsuyaku@pingcap.com → Koji Betsuyaku@,他们的 Google 账号已经建好了,请去改 primaryEmail」。用户的问题是「这是什么意思 为什么会有这个问题」,然后是「你来彻底解决,不要有误报」。 **先量了再修**。直连生产 TiDB:574 人里 36 人填了 `hris_email_name`,35 条是规范的 `名.姓`,**判为不一致的只有 P01574 一条**。也就是说这个每天 08:20 的告警自上线以来的全部产出 = 1 条 = 1 条误报,而入职日 2026-06-08 落在 180 天窗口里,它还会再响 89 天。 | | | |---|---| | SF `PerPersonal.customString4` | `'Koji Betsuyaku'` —— HR 填的是**姓名**,不是邮箱名 | | 实际 `work_email` | `koji.betsuyaku@pingcap.com` —— **本来就是对的** | | 老派生算出的「应为」 | `kojibetsuyaku`(空格与其它非字母一起被 `_sanitize_token` 删掉) | | 卡片上打印的目标 | `→ Koji Betsuyaku@` —— 带空格、带大写、没有域名,连合法地址都不是 | 卡片在叫 IT 把一个正确地址改成一个没人想要的地址。**三层一起修,任何一层单独都不够**: 1. **分隔符语义**(`_local_part_from_hris_email`)—— 空格/下划线是名字分隔符,折成点:`Koji Betsuyaku` → `koji.betsuyaku`,正是 PR #677 定的 `名.姓`。这一层让 P01574 **当场收敛,零改名**,并且让未来任何一个「HR 填了带空格的名字」的新人在建号那一刻就拿到对的地址(老行为会铸 `kojibetsuyaku@`)。3 段以上的显示名(`Nicholas Dakota Muniz`)猜不出哪个是姓,直接弃用回落到权威的 firstName/lastName 派生 —— 比铸 `nicholasdakotamuniz@` 强。 2. **告警谓词**(新 `_spelling_variant`)—— 只抑制两种、且**刻意只有两种**:① 字母相同只差标点(`kojibetsuyaku` vs `koji.betsuyaku`,改名什么也换不来、还拿一个能用的地址去赌);② 去重后缀(`wei.chen01` —— 平地址属于别人,HR 的值永远匹配不上,**改名根本不可能**)。两者落在 run summary 的 `spelling_variants` 桶里(看得见、不进任何人的收件箱),只有「真的是另一个名字」(P10026:HR 要 `nick.muniz`、邮箱是 `nicholas.muniz`)才 page。这一层不依赖第一层猜对分隔符 —— 老代码铸出来的那些存量行只要字母相同就走不到告警。 **自审时砍掉了我自己写的第三条规则(词序)**:第一版把 `chen.wei` 对上 `wei.chen` 也一起抑制了,但生产上从没出现过这个形状 —— 而在 `名.姓` 约定下两者必有一个是错的,那是要人来判的事。顺手按模式铺开就会静默吞掉一类真发现,已改成**照样 page** 并配了钉死它的测试。 3. **卡片说人话** —— 打印真正会铸出来的完整地址(`→ nick.muniz@pingcap.com`),HR 的原始值降级成括号里的上下文(`(SF: 'Nick Muniz')`),方便顺手去 SF 把字段改对。 **顺带查出并修掉的两个真缺陷**: | 缺陷 | 后果 | |---|---| | `reserve` 返回 `skipped` 被无条件记进 `re_reserved` | `reserve_work_email_for` 有好几个**永久性**良性跳过理由(HR 的 P99XX 测试号段、purged 墓碑、`auto_create_on_hire` 关、该角色没配域名),于是一个永远修不成的行**每天被记成一次成功修复**。改记新的 `skipped` 桶;刻意不进 `errors` —— handler 见 errors 就判 run failed,为 HR 自己的测试记录每天红一次是另一种噪声 | | `_cap_local_part` 单 token 超长时返回 `.aaaa…` | 以点开头的非法地址。老测试只断言长度,看不见内容 | **SF 里那个脏值本身**不再由 IT 顶着:新增数据质量发现 `hris_email_name_malformed`(**low**,不 page 任何人)把字段摆到 HR 的 `/admin/identity/data-quality` 面板上,HR 改完下次扫描自动 resolve。判据是**往返**而不是坏字符黑名单 —— 把存值过一遍 provisioner 自己的派生、问它有没有原样活下来,这样检查永远不会和被检查的东西不一致(正是对账注释里警告过的那个失败模式),也不需要维护一张跟着清洗函数漂移的字符表。`usable=false` 表示 Helix 完全弃用了 HR 的意图,`usable=true` 表示地址对但字段脏。生产 36 条里那 35 条规范值一条发现都不产出(有测试钉住)。 **验证**:新增 `test_email_name_display_name_2026_09_07.py`(21 条,含生产那一行的原样复现)。**六个变异逐一验过**——去掉空格折点、`_spelling_variant` 永返 None、卡片改回打印原始值、`skipped` 又记成 `re_reserved`、恢复前导点、探测器不挂进 `_detect_all` —— 每一个都让对应测试转红(最后那条尤其重要:直接调探测器全绿,证明不了它被扫描调到)。既有 `test_reconcile_compares_against_what_would_actually_be_minted` 的期望值随派生规则一起更新(`Nick Muniz` 现在收敛到 `nick.muniz@`),它守的「一遍就收敛、不许每晚重跑」由新文件里的两轮 run 显式钉住。 > **2026-09-07 — fix(data-access): 已审批 Service Account 授权不再依赖预登记白名单（0 migration / 0 API / 0 cron / 0 RBAC / 0 MCP）。** 移除 `service_account_apply_principal_allowlist` 的解析与 reconciler 拦截；旧配置无论缺失、空值或格式异常都不再参与授权判定，下一次 apply-mode config merge 一并清掉历史 principal/dataset allowlist。保留 integration apply、SA apply 两个显式开关、正常审批生成 binding/effect、当前资源 active/requestable/owner-resolved 与精确 locator 检查；撤销继续要求 revoked binding，Provider writer、etag、精确 `serviceAccount:` + `dataViewer` 和审计不变。回归覆盖首次输入 SA 邮箱→待批零写入→审批→定时执行→精确 dataset/table IAM→再次 tick 零重放，以及旧配置兼容和保留的关闭/资源失效闸。生产只读排查发现两笔已批 SA 申请共 14 项被旧名单挡住；按用户授权通过既有 reconciler 定点补齐，独立 BigQuery 回查 14/14 存在、两笔请求及 14 条 effect 均 `applied`，未扩大生产持久化白名单。代码修复需随 PR 发布；发布后其他符合条件的历史 pending/retryable SA effect 会由既有 scheduler 自动执行。 > **2026-09-07 — chore(web): 数据仓库生命周期演示整体下线(纯前端删除;0 后端 / 0 迁移 / 0 API / 0 cron / 0 RBAC / 0 MCP)。** 按用户指示删掉 `/my/data-warehouse/lifecycle-demo/*` 与侧边栏那个 **数据仓库演示** 一级分组:`web/src/pages/dataWarehouse/lifecycle/` 全目录(27 文件,含 3 个自带的 vitest 文件)、App.tsx 的 lazy 导入与通配路由、MainLayout 的菜单 splice 注入 + 调色板 demoHref 分支 + `activePath` / `getOpenKeys` / 菜单 onClick 三处 DEMO_PATH 分支 + `warehouseDemoBoundaryKey` 的 ErrorBoundary key(回归为 `location.pathname`,那条「演示详情页共用一个会话所以不能按 pathname 重挂」的例外随演示一起消失)、7 个只服务于演示图标的 antd icon 导入、三语各 551 条 `dwDemo.*` key(zh-CN / en-US / ja-JP 同步删,parity guard 绿)。**这个演示当初就是「只读复用既有 GET + 内存态模拟」,所以下线不回收任何服务端资产、不动任何真实数据。** 刻意**未**触碰同样带 warehouse / lifecycle 字样的官方面:`/my/data-warehouse` 指引页、`/admin/data-warehouse` 总览 / grants / access-history、`DataAccessGrantLifecyclePage`、`server/app/domains/data_access/lifecycle*`、手册第 15 篇 —— 演示的唯一识别特征是 `dataWarehouse/lifecycle/` 目录 + `lifecycle-demo` 路径段 + `dwDemo.` key 前缀,靠「warehouse」一个词去删会连坐真功能。四道前端闸:`pnpm typecheck` / `pnpm lint`(含 i18n parity、dynamic-namespace、internal-link 等 14 个 guard)/ `pnpm test`(106 文件 1420 用例)/ `pnpm build` 全绿;i18n 包体各减约 1.9 万行来源的 551 条。文档侧同 PR 清理:删 `docs/testing/data-warehouse-lifecycle-demo.md`、删 PLATFORM.md「Warehouse lifecycle presentation boundary」整节、删 ROADMAP 的 V3/V4 两条 current-state 条目、DECISIONS 追加一条作废 2026-08-31 那两条演示 ADR 的新 ADR(历史保留,但标明其描述的代码已不存在)。 > **2026-09-07 — fix(identity_sync): 一条「google-dept: failed」的告警,拆出三个叠在同一个状态标签上的缺陷(0 迁移 / 0 cron / 0 API / 0 MCP)** 收到的 P2 全文只有这么多: ``` identity_sync.dispatch: 1 due target(s) failed this tick; first errors: google-dept: failed ``` 没有人名,没有原因。查生产 TiDB:那一跑(2026-09-07 01:00:57)`persons_in_scope=411, skipped=410, failed=1`,`error_message` 是 **NULL**;真正的原因一直躺在同一行的 `result_summary.errors[0]` 里 —— `chunlin.zhuang@pingcap.com: RefreshError: ('unauthorized_client: …')`。8 分钟后的下一跑 411 人全绿,自愈。 三个缺陷,分别修在三处。 ## 一、诊断在库里,但没写进任何人读的那一列 按人失败的 sweep **从不 raise**,所以 `_finalise_run` 拿到的是 `error_message=None`。而下游三个消费方**只**读这一列:`run_due_targets` 拼 `error_message or 'failed'`(就是上面那条告警的正文)、`alert_notifier` 把它渲染成卡片的错误行(空白)、`compute_failure_signature` 拿它算去重签名 —— 于是**同一目标上所有按人失败共用同一个签名**,第二种、原因完全不同的失败会被当成第一种的重复而静音。 现在按人失败也合成 `error_message`(前 3 条,压成一行 —— 三个消费方都只取第一行,嵌进去一个换行等于把消息截回没用),跟 2026-07 就有的 dept-phase 合成走同一段代码。 ## 二、「写成功」不等于「调通了」 `_sweep` 的状态判定把 `created+updated+deactivated+deleted == 0` 读作「目标挂了」(`failed`)。可**读-比对型 runner 稳态下本来就一个字都不写**:那一跑 `google-dept` 对 122 人做了 GET → 比对 customSchemas → 已一致 → `skipped`,其余 288 人 hash-skip,只有 1 人撞了瞬时 `unauthorized_client`。**122 次成功的 Google API 调用**换来一句「目标 DOWN」+ P2。 区别在于 **runner 返回的 `skipped` 是厂商答复过的往返,hash-skip 一个 HTTP 都没发**。新计数器 `RunSummary.verified_skipped` 只数前者,proof of life 改成 `created+updated+deactivated+deleted+verified_skipped`。 **2026-08-14 `aws-ai` 凭据吊销那一跑仍判 `failed`** —— 不是推理,是生产取证:那一跑记了 127 条 failed run_item、**0 条 skipped run_item**(282 次全是 hash-skip,压根没进 runner),`verified_skipped=0`。90 天回放里只有 2 跑会翻转,都是本次这个形状(都是 google-dept)。 ## 三、一个状态标签同时被当成「要不要告警」和「要不要补跑」 `partial` 之前既不进 `ran_failed`(dispatcher 不 raise),也不触发当日重试(游标直接推到明天)。于是「目标活着、某个人没同步上」这一类:**没人被叫醒,而且那个人的修复还要再等 24 小时** —— 正是当初写 outcome-aware 重排策略要消灭的那个 24 小时。 `alert_recipient_ids` 撑不起这个兜底:生产 12 个目标**全是空**,且按设计没有管理员 fallback(DECISIONS 2026-06-19)。自动化异常台账确实会收下这条失败 run_item 并派给 owner,但那是采集节拍上的复核队列,是后续、不是警报。 现在 `_RUN_STATUSES_WITH_FAILURES = ("failed", "partial")` 一个谓词同时驱动两处,并与 `alert_notifier._ALERTING_STATUSES` 同集合(有测试断言二者相等 —— 两个模块循环依赖,常量只能各写一份,正是会漂的那种成对)。 ## 验证 ```bash cd server && PYTEST_XDIST_WORKER=<你的库名> .venv/bin/python -m pytest tests/test_identity_sync -q ``` 887 → 892 passed。三处改动**逐个做了变异验证**(把每一处改回旧行为,确认对应用例当场变红,再改回来):去掉 error_message 合成 → 3 条红;dispatcher 闸退回 `failed`-only → 1 条红;重排退回 `status in ("ok","partial")` 前进 → 1 条红。 新增 [`test_item_failure_is_diagnosable_2026_09_07.py`](../server/tests/test_identity_sync/test_item_failure_is_diagnosable_2026_09_07.py);[`test_credential_outage_run_status_2026_08_14.py`](../server/tests/test_identity_sync/test_credential_outage_run_status_2026_08_14.py) 现在对写两个方向的不变量。 其中 dispatch 那条用例**跑真的 `run_due_targets`**。既有那条用例把 `run_due_targets` 整个 monkeypatch 掉、手工喂一个 `ran_failed` 列表进去 —— 那只能证明「非空列表会让 handler raise」,**永远证明不了列表会被填上**,而这次坏掉的正是填列表的那一行。 ## 预期的生产可见变化 - `partial` 跑会开始触达 IT(近 60 天全目标合计约 11 跑),每条带诊断正文,且 scheduled-job 通知器按签名去重,所以长期不变的同一个失败只 page 一次。 - `partial` 跑会占用当日重试预算(5/10/20/40/60 分钟、共 5 次 —— 已有上限,没有放宽)。 - `google-dept` 这类稳态跑的红点会变黄:`success_rate` 口径是 `ok / (ok+partial+failed)`,分子分母都不含 partial 的迁移,**成功率数字不受影响**。 > **2026-09-06(第十轮)— fix(txn): 把上一轮自己写下的「闸有个盲区、留着没扩」真的扩了 —— 而扩闸当场证伪了我上一轮的一句断言(0 迁移)** 上一轮结尾我列了三件「看见了但没修」的事。用户的回复是「全都修复了 不要遗留问题」。这一轮把它们全部关掉,过程中又发现两个真缺陷,其中一个**推翻了我上一轮写进 CHANGELOG 和代码注释的一句话**。 ## 一、闸的盲区补上了,并且是**验证过**补上的 `check_savepoint_isolation.py` 的过程间规则只匹配 `f(db, ...)` —— 第一个位置参数是 session。本仓最常用的形状 `ProvisioningService(db).retry_task(task_id)` 它看不见,session 进的是**构造器**。上一轮的第 4/5 条缺陷就是从这里过去的。 现在加了「构造器注入」这一条:`Service(db).method(...)` 以及 `svc = Service(db)` 之后的 `svc.method(...)`,判据仍然是**被调方是否 mutate**(只读的照旧不报,否则一次就是一百多条噪音)。**变异验证**:把 `replay.py` 改回上一轮修复前的原样,闸立刻报 `app/domains/automation_exception/replay.py: 1 finding` —— 它现在真的能抓住那个曾经溜过去的形状。 ## 二、🔴 扩闸的配套断言当场把我上一轮的话证伪了 widening 会多出 **86** 条,其中 **73 条**都是同一件事:`NotificationService.dispatch` / `enqueue` / `push_inbox_and_feishu`。上一轮我判断它们**自我隔离**,所以这轮加了一张 `(构造器, 方法)` 的豁免表 —— 并且**给这张表配了一个结构测试**,让「它们自我隔离」这句话由 AST 去核,而不是由我去记。 **那个测试第一次跑就红了。** `_deliver` 末尾的 `self.audit.log(...)` **不在** savepoint 里,而 `AuditService.log` 是裸 `add()+flush()`、不自我隔离。也就是说: - 上一轮我在 CHANGELOG 里写的「那 6 处原本不是缺陷,`dispatch` 已经自我隔离」—— **对了一半**。outbox INSERT 和状态 UPDATE 确实隔离了,审计行没有。 - 全仓**约 52 个**调用点正是靠这句话在裸 `except` 里包 dispatch。一个超长的 `detail` 值、一次 `audit_logs` 上的锁等待,就能把调用方的事务带走。 修在**原语**里(一个 savepoint 覆盖 52 个调用点),而不是在 52 个调用点上。丢一条审计行是可见的、小的;丢调用方整个事务是静默的、大的。 ## 三、闸照出来的 13 处,全部排空 **9 处用 `best_effort` 修**:登出时的 refresh-token 失效(下一句就是 `AuditService.log`,教科书形状)、HRIS 同步协调器起入职单、合作方标签的注册表写 + GitHub 台账写、云授权撤销时级联关闭续期申请(「绝不让续期记账拖垮撤销」此前恰好会拖垮撤销)、Google 建号的密码信留档、离职的 CBG 保留注册表写、跳过 blocker 时把设备标成「被离职者持有」(其后紧接着 `_get_process(lock=True)` + 审计写)、API Key 强制转手(**兜底分支自己也在写**,所以原来的兜底在最需要它的时候必然失败)。 **4 处标 `savepoint-exempt` 并写明理由**:三处被调方**中途 commit**(savepoint 会被那个 commit 释放,包了反而每条都报失败 —— PLATFORM.md #25 点名的 must-not-wrap),一处 handler 无条件 `raise`、且兜底审计走**自己的 session**。 顺带把 `savepoint-baseline.json` 从 **32 → 31**(合作方标签那条存量一并排空),并把 `idle_reclaim` 两个 phase 的裸 `begin_nested` 也换成 `best_effort` —— 裸形式会吞掉 1205/1213/1305 这类**服务端已经中止事务**的错误,于是一次瞬时死锁会变成后面每一个坐席都 "SAVEPOINT does not exist"。 ## 四、顺带查出的两个真缺陷(都是「同一个失败模式换个门」) | 缺陷 | 后果 | |---|---| | `service.reopen()`(**管理员手动重开**)不清 `subject_notified_at` / `escalated_at` | 自动重开路径早就清了 —— 这正是「回音变成一辈子一次」那条修复。手动这道门没跟上:管理员把一个**关错了**的簇重开,它后来真修好了,**当事人永远收不到那条「已经好了」**;复发也永远不会升级给负责人 | | `affected_people` 从**截断后**的最近 100 条发生记录里取,而表头的 `affected_person_count` 是全量 `COUNT(DISTINCT)` | 一个繁忙的簇会说「23 人受影响」然后只列出 9 个,页面上没有任何东西解释这个差 | ## 五、三件「看见了但没修」的收尾,其中一件是我上一轮**判断错了** - ✅ `_run_signal_backed_phase` 的裸 `begin_nested` —— 改了,连同它照抄的 phase 1 一起(只改一半才是坏的)。 - ✅ `_HEALTH_PRIORITY` 与 `resolve_job_health` 的顺序不一致(`chain_stalled` vs `integration_disabled`)。对齐了,并加了一条**契约测试**钉住重叠情形,以后改一边就红。 - ❌ **HEIC:我上一轮的顾虑是错的,现在撤回。** 我当时说「移动端 iOS 可能撞上 `ai_labs_image` 不收 HEIC」。去读代码才发现**移动端 AI Labs 页面根本没有文件输入** —— 整个文件里 `image` 出现 0 次。我那条顾虑是从**页面的注释**里读来的,而那句注释写着「图片保留,因为相机就在手边」,**描述的是一个没有实现的功能**。真正该修的是那句假断言,已经改成如实说明「一个附件都没有,以及为什么」。厂商白名单一个字没动 —— 没有实测证据就不该去放宽面向厂商的白名单。 **顺带清掉三处死声明**:`HeldDevice`(整个类没有任何人构造)、`ChainAdvance.parent_last_run_at`、`_SeatEvidence.product_label`。而 `AttestationFacts.holder_display` **刻意留着并加了注释**:它确实没人读,但「为了让字段有人用」而把员工姓名塞进厂商请求,是把隐私回退包装成整洁。 ## 验证 后端定向集合**逐个**跑(不并行):automation_exception+auth+core **1021** / notifications+core **2014** / offboarding+leaver_blocked+hr **1344** / scheduled_jobs+auditor **912** / google_workspace+hr_lifecycle+github_org **730** / asset+apikey **1241** / cmdb **2158** —— **全绿**。 新增 **11** 条测试(6 条钉住扩宽后的闸本身、2 条钉住 `_HEALTH_PRIORITY` 与解析器一致、1 条手动重开、1 条受影响人名单、1 条**行为层**验证审计写失败不再毒化 session),每条都做过变异验证 —— 包括那条把我上一轮断言推翻的结构测试。静态闸:ruff / mypy 棘轮(1268=1268)/ savepoint 棘轮(32 → **31**)/ TiDB parity / alembic 单头 622;前端 lint / typecheck / vitest / build 全绿。 > **2026-09-06(第九轮)— fix(review): 三天 59 个 PR 的全量复审 —— 十个真缺陷,最狠的三个都是「产出了但没有人读」(0 迁移)** 对 2026-09-04 ~ 09-06 合入的 **59 个 PR / 489 文件 / +106,609 行**做一次整体复审:读代码 → 修 → 复审修复本身 → 安全扫描 → 逻辑扫描,循环到只剩注释级为止。每条修复都做了**变异验证**(撤掉修复,新测试必须转红),下面每一行都是那样确认过的,不是读出来的。 **这一轮最贵的三个缺陷是同一个形状:一份数据被认真地算出来,然后没有任何人读它。** 单 PR 自审看不见这类东西 —— 生产者那一侧写得很好,测试也断言了生产者确实产出了它。 | # | 缺陷 | 后果 | |---|---|---| | 1 🔴 | **五个采集器算出的 `severity_facts` 消费者是零。** `ingest` 从来没把它传给 `compute_severity`,父行按模型默认值 `normal` 建出来,之后只被四个列重算 | 「离职的人权限没撤掉」—— 这个域自己的分类法点名叫 `critical` 的那一条 —— **一直被评为 `high`**。待入职新人没账号同理;P0 定时任务失败评成 `low`;没送达的 action 类通知评成 `normal`。而这块面板整个排序就是「最糟的在最上面」,**第一屏是错的**。原有测试只断言采集器**产出**了那个 dict(`test_collectors.py:86,195`)—— 断言打在了错的那一层,把消费者整个删掉它照样绿 | | 2 🔴 | **`wont_fix` 的簇会给每个受影响的员工发「现在它已经生效,你不需要再做任何事」。** `close_wont_fix` 也会写 `resolved_at`,而回音只筛了这一列 | 管理员刚刚明确判定「这个我们不修了」,平台转头告诉当事人它好了。`resolution_kind` 区分不了 —— wont_fix 和人工确认修好都写 `manual` | | 3 🔴 | **SSO 撤销核验的冷却判断第二次起必抛 `TypeError`。** `removal_last_checked_at` 是 MySQL 的裸 `DATETIME`(取回来是 naive),而 `now` 是 aware;这个模块里**其它每一个**时间戳都过了 `_aware`,只有它没有 | 第一次检查时该列还是 `NULL`、比较不发生,所以看不出来;**第二天起**每个 grant 都在 per-grant savepoint 里抛异常并被记成一次「跳过的错误」。Google 侧的核验对该 grant **永久失效**,而屏幕上什么都不说。既有测试全部传 `force=True`,恰好绕过这条分支 | | 4 | 重放的三个 per-row handler 用裸 `except` 包住**不自我隔离**的域写入(`retry_task` / `resend_outbox_row` / `sync_person_to_target`) | flush 失败会让整个事务失活,于是「一行失败不能拖垮其余 199 行」这句承诺在最常见的 DB 失败上不成立:后面每一行都 `PendingRollbackError`,收尾的 `flush()` 把整次点击变成 500 | | 5 | 权限到期扫描里的 `revoke_user_permission` 同样是裸 `except` | 一次 poisoning 失败之后,**这一跳里后面所有到期权限都没有被回收**,而任务照常报成功。这是「访问在自己的有效期之后还活着」 | | 6 | 任务链预测把每一跳的时长算了两遍(第二跳起) | `chain_offsets` 存的是**累计**偏移,配的却是上一跳**已经位移过**的时刻表。深度 1 是对的 —— 所以看不见;#3467 的云 IAM 三件套是本仓第一批深度 ≥2 的链 | | 7 | AI 分诊队列的**第二道饿死门** | `FAILURE_MODEL` / `FAILURE_UNGROUNDED` 记录尝试但刻意不落 `advice_generated_at`(瞬时错误值得再试)。于是一条模型总是答不接地的行永远留在结果集里,而排序只按次数 —— 几条就能占满每小时的预算。和 WHERE 子句关掉的那道门是同一个结局,换了个入口 | | 8 | 一条发生记录换簇之后,它**离开**的那个簇当轮不重算 | 空簇顶着 `open_occurrence_count` 在工作台上装成一个活着的问题,直到第二天的对账 | | 9 | `auditor.self_attestation_advice` 是全仓 **32 个** LLM 构造点里唯一没报 `purpose=` 的 | 它的花费记进 `unattributed`。而这正是**按人扇出**的那个调用点 —— 漏掉它对「哪个功能烧的 token」这个问题的影响最大。补了一道 AST 结构闸,它自己做过变异验证 | | 10 | **同一个 `wont_fix ≠ 已修好` 的混淆,换了个面又回来了**(第三轮才抓到) | 工作台的「自愈率」KPI 是 `resolved_by_kind.auto ÷ resolved_in_window`,而分母筛的也是 `resolved_at IS NOT NULL` —— 于是**每一个管理员主动判定「不修了」的问题,都在把显示出来的自愈率往下压**,并且记在 `manual` 桶里,和「人工确认修好了」完全分不开 | **关于第 4/5 条要说准确一点。** 同一轮我把 6 处 `dispatch` 调用也换成了 `best_effort`,但**那 6 处原本不是缺陷**:`NotificationService.dispatch` 已经自我隔离(`enqueue` 与 `_deliver` 的两次 flush 都在 `begin_nested` 里)。留下它们是纵深防御 + 统一形状,而那 6 处真正修掉的是**错误文案**:`str(exc)` 把 `AppException` 渲染成 15 字符的空哨兵并丢掉 `.code`,日志行以一个冒号结尾、后面什么都没有 —— 现在一律走 `step.reason()`,也就是本仓唯一的那个格式化器。**代码注释与本条都按这个区分改写过**,因为把「纵深防御」写成「修了个 bug」本身就是一条假断言。 🔴 **顺带记下一个闸的盲区(本轮没有扩,理由在下面)。** `scripts/check_savepoint_isolation.py` 的过程间规则只匹配 `f(db, ...)` —— 第一个位置参数是 session。**`Service(db).method(...)` 这个形状它看不见**,上面第 4/5 条就是从这个洞里过去的。按同一形状粗扫(我自己写的 AST 探针,比闸本身更宽松)全仓约 **125 处**,把闸扩宽等于一次性把 baseline 从 32 涨到三位数,那是一个独立的排空工程,不该塞进一次复审 PR 里连带做。**本轮新增代码里的 9 处已经清零**,盲区本身写进了 `PLATFORM.md` 第 24 条,下一个人不必再自己发现一遍。 **两条主动否掉的「顺手修」。** ① `_run_signal_backed_phase` 用的是裸 `async with db.begin_nested()` 而不是 `best_effort` —— 但它是照抄同文件里 phase 1 的既有形状,只改一半会让同一个文件出现两种写法,而闸本来就接受这个形式;② `ai_labs_image` 不收 HEIC,移动端 iOS 可能会撞 —— 这是**厂商能力**问题,没有实测证据之前不该去放宽一个面向厂商的白名单(见 memory 的「第三方 API 方向」)。两条都如实留着,而不是悄悄修掉。 **循环收敛的形状,如实记下来。** 第一轮(读原代码)8 条;第二轮(**只审我自己的修复**)3 条 —— 其中两条是我自己写坏的:替换后的错误文案在 `AppException` 上会回落成空字符串,以及丢掉了原来 `exc_info=True` 的调用栈;第三轮(问「这个失败模式还有别的入口吗」)1 条真的(上表第 10 行)+ **4 条怀疑被证伪**(几个新 dataclass 字段确实没人读,但都只是装饰性的,不像 `severity_facts` 那样悄悄改变了排序;SQL 层的 `Model.col <= now` 是绑定参数,不会像 Python 层那样抛 TypeError)。**证伪多于发现 = 可以停了。** **验证。** 后端定向集合**逐个**跑 —— 不并行:同一个 slug 上两个 pytest 会互相 drop 表,这一轮我自己踩了一次,那批 19 个 setup ERROR 全是它造成的,重跑就是 1338 passed。automation_exception 179 / scheduled_jobs 418 / permission+data_access 482 / apikey 305 / sso+apikey 363 / auditor 492 / ai_labs 173 / notifications+provisioning+identity_sync 2390 / offboarding+onboarding+hr_lifecycle 955 / asset 936 / integrations 1338 / cmdb 2158 / intelligence 244 / automation_exception+permission+apikey 519 —— **全绿**。新增 **23** 条回归测试(22 条在 6 个新文件里 + 1 条追加进 `test_triage_queue.py`),每条都做过变异验证。静态闸:ruff / mypy 棘轮(1268=1268)/ savepoint 棘轮 / TiDB parity / alembic 单头 622 全绿;前端 lint 13 道 / typecheck / vitest 1455 / build 全绿。安全扫描(新增路由的鉴权、MCP 新工具的 RBAC 与自作用域、IDOR、注入、密钥入日志、SSRF、XSS、上传路径穿越、除零)**零发现** —— 三个「没有 guard」的 MCP 工具逐个读过,分别落在 `can_read_all_assets` 与服务层的持有人校验上。 > **2026-09-06(第八轮)— refactor(web): 管理端菜单真正重组 —— 一级仍是 14 行,但每一组只回答一个问题(0 迁移)** 上一轮我做了管道(菜单搬成数据)和安全网(目的地快照),然后用「105 个叶子塞不进 8 组 × 8」当理由,**可见的部分一个字没改** —— 用户的原话是「我怎么看着没有变化啊」。他是对的:那等于把问题原样退回去。 真正该修的不是行数,是**分组不自洽**,而这正是「我不太能理解怎么分布的」的来源: | 组 | 之前 | 现在 | |---|---|---| | **人员与身份** | 用户管理 4 项 | **11 项**(并入身份与 SSO、邮件组)—— 「这个人是谁」和「他的身份同步到哪」是同一个对象的两面 | | **云与数据** | 云资产 8 项 | **11 项**(并入数据仓库)—— 数据仓库单独一组只有 3 项,还得先想「它算不算云」 | | **系统配置** | **12 项,混了三种活** | **6 项**,只剩真配置 | | **运营洞察** | 8 项,混了运维 | **6 项**,只剩「数字说明了什么」 | | **平台运维** | 不存在 | **4 项**:健康台 / 对账 / 定时任务 / 审计 —— 排障要的四页此前散在两组 | | **IT 服务** | 不存在 | **4 项**:服务台 / 知识库 / 助手评测 / 流程审批 —— 是日常工作队列,不是配置项 | | HR 工具 | 10 项,含办公地址与邮件组 | **8 项**,只剩「人的时间」 | **两个折进去、两个拆出来,一级仍是 14 行。** 行数从来不是目标 —— 目标是点开一行之前就知道里面是什么。三条硬约束守住:**没有合并任何页面、没有加第三级、没有改任何路由**,深链与收藏全部照旧。 **做法:声明式规格,而不是手改 1,900 行 JSX。** `menu/regroup.ts` 是一份「组 → 子项」的规格,`regroupAdminMenu` 在**丢掉任何一页时直接抛错**。第一次跑就抛了 —— 我凭印象敲的 11 个路由路径全是错的(`/admin/org-chart` 实际是 `/admin/org`)。**这条保护当场把「凭记忆写代码」拦下来了**,改成从实际菜单树里读才对。 🔴 **可达性守门抓到了这次改动,我把它改强而不是迁就它。** 它原本解析 `MainLayout.tsx` 源码找标识符 —— 因为当年菜单是 1,500 行由十几个 hook 构建的 JSX,测试里跑不起来。我把重组放在运行时之后它**看不见了**,于是报「global_admin 与 management 回不到 AI 大脑」。它自己的注释写着「红了不要削弱它」,所以:菜单现在是可导入的纯函数,守门改为**真正构建每个视角的侧栏(含 shell 施加的重组)**,断言落地页确实在里面。旧版只能看见源码字面写了什么,**会放过「源码里对、屏幕上错」的菜单**;新版不会。做过变异验证:把 `/admin/intelligence` 从规格里删掉,它在导入阶段就抛。 **验证**:前端 lint 13 道 / typecheck / vitest **1455** / build 全绿;重组测试钉住「目的地集合与重组前完全一致」「每页深度仍是 1」「无重复」「抛错保护本身会红」。 > **2026-09-06(第七轮)— refactor(web): 菜单从 MainLayout 搬出来变成数据,每个人多一条「常用」轨;外加一份模块地图(0 迁移)** 起点是两个反馈:**「管理的菜单一直很多很复杂」**、**「很多东西臃肿地分布在各种位置,我不太能理解怎么分布的」**。 🔴 **先纠正我自己的一个错误测量。** 我此前说管理端侧栏有 **25 个一级入口**,并提议压到「8 组、每组 ≤8」。那个 25 是我按标签文本粗数的,把不同层级的标签混在了一起。**真正跑一遍菜单构建器数出来是 14 个组、共 105 个目的地**,每组 3–12 个。 这个更正直接改变结论:**105 个叶子塞进 8 组 × 8 = 64 个位置,算术上就不成立**。要把一级入口数真正压下去只有两条路 —— 三级嵌套(用户已否决),或者合并页面(我承诺过:没有「数据证明没人用」之前不合)。**所以这一轮不强行压数字**:一个页面没合,一条路由没改,深链 / 收藏 / 别人发的链接一条都不会断。 **菜单变成数据。** 1,800 行数组从 `MainLayout` **原样**搬进 `layouts/menu/roleMenus.tsx`。那个文件本来 2,841 行、六成是菜单条目 —— 决定外壳怎么渲染的文件,主要内容却是一张菜单清单,两件事都得翻过对方才能读。搬完 MainLayout 约 700 行。 **搬家的安全网,也是以后任何重组的安全网。** `roleMenus.test.ts` 快照**每个视角的完整目的地集合**,外加重复 key 与非空检查。**分组本身刻意不断言** —— 那正是以后应该可以自由改的东西;被钉住的是「这个角色能到达哪些页面」,也就是分组改错时用户真正失去的东西。以后哪个叶子真要下线,这个文件在同一个 commit 里变更,diff 会指出是哪个视角丢了哪一页:**丢页面从事故变成一个看得见的决定。** **「常用」轨。** 105 个目的地意味着任何分类法都是妥协 —— 对按同样方式思考的人是对的,对其他人就是找。与其继续争分类,不如把每个人**反复打开**的那几页的路径缩短:按人、免配置、**按当前视角过滤**(否则切换视角后快捷方式会变成打不开的链接,那比没有更糟)、**要访问两次才占一格**(一次通常是找别的东西误入,提拔它只会让这条轨变噪声)。存储不可用或损坏时整条轨消失、侧栏照常渲染,两种情况都有测试。 **既有守门没有被削弱。** `menuReachability.test.ts` 原本解析 `MainLayout` 源码找 `menuByViewRole` 与各角色数组;现在数组在新模块里,于是它**读两个文件并合并声明** —— 不变量一个字没改。 **模块地图(`PLATFORM.md` 新增一节)** 回答「我不太能理解怎么分布的」:后端 51 个域是常态、17 个顶层目录各自是**跨域的一层**(附最容易搞混的两对:`identity` vs `identity_sync`、`hr_lifecycle` vs `domains/hr`);前端**按域**是主约定,`pages/admin` 是**漂移**而不是第二种约定 —— 其中约 21 个文件明确属于某个域。 ⚠️ **那 21 个文件本轮没有搬,并且写明了理由**:搬家本身是机械的,但给每个文件挑新家需要约 20 次判断,挑错会让布局比现在更糟(`RoleChange*` 进 `pages/hr` 还是新建 `pages/roleChange`?而 `pages/provisioning` 里已经有一个 `RoleChangePage.tsx`)。建议改成「新增一律进域目录,存量动到哪搬哪」,而不是一次 59 个文件的大搬家 —— 后者会让之后每一次 `git blame` 和每个在途 PR 都付代价。 **路由刻意没有按域拆**:路由与 `RoleRoute` 守卫是交织的,拆开会把「哪些页面在哪道守卫后面」藏起来,而那正是需要一眼能审的东西。 **验证**:前端 lint 13 道 / typecheck / vitest **1449**(新增 19)/ build 全绿。 > **2026-09-06(第六轮)— fix(automation-exception): 收口复审 —— 六个真缺陷,没有一个在单个 PR 内部,全在 PR 之间的接缝上(0 迁移)** 自动化异常闭环 PR5:对 PR1–PR4 新增的**整片面**做一次复审 + 安全扫描 + 逻辑扫描,循环到干净。四个 PR 各自全绿合并,**接缝上仍然躺着六个真缺陷** —— 这正是「整体复审」与「四次单 PR 复审」的差别。 | # | 缺陷 | 会造成什么 | |---|---|---| | 1 | reopen 清了 `escalated_at` 却没清 `subject_notified_at` | 回音变成「一辈子一次」:问题复发的人,**第二次修好永远不会被告知** | | 2 | 重放死信通知永远无法恢复 | `resend_outbox_row` 是**克隆**,原行仍是 dead+未确认 —— 而采集器扫的正是这个集合。同一 outbox id 每 tick 都是候选,父行永不解决,而 UI 报的是「已重新执行 1 条」 | | 3 | `_replay_outbox` 把「被拒绝的重发」当成功 | 它对离职收件人等四种情况返回 `{"status":"skipped"}` 而**不抛异常**;管理员看到「全部重驱动」,实际一条没发 | | 4 | 分诊在 Python 里过滤、却在 SQL 里分页 | 被 `needs_triage` 永远拒绝的行**永不落戳**,于是永远留在结果集里;而排序是「最严重优先」,几十条已分类的高频行就能占满每一页 —— **分诊每小时跑一次,永远什么都不做** | | 5 | 两个模板只登记在管理端分组表,没登记进语言表 | **每个收件人都会收到硬编码中文**,无论 `preferred_language`。而本公司多数员工读英文 | | 6 | 严重度重算把 `integration_enabled` 写死成 `True` | 一个**被主动停用**的连接器,其异常会在下次对账时从 `low` 升到 `high` —— 停用越久、台账上越吵,方向是反的 | **第 5 条尤其值得记:守门测试是绿的,而它本该抓住这个。** `test_every_sent_template_key_is_registered` 扫两种拼法(`template_key="字面量"` 与名字含 `TEMPLATE` 的常量),而我的常量叫 `TPL_SUBJECT_RECOVERED`、调用点传的是**名字**,两条正则都不匹配。该测试的注释里已经记录过这个盲区的**两个**前科,我撞上的是第三个变体。守门已加宽到同时认 `TPL`,并做了**变异验证**:摘掉一条注册,它确实转红。 **第 2 条的修法特意没有写 `recovered_at`** —— 那会让重放自己断言恢复。改为走通知域**自己的 `cancel_outbox`** 关掉原行,采集器下一轮**自己观察到**,恢复仍然来自证据。也照了那条「读者必须只认一个常量」的规矩:**写者也一样**,所以没有手工拼 `ACK_NOTE_PREFIX`。 **每条修复都配了带前置断言的回归测试。** 前置断言不是装饰:reopen 那条的第一版就因为 fixture 用了随机 `signature_hash`,导致 ingest 建了新簇、reopen 路径**根本没被走到** —— 加上 `assert stats.exceptions_reopened == 1` 才让它验的是它声称在验的东西。 **验证**:`tests/test_automation_exception/` **159 条**;三域联跑(automation_exception / notifications / scheduled_jobs)**1980 passed**;`test_template_locale_parity` **853 passed** 且经变异验证;`ruff` 干净;mypy 棘轮 **1268** 无新增;前端四闸全绿。安全扫描:11 个端点全部有 RBAC(读 `require_admin_read`,写 `require_admin`)、台账按构造不含凭证与提示词、搜索是绑定参数且限长 200、自由文本两层限长、审计 detail 不含密钥或 PII。 > **2026-09-06(同日第八轮)— fix(access-lifecycle): 自证建议的定时任务在「整个功能都挂了」时报成功 —— 一条 PR5 自己埋的、宽容度用错了地方的闸(0 迁移)** `auditor.self_attestation_advice` 的容错原则是对的:**一个持有人失败不该让整轮失败** —— 那个人少一段摘要,复核页照样能用。问题是这条原则**悄悄替另一条弱得多的主张站了岗**:一轮里**谁都没拿到建议、而原因是模型通道根本连不上**,也被当成成功。 那种运行长这样:每个持有人都踩 `no_client` / `call_failed`,摘要写着 `annotated=0, failed=500`,而定时任务台账盖一个 **SUCCESS**、`failure_count` 停在 0、没有任何东西惊动任何人。下一次开 campaign 时,~500 个人被请去依赖一批**从来没有生成过**的建议。 修法是给「整体失败」单独一条判据,而不是放宽既有的容错:`channel_failures` 单独计数,**只有 `holders_annotated == 0` 且 `channel_failures > 0` 才 raise**。两半都是承重的,变异验证分别证明:去掉 raise → `test_channel_down_for_every_holder_fails_the_run` 红;去掉 `annotated == 0` 这一半(部分失败也炸)→ `test_one_holder_failing_still_succeeds` 红。 🔴 **`FAIL_NO_ITEMS` 和 `FAIL_UNGROUNDED` 刻意不进这个集合,而且这是三条负向测试的全部意义。** 「这个人没有要复核的东西」是关于那个人的事实,不是关于通道的;而 100% `ungrounded` 是**接地闸在正常工作** —— 一个每次接地闸生效就呼叫值班的闸,迟早被人关掉,而它守的恰恰是「别让编出来的数字上合规页面」。把失败集合放宽成「任何 failure_code」→ 那三条负向测试全红。 **raise 放在 `commit()` 之后**:每一行 per-holder 记录都带着自己的 `failure_code`,是「尝试过、为什么没成」的唯一证据;为了表达「这轮失败了」而回滚它们,等于把原因一起删掉,下一轮只会看到同样一批没有建议、也没有任何解释的持有人。 线索来自并行会话的 PR5 复审 —— 他们挖到的「`_replay_outbox` 把被拒绝的重发当成功」是同一族:**一个被拒绝的动作被记成一个完成的动作**。我拿这个形状回头扫自己刚合的代码,才发现这一条。功能目前在生产上是暗的(`ai_advice_enabled` 默认关),所以这个缺陷还没有机会发生 —— 但它会在开关打开的那一天开始沉默。 **验证**:新增 14 条(1 条钉住失败码集合 + 8 条判据参数化 + 5 条真跑 handler 的集成);**3 处变异验证各自转红且互不重叠**;`tests/test_auditor` + `tests/test_scheduled_jobs` 全绿;ruff / mypy 棘轮 1268 / savepoint 守卫无新增。 > **2026-09-06(第五轮)— feat(automation-exception): 在等的那个人终于会被告知一声;而一个「又回来」的问题会去找负责人(迁移 622 · 只播种 cron)** 自动化异常闭环 PR4。**没有新列** —— PR1 把 `subject_notified_at` 与 `escalated_at` 就留在那儿等着这一轮;迁移 622 只播种一条 cron。 一次没走通的自动化,背后通常有个**人在等**:没拿到账号的新人、坐席申请死在厂商 500 里的员工。平台一直知道这件事,却什么都不说 —— 他们要么靠问 IT 才知道,要么永远不知道。这一轮补上这一半,同时补上方向相反的另一半:一个**被解决之后又回来**的问题,说明上次的处置没解决根因,所以它会去找负责人,并带上当前根因与建议的下一步。 **三条规矩,每一条都因为反面更糟。** ① **只在真的修好时发,且只发一次** —— 触发点是「未恢复 → 已恢复」这次**状态转移**,不是「我们重试了」也不是「我们注意到了」;`subject_notified_at` 让它是一次转移而不是一个状态,采集器再跑一遍也不会发第二条。**被告知两次的人,会连第一条也不再相信。** ② **不新增打扰类目** —— 本平台的类目是从 template_key 派生的(`categories.classify`),所以两个 key 注册进**既有** `lifecycle` 类目;员工已经设好的静音与免打扰**天然管住它**。新增类目更省事,而且会悄悄给所有人塞一条他们从没同意过的推送。③ **不把他无法处置的失败告诉他** —— 给员工的那条只说「现在可以用了」,**不说**「它此前失败了 47 次」;后者是管理员的问题,讲给一个只是在等的人听,等于把一个已解决的问题变成一份新的担心。有测试断言失败次数与厂商错误串**不出现在**员工那条里。 🔴 **同伴会话的一条判据在这里直接命中了我的两处真缺陷。** 判据是:**在这个库里,「我刚才读过它」就是让后续任何重新读失效的那个条件** —— `select()` / `Session.get()` 都返回 identity map 里的旧对象,`expire_on_commit=False` 让 commit 也不帮你过期,只有 `populate_existing` 会刷新。 - **PR3 的重放冷却期根本没有锁**:两个管理员同时点,**两边都读到 `last_replay_at IS NULL`,两边都发** —— 把冷却期本来要防的厂商负载翻倍这件事原样做了一遍。 - **PR4 的回音同理**:两个 tick 同时跑,同一个人被告知两次 —— 正是上面第 ① 条承诺不会造成的伤害。 四条查询现在全部 `.with_for_update().execution_options(populate_existing=True)`。**锁本身不解决问题,是 `populate_existing` 让锁有意义**:否则加锁 SELECT 发出去了、锁也拿到了,回来的值还是加锁之前的那个。 🔴 **补这个洞的测试又炸出第三个真 bug**:`moment - occ.last_replay_at` 抛 `TypeError` —— **MySQL 返回的是 naive datetime**。此前这个值只由本进程在内存里写(aware),把 bug 藏住了;而**只要它在数据库里走过一个来回就会炸**,也就是第一次之后的每一次运行。已按 PR1 的 `timeutil.aware()` 收口。 **测试不能是空的。** 冷却期那条回归测试的第一版必然空转:`Session.execute(update(...))` 默认 `synchronize_session='auto'` 会把新值**写回**内存实例,替我把「陈旧」抹平。现在显式 `synchronize_session=False`,**并且在调用被测函数之前先断言一句「内存副本此刻确实是旧的」** —— 没有那句,这个测试哪天会因为完全无关的原因静默变空。 **验证**:`tests/test_automation_exception/` **149 条**(新增 12:两个 template 都路由到既有可静音类目 / 只告知一次 / 不告诉他失败了多少次 / 无人等待也要落戳 / 发送失败**不**落戳(否则这个人永远不会被告知)/ 离职者不打扰 / 一次复发是噪声两次才是模式 / 升级带上下一步 / 每个 episode 只升级一次 / 无负责人不乱找人 / **陈旧内存副本下冷却期仍然生效**);`ruff` 干净;mypy 棘轮 **1268**(跑过 checker)无新增;前端四闸全绿。 > **2026-09-06(staging-deploy 合并后复审)— fix(staging-deploy): 上一轮自己写的那份「怎么恢复」把人指进了它同一个 PR 刚证明是死路的分支(0 迁移 / 0 端点 / 0 MCP / 0 RBAC)** #3478 一边在文档和脚本里更正「迁移之后**只能重跑 sanitizer**,重新证明那条必然 `exit 8`」,一边在**它自己新写的 step summary 第 2 步**里写着「用 `reattest-dax-retained-on-ecs.sh` 重新证明新 revision」。**运维最需要准确指令的那一刻,拿到的是同一个 PR 刚刚证伪的那条路。** 现在第 2 步改成「重跑 Staging Branch sanitizer」,并把「重新证明不是替代方案、它会 `exit 8`」直接写在旁边。 同一份 summary 里还留着两句已经不成立的话:「**它会每夜同样地失败**」和「计划发布永不迁移」—— 而这个 PR 删掉的正是 `schedule:`,已经没有「每夜」和「计划发布」了。改为「每次 dispatch 都会停在这里」和「只有 dispatch 时带 `apply_migrations=true` 才会迁移」。host 脚本那行 `scheduled deploys never migrate` 同理改为 `this run is not authorized to migrate (dispatch with apply_migrations=true)`,契约测试跟着改断言。summary 里指向运行手册的相对链接换成绝对 URL(step summary 里的相对链接不可靠)。 **验证**:`tests/test_deploy` 118 绿;工作流每个 `run:` 块单独 `bash -n` 通过;`deploy-on-ecs.sh` `bash -n` 通过。 > **2026-09-06(独立修复,不属于当日两个主题系列)— fix(staging-deploy): 每夜必红的 Staging 计划发布 —— 一个和本仓合流速率结构性互斥的 cron,外加一份让人读不懂它为什么红的日志(0 迁移 / −1 GitHub Actions schedule / 0 端点 / 0 MCP / 0 RBAC)** `Staging Deploy` 连续 13 个夜晚失败(08-24 → 09-05),Staging 停在 Alembic 527、`main` 的 head 一路走到 618。报进来的口径是「至少 5 天、5 个不同 commit、根因是 schema 漂移」。**逐条分类 20 次失败之后,这三点里有两点要改。** **第一,不是 5 天,是 13 天;而且这个 cron 一生就没正常工作过。** 全量 38 次运行按时间排开:计划触发共 24 次、**成功 4 次(16.7%)**,4 次全部落在 2026-08-21～08-23。查 `main` 上迁移的落地日期,那三天**一个迁移都没有** —— 是个周末。迁移 528 在 08-24 落地当天它就再次转红。08-24 至 09-06 的逐日计数是 12/8/11/3/4/6/7/6/7/3/9/1/13/7,**没有一个工作日为 0**,中位数约 7。 🔴 **所以「把 Staging 迁到 head」不是修复,是上了跑步机。** 计划发布**失败闭合**于「Staging 不在这次发布的 head 上」,而本仓每个工作日都合并迁移 —— 迁完最多买到一个晚上,还得那晚恰好没有迁移合入,自 08-24 起这样的工作日一次都没出现过。这两条约束互斥,不是配置问题。**删掉 `schedule:`,只留 `workflow_dispatch`。** 2026-08-13 那条 ADR 的安全边界一个字不动:计划发布永不迁移、人工 dispatch 仍是唯一的 `alembic upgrade head` 路径、两阶段恢复不变;变的只有「每天自动试一次」本身。8 月 20 日那次恢复本来就是一天之内 8 次手工 dispatch 做出来的 —— 按需触发说的是实话。 **第二,一半的失败根本不是 Staging 的问题。** 20 次失败分三类:**schema 漂移 9 次**;**`go-ci / Main` 不绿 10 次**(08-13→08-19 连续 7 次,以及 08-25 / 09-01 / 09-04)—— 这一类在拿到任何云身份**之前**就退出了,是祖先闸在正常工作,拒绝发布一个红的 `main`;**08-31 那次是 Staging 的 TiDB Serverless Branch 自己答 `(1105) usage quota exhausted`**。把它们读成同一个根因,是因为**读不出来**。 🔴 **读不出来的原因是一个纯粹的 bug:Cloud Assistant 的 `Output` 是 Base64,工作流把它原样 `printf` 进日志。** 这个工作流有史以来每一次失败,在 Actions 上都是一坨不可读的 blob;要知道昨晚为什么红,得手工 `base64 -d`。**这就是它红了 13 夜没人处理的机制性原因。** 现在解码后再打印(不是合法 Base64 就原样回退)。 **三种状态现在各说各的话。** host 脚本给「落后于 head 且本次无权迁移」保留**退出码 43**(与既有的「仅迁移」`42` 同一形状,工作流不解析人类可读输出),并打一行机器可读的 `SCHEMA_BEHIND current=… head=…`;工作流据此给出带标题的 `::error::` 加一份 step summary,列出两个 revision 和那四步恢复动作。`go-ci` 闸失败改为报出该 check 的真实结论并明说**「这不是 Staging 发布链路的问题,去修 `main` 自己的 post-merge CI」**。 🔴 **顺带查出运行手册在两条恢复分支里错了一条。** `docs/deployment/staging.md` 一直写「重新脱敏 **或** 重新证明」。**重新证明这条是死路**:`reattest-dax-retained-on-ecs.sh` 把源 receipt 的 `database` 块**原样抄进**新 receipt,因此原理上无法证明一个 sanitizer 没见过的 revision —— 它拿源 receipt 的 `alembic_revision` 和活库 schema 比,迁移之后必然 `exit 8`。迁移之后唯一走得通的是**完整重跑 sanitizer**。脚本现在把这句话直接打在那次 `exit 8` 上,文档也改了。这条同时是「每日闸门」为什么不是排程问题的原因:无人值守链路缺的正是「能证明新 revision」的那一环。 **验证**:`tests/test_deploy/test_deploy_safety_contract.py` 14 条全绿(既有 12 + 新增 2);原来把 cron 写死成契约的那条改为断言 `on` 只有 `workflow_dispatch`,并在测试里注明再加回来之前要先回答哪个安全边界问题。**四处变异验证**,每处都由**对应的**那条断言在**不同行号**抓住:①撤掉 output 解码 → 转红;②`43` 不再保留 → 转红;③把 `schedule:` 加回来 → 转红;④删掉 reattest 的指路文案 → 转红;还原后重跑仍 14 绿。两个 shell 脚本 `bash -n` + shellcheck(只剩两条**改动前就存在**的 SC2155)干净;工作流 YAML 可解析,且**逐个 `run:` 块**在替换掉 `${{ }}` 后单独 `bash -n` 通过;Base64 解码助手拿**生产那次真实的 blob** 和纯文本各测一遍(解码正确 / 原样回退);`SCHEMA_BEHIND` 的 sed 解析对真实格式与缺失标记的兜底各测一遍。 **没做也不能在这里做的事**:恢复 Staging 本身要在 ECS 上跑 Cloud Assistant(迁移 → 重跑 sanitizer → 改 `deploy.env` 的 `STAGING_SANITIZATION_RECEIPT` → 再发一次),本会话没有阿里云凭证,**未触碰任何生产或 Staging 环境**。08-31 那条配额告警是否仍然有效也未核实 —— 它会挡住上面第一步。 > **2026-09-06(第四轮)— feat(automation-exception): 「凭证修好了」是一次点击,不是一张 47 行的待办清单(0 迁移 / 0 cron / 0 新 MCP)** 自动化异常闭环 PR3。这一轮**没有迁移** —— PR1 已经把 `replayable` / `replay_attempt_count` / `last_replay_at` / `last_replay_error` 四列都留好了,PR3 是来写它们的。 🔴 **这个模块拒绝的形状:管理员换好了一把过期的凭证,平台回给他 47 行失败让他一条条点。** 那是技术上正确、审计完整、却完全没用的做法 —— 他已经做完了**唯一需要他做的决定**,把这个决定的后果转发回去,等于让他把活干两遍。所以:管理员说「凭证修好了」,平台**自己**把这个集成下面所有未恢复的行重新驱动一遍,成不成都不再问他,最后给他一句回音。 **四条让这件事安全的性质。** ① **只驱动既有原语,绝不新建**:建号任务走 `ProvisioningService.retry_task`(它自己行锁,两个并发重试不会都把 attempt_count 归零)、通知走 `resend_outbox_row`(克隆成新投递而不是改写死信行,投递历史才诚实)、身份同步走 `sync_person_to_target`。三者各自已有锁、审计与幂等;在这里再写一遍就是同一件事的第二个实现,两边必然漂移。② **有界**:`MAX_REPLAY_PER_RUN` 封顶一次调用 —— 对一个刚刚恢复的厂商灌进一整个坏发布的重试量,是自己给自己制造一次故障,而那正是这些异常的一半来源。③ **只有成功才关闭任何东西** —— 而且**成功也不写 `recovered_at`**:一次返回 200 的重试**不是**底层工作成功的证据,恢复由各来源的采集器按自己的证据判定。在这里替它们下结论,等于往唯一一张记录「失败真相」的表里写一句谎。④ **每次尝试都留痕,包括什么都没改变的那次**:`last_replay_at` 即使失败也会推进,于是冷却期内的第二次点击是**看得见的空转**,而不是悄悄把厂商负载翻倍。 🔴 **写这一轮时我自己造出、又拆掉的一个真缺陷:同一个问题有了两个权威。** PR1 已经确立了判据 —— 「这一行能不能重放」由**产出它的采集器**逐行标 `replayable`,因为只有它知道那一行带没带够重试所需的东西。我的初版却按**来源**判定,于是造出了第二套、而且**互相矛盾**的定义:它会去重放 `integration` 行,而 `integration_source` 明确标了 `replayable=False`(重新测一次连接不是「重放失败的工作」)。一个问题两个权威,就是它们漂移的方式。现已收敛:两处查询与循环体内都以**行上的标记**为准,来源表只用于分派;`SOURCES_WITH_HANDLERS` 现在与「采集器会标 True 的三个来源」逐一对齐,并由测试断言。 **同一轮还拆掉了三列重复的列。** 我一度按不同的名字(`replay_attempted_at` / `replay_last_error`)把 PR1 已经建好的列又加了一遍,模型里 `replay_attempt_count` 甚至声明了两次,并为此写了一支迁移 620。查过模型后全部撤销:**PR3 一支迁移都不需要。** **面**:异常详情抽屉新增「重新执行(N)」按钮。`N` 来自后端新增的 `replayable_occurrence_count`,与引擎用的是同一个权威,所以按钮**永远不会提供一个可证明什么都不会做的动作**。回音分三种且不四舍五入成成功:全部重驱动 / 部分失败(带第一条真实原因)/ 无事可做(说明多少条在冷却期)。文案明说「是否真的恢复由采集器下一次判定」——界面不替数据下它没有的结论。 **验证**:`tests/test_automation_exception/test_replay.py` **11 条**(行标记是唯一闸门 / 成功不写 recovered_at / 一条坏行不打断整批 / 失败也留痕 / 成功清除旧错误 / 冷却期空转 / 过了冷却期再试 / 批量有界 / 集成级只挑该集成下未恢复且可重放的行);全域 **137 条**;`ruff` 干净;前端 lint 13 道 / typecheck / vitest / build。 > **2026-09-06(同日第七轮)— feat(access-lifecycle): 访问对象闭环 PR5 —— 自证有了可以据以判断的东西,「没人回答」不再是终点(迁移 621 / +2 端点 / +1 cron / +1 MCP → 626 / +1 通知模板)** 半年度访问自查(SOC2 CC6.3 / ISO A.5.15 的证据)有两个洞,这一轮各补一个。 **① 持有人没有可以据以判断的东西。** 一份资深工程师的清单是几十行 `jira-software-users` / `analytics-prod.events_raw` 这样的名字;冷着问,唯一安全的答案是「都留着」—— 而一次人人全留的复核**产出了证据、什么也没改变**。PR4 已经把缺的那半做出来了。新模块 [`auditor/self_attestation_ai.py`](../server/app/domains/auditor/self_attestation_ai.py) 刻意做成和 [`mover_review_ai`](../server/app/hr_lifecycle/mover_review_ai.py) 同一个形状,包括让建议可以给人看的那三条:**不能编数字**(`_validate` 拒掉事实里没有的整数,整份作废而不是删一句)、**不能发明类别**(只匹配这个人清单里真有的访问类型)、**什么也不决定**(建议落在 `auditor_self_attestation_advice`,与持有人的 `decision` 并列,永不落进去)。 🔴 **这个模块比转岗那份多一条规矩,因为它的事实来自厂商而不是 Helix 自己的表:「无法确认」不是「没在用」,而且提示词的禁令不算闸。** `unknown`(厂商没给可用值 / 快照过期)和 `unsupported`(厂商根本答不了)按原样发给模型,系统提示禁止把它们说成闲置 —— 但**提示词是请求,不是闸**,所以 `_validate` 里有一条代码级检查:摘要里出现「闲置 / 没用过 / 可以清理 / unused / idle」并且带着那个 unmeasurable 的数,整份作废。PR4 把四态一路端出来的意义,会在一个摘要把它们拍平成「5 项闲置」的那一刻全部丢掉。这条检查还带了一个反向条件(`unknown_total not in idle_counts`),否则它会拒掉**说对了的**叙述 —— 一个会拦住真话的闸,迟早被人关掉。 **② `no_response` 是个耸肩。** `complete_campaign` 收尾时把没人回答的条目一律盖成 `no_response`(`decided_by_person_id` 保持 NULL),**权限原样留着**。于是这个流程为「做过一次复核」产出了证据,而一个从不回答的人什么都没丢,半年后同一份清单再来一遍。现在那些条目自动开一个 `no_response_followup` **补审 campaign**,reviewer 是持有人的直属经理,走既有的 `decide_item` + 回收流水线 —— 不另造第二条撤权路径。**没有任何东西被自动撤销**:补审只是把决定权从一个没回答的人手里,交到一个能回答的人手里。开关 `access_review.self_attestation.no_response_policy` 默认 `report_only`(保持今天的行为)。 🔴 **最要紧的一条:「记下谁该处理」不等于「派给他」—— 差点在这个 PR 里原样重演一遍。** 把 `assigned_reviewer_person_id` 设成经理看着像派活了,但**既有两条 decide 路径都门在 `can_manage_security` 上**(合规路由 + MCP 工具),而一个普通经理两个角色都没有。也就是说:补审开出来了,经理**一个门都进不去** —— 整个「后果」会是一行没有门的数据。所以这一轮补齐了三样:自作用域的 `GET/POST /api/v1/me/access-review/assigned`(「你是被指名的复核人」本身就是授权,和 `submit_self_attestation` 同一条政策)、一条通知模板、以及「我的待办 ▸ 替下属复核」页签。回归测试里最重的一条就叫 `test_the_followup_actually_reaches_the_manager`。 🔴 **安全扫描抓到一个我自己引入的越权,这是这一轮最重的一条。** `decide_assigned_review` 第一版只按 `assigned_reviewer_person_id == 调用者` 授权,**没有 campaign 类型限制** —— 而 `_snapshot_identity_consumer` 把 `person_id` 和 `assigned_reviewer_person_id` **都**设成消费方自己的 owner。也就是说对那类 campaign,「复核人」就是「被复核的人」,而这个端点背后没有任何管理员角色。完整链条:一个普通员工自助申请拥有一个身份消费方(owner 默认就是申请人)→ 季度重认证把它快照成「他自己复核自己」→ 他不回答 → `lapse_disable_identity_consumers`(它自己的 docstring 叫「重认证的执行牙齿」)把消费方停用 → 条目仍是 pending、campaign 仍 in_progress,于是出现在新页签里 → `keep` 走到 `mark_identity_consumer_certified`,把 `status` 翻回 ACTIVE 并清掉 `recert_lapsed_at`。**净效果:一个没有任何管理员角色的员工,可以把安全工具刚停掉的一个 PII 出口重新打开。** 这些条目在本 PR 之前只能经 `can_manage_security` 的路径碰到。 修法是**白名单**而不是黑名单,并且四道都补上:① 自服务 decide 只允许 `no_response_followup` 一种 campaign 类型;② 拒绝自审(`item.person_id == 调用者`);③ 列表用**同一个**白名单过滤 —— 否则页签会渲染出点了就 403 的行,而且会把别的 campaign 类型的持有人数据摊在一个没有管理员角色的界面上;④ `_followup_reviewer_for` 让自管记录(`manager_person_id == holder.id`,高管和 HRIS 边界情况真实存在)**根本不生成**这一行,留空走审计控制台 —— 把自己的「没回答」交给自己裁决,等于这次复核完全没有牙齿。 🔴 **而变异验证在这里又救了一次:①②两道各自删掉,测试都还是绿的。** 因为纵深防御里两道门互为兜底,那条组合测试只能证明「至少有一道在」,证不出哪一道承重。补了两条互相隔离的测试(一条让 `person_id != 复核人` 从而只剩白名单挡着,一条在白名单内的 campaign 里造出自审行),四条变异这才全部转红。**这正是「同一操作两道强度不同的门 = 弱的那道才是真边界」那条判据的反面用法:两道都强的时候,得分别证明。** **其余的边界都写成了测试**:离职者的条目**不进**补审(离职者的权限归离职流程,不归复核);没有经理在册的条目**留空不派**(猜一个替补复核人,是让权限决定落到没人选过的人头上);空补审直接删掉,不留一个读起来像未办事项的零条目空壳;源 campaign 的 `no_response` 计数**原样不动**,补审是另一个可独立审计的 campaign,不是对已关闭那个的改写。 **MCP +1 → 626**:`list_my_assigned_access_reviews`(只读)。写动作**刻意不给工具** —— 本文件里 approve/reject 一类「替别人的申请做决定」早就写明不上聊天面:一句话就决定同事的权限、而条目的上下文不在决定者眼前,正是复核页要堵的洞。 🔴 **迁移 621 的第一版是「同一个 3780 的第三种形状」,而且我把 612 的教训学错了方向。** 我没用 `sa.Uuid()`,而是**自己读父表的 `column_type` 拼进一段裸 SQL `CREATE TABLE`** —— 看着比硬编码谨慎,其实还是错的:**`column_type` 不带 collation**,而没有显式 `COLLATE` 的列继承的是**表默认**。errno 3780 在「数据类型一致但排序规则不一致」时同样会炸。 **为什么第一次没抓到:我只在一个「一次性建出来的」临时库上验过往返** —— 那种库上父表和新表的 collation 天然一致,矛盾不存在。换到一个**沿着真实迁移链建起来的**库(`utf8mb4_unicode_ci`)立刻 3780。这正是 `id_type_for` 的 docstring 早就写明的那条不对称:**本地 MySQL 8 各处一个 collation,复现不出来;生产 TiDB 会。** 本仓已经为这件事付过两次代价(迁移 126、2026-07-29 那次发布),而**答案一直在 `app/core/migration_helpers.id_type_for` / `table_kw_for` 里**。改成 `op.create_table` + 这两个助手之后,在 `utf8mb4_unicode_ci`(真实链)和 `utf8mb4_0900_ai_ci`(全新库)两种库上分别验证,子列与父列的**类型和排序规则**都逐字段一致,`621 → 620 → 621` 往返干净。 **并且给守卫补了第 (1d) 类,因为我这个形状是它看不见的第四种。** 既有三类((1) `String(36)`+FK、(1b) 裸 `CHAR(36)`+FK、(1c) DDL 里的 `sa.Uuid()`)全都在检查 `sa.Column(...)` 调用,所以**一张用 SQL 字符串建出来的表在结构上对它们不可见** —— 而 SQL 字符串恰恰是作者必须手工把类型和排序规则都写对、却没有任何东西核对的地方。新规则:`op.execute` 里的 `CREATE TABLE` **且带 `FOREIGN KEY`** 一律拒绝(不带 FK 的裸建表碰不到 3780,不管);修法永远不是「把类型读得更仔细」,而是 `op.create_table` + `id_type_for` + `table_kw_for`。5 条新单测 + 变异验证:把 621 退回原样,守卫红并逐行点名(`621_self_attestation_advice.py:102`);改回,全树绿。 **迁移 621 顺手把 612 的教训做成了做法。** 新表的 id 列类型**从活库里读父表**(`information_schema.columns`),而不是写 `sa.Uuid()` 或者硬编码 `CHAR(36)`。在真库上验证时这个做法当场又救了一次:`identity_persons.id` 在真实迁移链上是 **`varchar(36)`**,不是 `char(36)` —— 也就是说把 612 的错「显然地」改成硬编码 `CHAR(36)` 会换出另一个不匹配。**没有一个字面量对所有父表都对,只有「读」是对的。** **验证**:新增 **45 条**测试 —— [`test_self_attestation_pr5_2026_09_05.py`](../server/tests/test_auditor/test_self_attestation_pr5_2026_09_05.py) 18 条 + [`test_setting_bool_fail_closed_2026_09_05.py`](../server/tests/test_core/test_setting_bool_fail_closed_2026_09_05.py) 22 条 + tidb-parity 守卫第 (1d) 类 5 条;**变异验证 8/8 转红** —— 放开数字接地 / 放开类别闸 / 去掉「无法确认≠闲置」检查 / 把该检查放得过宽(会拒掉真话)/ `report_only` 偷偷升级成补审 / 经理从不被通知(没有门的那一行)/ 去掉复核人授权(谁都能替别人决定)/ 离职者条目照样派给经理。既有 `tests/test_auditor` 459 条全程绿。迁移在真库 `621 → 620 → 621` 往返,建表/删表、两个设置、cron 播种/删除、NOT EXISTS 重跑守卫都验过,FK 与父表类型逐列比对一致。前端 `pnpm typecheck` + `pnpm lint`(13 guard)+ `pnpm test` **1431 passed**。 🔴 **顺带堵掉一个 fail-OPEN:`bool("false")` 是 `True`。** 这些开关都存在 `platform_settings.value`(JSON 列)里,而管理员的 upsert 端点收的是任意 JSON —— 一次把 `false` 存成字符串 `"false"` 的保存(前端表单、一次手工 SQL、一份导入脚本都够),`bool(raw.get(...))` 就把一个**默认关**的闸判成**开**。方向恰好是最糟的那一个:这一批开关背后是「给员工发推送」和「自动回收权限」。新 [`app/core/setting_values.as_bool()`](../server/app/core/setting_values.py) 做失败关闭的强制转换(识别 `"false"` / `"0"` / `"off"` / `"no"` / 空串,认不出来的值一律落到 `default`),`data_access/lifecycle.py` 的四个开关与自证的 `ai_advice_enabled` 全部改走它。22 条单测把每一种拼法钉住 —— 这类工具函数的坑就在于「看着显然对」,而它是否真的关着,只有逐个拼法断言才知道。 **顺带修绿了 main 上 5 条不是这个 PR 引入、但确实是我自己欠下的红**:`savepoint` 守卫基线 1 条(我 PR1/PR2 四个文件 + PR5 一个新文件,全部改成 `best_effort` 或写明理由的豁免)、assistant 目录闸 4 条(PR1/PR2 加的 20 个 MCP 写工具里有 11 个衍生成可提议动作,而 curated 卡片一个都没配 —— **和这条闸此前两次红的形态一模一样,第三次了**)。处理方式不是把上界从 76 抬到 87:**6 个进了 `OPT_OUT`**(4 个自己函数体里就 `_require_global_admin`,提议给员工等于给他一张必然被拒的卡;2 个是「替别人的申请做决定」,落在该文件早写明的那一类),**4 个补了 curated 卡片**,上界因此是 80 而不是 87 —— 差出来的 7 个不是「已解释」,是「本来就不该在目录里」。 > **2026-09-06(定时任务系列合并后复审)— fix(scheduled-jobs): 复审 —— 两个 PR 各自都对,合起来让一条链每 5 分钟空转一次;同族共三条(0 迁移 / 0 端点 / 0 MCP / 0 RBAC)** 定时任务域五个 PR 合完之后的整体复审。找到的**唯一一个真缺陷是跨 PR 的**,两半单独看都没有问题,所以两次单 PR 的自审都不可能发现它。 🔴 **推进对账会把一个「永远跑不了」的下游每 5 分钟重放一次,永不停止。** #3462 让绑定了停用集成的任务在**占并发槽之前**就跳过,并且为了不让一个长期关停的集成把 100 行的运行台账刷空,**第一条之后的跳过一行都不写**(连时钟都不写)。#3467 把云 IAM 三件套按账号串成了链 —— 而那批行恰好就是绑集成的,生产上有 5 个集成是停用的。推进对账判断「下游落后了没有」靠比较两个时间戳,并且**依赖这个条件在下游跑过之后自动消失**;一个根本跑不了的下游永远不会让它消失:每 5 分钟被触发一次、每次都在闸门前被挡回去、时钟一动不动 —— 每天 288 次空转,更要命的是它**长期占着每跳 12 个的名额**,真正该推进的成员会被它挤掉。 **修在对账侧,不修在闸门侧,理由是这次复审里最值得留下的一条。** 让跳过路径顺手写一下 `last_run_at`,判据就自动消失了,一行就完事 —— 但 `last_run_at` 同时是**合规态势闸**判断「这个控制项的信号还新鲜吗」所读的那一列(`auditor/compliance_service.py::freshness`)。一个什么活都不干却一直报告新鲜时钟的任务,会让一个控制项在**没人在采集的数据上显示为绿色** —— 那正是 #2217 花了力气堵上的那个洞。所以时钟保持诚实,改成让对账**学会第二种「跑不了」**;它本来就认得第一种(`enabled = 0`)。排除不丢东西:集成一恢复,下游仍然落后于上游,下一跳就会把它放出来(有测试)。 🔴 **同一族的第二个缺陷:对账检查「上游在不在跑」,却不检查「自己在不在跑」。** 一个任务的 `last_run_at` 是在运行**结束**时才写的,所以在它自己跑的整段时间里,它读起来仍然落后于上游。对账于是每 5 分钟把一个**正在跑的**下游再触发一次,每一次都输掉单飞锁的竞争、并留下一行 `skipped`。有界(锁在运行结束时释放),但不是无害:三件套里有一个成员实测 17 分钟,于是每天每次运行都往一个只有 100 行上限的历史里滴几行垃圾,而且让「single-flight lock busy」—— 本该意味着一次值得查的真碰撞 —— 变成设计上的常态。两端一起排除,查询数不变。 **顺带修掉两条同源的小问题。** ① `plan_advances` 的查询**没有 ORDER BY**,而调用方有每跳 12 个的上限 —— 数据库完全可以每次都返回同一批,让上限从「削峰」变成「某个成员无限期饿死」。改成按等待时长排序(NULL 优先,即从没跑过的最该先跑)。这一条在修之前测试是**碰巧绿的**,加了排序之后做变异验证才转红,说明返回顺序确实不确定。② 「这一行绑了哪个集成」原本在闸门侧和对账侧各写了一遍,两份对**畸形 config**(`integration_id` 不是字符串)的判断不一致:闸门当作「没绑」照跑,而我新写的那份会当作「绑了但集成不存在」把它排除掉 —— **一条链会因此停住,而任何地方都不会说为什么**。收敛成同一个 `config_integration_id_of`,两侧共用。 **任务链面板现在会说出这一环为什么不动。** 排除是对的,对账保持沉默也是对的(这不是故障,不该由它报),但代价是**管理台上这条链看起来完全健康却什么都不做** —— 那是这个面板能显示的最糟糕的东西。`chain_graph` 每个成员多一个 `blocked_reason`,与对账的排除条件**逐条镜像**(同一个谓词、同一个顺序),面板上渲染成一个 warning 标签 + 说明为什么、以及不需要做任何事。有测试断言两侧对「谁卡住了」给出同一个判断 —— 面板和对账各说各话,比面板什么都不说更糟。 **一条查证后确认无害、单开任务处理的历史遗留**:`scheduled_jobs.next_run_at` 全仓**没有任何写入**(所有 `next_run_at =` 命中都在别的表上),因此恒为 NULL,却仍在列表接口、排程预测的兜底、以及一个 MCP 工具里作为字段发布。不是这一系列引入的,也不影响正确性,已另开任务决定「删列」还是「真的去维护它」。 **验证**:7 条新回归测试(含一条把「面板与对账必须一致」钉死的);**三次变异验证**(摘掉排除 → 2 红;摘掉排序 → 红;两者同时摘 → 3 红);`tests/test_scheduled_jobs` 全绿(一次批量 error 经单独重跑证明是另一个会话并发占用同一套测试库,不是代码);五道后端守卫(alembic / TiDB parity / savepoint / mypy 棘轮 1270 / uuid seed)全绿;前端 typecheck + 13 道 lint 守卫 + 1431 条单测全绿。 > **2026-09-06(独立修复,不属于当日两个主题系列)— fix(scheduled-jobs): 删掉 `scheduled_jobs.next_run_at` —— 一个从来没有人写过、却被六处读出去当数据渲染的列(迁移 620 / 0 端点 / 0 MCP / 0 RBAC)** `scheduled_jobs.next_run_at` 从迁移 037 建表起就在,**没有任何代码写过它**。调度器的下次触发时刻活在 APScheduler 的触发器里,不落这张表;`_finalise_run` 只回写 `last_run_*` 一族。 🔴 **它能活到今天,是因为 grep 看上去总有人在写。** 全仓 `next_run_at\s*=` 的写入命中全部落在**别的表**上:`identity_sync_targets`(那是真游标,dispatch 每 60s 按它取 due 目标,还有 2026-07-14 那次饿死事故留下的一整套语义)和 `cmdb_resource_report_subscriptions`。同名不同物 —— 任何一次「这列还有人用吗」的排查,只要停在文件名和列名上,都会得到「有」。 **并且它不是"永远 NULL"那么无害。** 迁移 245 播种 `hr.recover_orphaned_left` 时带了 `next_run_at = NOW()`,那一行是 `enabled=1` 的。于是管理员在 `/admin/scheduled-jobs` 上看到的不是空白,而是一个**冻结在 2026-06-03 部署那一刻**的「下次运行」—— 一个三个月前的未来时间。空字段还能被认出来是没数据;一个具体的时间戳不会。 **读它的地方有六处,不是三处**(排查这一列时最初只点出了三处,实际清点多出三处,其中两处直接渲染给人看):任务列表/详情响应(`scheduled_jobs/router.py`)、排程预测里 `next_run` 的兜底(`service.py`,死兜底)、**合规控制项的 control-status**(`domains/auditor/router.py` → `AuditorControlBanner` 8 张控制卡上永久的「下次运行:—」)、关系图 sync-status(`domains/relationships/router.py`)、owner digest 任务元信息(`domains/cmdb/efficiency_router.py`)、HRIS 新鲜度的 due 计算(`intelligence/providers/people.py`,死分支)。另有一处 `mcp/tools.py` 的同名命中经核实是 `identity_sync` 目标的真游标,**不属于本次范围,未动**。 **顺带修好了一处因这个死兜底而不可达的功能。** 排程预测里 `next_run = upcoming[0] if upcoming else <读这个空列>`,所以「窗口内没有触发」的任务一律报 `None`,前端时间轴那句「窗口外,下次 …」的提示是**永远走不到的死代码**。现在兜底改为按活的触发器**现算窗口外的第一次触发**(cron 走 `CronTrigger.get_next_fire_time(window_end, window_end)` 取严格晚于窗口的那次,interval 走锚点算术),一个下次触发在三天后的任务终于能说出自己什么时候跑。**dense 与 chained 两类显式返回 `None`**:dense 的下次触发在几秒后、就在窗口内(`upcoming` 为空只是因为枚举短路成了频带),标成「窗口外」是换一个谎;chained 没有自己的时钟,越过窗口外推等于在估计之上再叠一层估计。 **权威来源就是 `service.schedule_forecast`**:它按 worker 同一套算法现算,并且覆盖 `trigger_type='chained'` —— 链式任务本来就没有自己的时钟,任何存起来的标量都表达不了它。前端 `ScheduledJob`(列表类型)不再带这个字段,列表页「节奏」列去掉那行下次运行(同一页的排程时间轴 Tab 画的是真触发时刻);合规控制卡去掉永久「—」的那一行,连带删掉只被它使用的 `formatNext` 与 7 个 i18n key × 3 语。 **验证**:两个新测试文件。`test_no_stored_next_run_at_2026_09_06.py`(7 条:列在 `information_schema` 里不存在**且 `identity_sync_targets` 的真游标仍在**、ORM 属性不存在、列表端点响应不含该键、窗口外真算出下次触发且等于「上次运行 + 一个间隔」、**从未跑过的任务锚在 `now` 而不是窗口末端**、窗口内有触发时不被覆盖、dense/chained 为 `None`)。`tests/test_alembic/test_migration_620_drop_next_run_at.py` 直接驱动迁移函数本身跑真 MySQL —— ORM `create_all` 建的测试库里这列本来就不存在,**那个库分不出「迁移写对了」和「迁移根本没写」**;它的收尾刻意恢复成「与模型一致」(列不存在)而不是像 540 那样恢复成 fixture 的中间态,否则同库的另一个文件单跑绿、混跑红。**三处变异验证**:①窗口外计算改回 `return None` → 目标用例转红、其余全绿;②从未跑过的锚点改回 `window_end` → 新增那条转红(这是我自己第一版写错的地方,`last_run_at` 有值时完全看不出来);③把迁移的目标表改成 `identity_sync_targets` → 4 条里 3 条转红(含真游标守卫)—— 该变异在**独立的一次性库**里跑,不碰共享测试库。迁移 620 另在真 MySQL 上跑了完整链路 + `downgrade -1` + 再 `upgrade` 往返:列消失 → 回来 → 再消失,`identity_sync_targets.next_run_at` 全程不动,`alembic heads` 单头。`tests/test_scheduled_jobs` + `tests/test_intelligence`(648)+ `tests/test_alembic` / `test_relationships` / cmdb owner-digest(117)+ `tests/test_auditor` 全绿;ruff 净;mypy 棘轮 1270 = 基线 1270(未新增);前端 `pnpm typecheck` / `lint`(含 i18n 三语 parity 守卫)/ `test`(1431 passed)/ `build` 全绿。 > **2026-09-06(独立修复,不属于当日两个主题系列)— fix(intelligence): 每周简报 14/17 失败的三类真因都已在线上 —— 剩下的缺陷在**报告失败的那条路**上(0 迁移 / 0 端点 / 0 MCP / 0 RBAC)** 接上一轮结尾留的那条:`intelligence.analysis_daily` 30 天 17 跑 14 败。**先查再修的结论是:那张失败表描述的是一份已经不存在的代码。**三类真因分别在 #2929(2026-08-17,`MissingGreenlet`)、#3379 与 #3383(均 2026-09-01 当天,输入窗口 + 接地闸便宜规则解连坐 + 生成层重问)里修掉并上线;生产当前跑 `sha-4bf6a0a00`,三者全部包含。**最后一次失败(09-01 07:35 UTC)发生在当天两个修复合入之前**,而这个 job 是周任务(`35 7 * * 1`),此后一次都没再跑过 —— 所以没有任何一次运行验证过现在的代码。`run_count=17 / failure_count=14` 是自 08-16 起的累计计数器,不会因为下一次成功而回落。 **用只读探针补上那次验证**(直连 prod TiDB 取 09-05 真快照 → `build_model_fact_package` → 真 key 打 qwen3-max → 真 `validate_intelligence_output`,零生产写入):输入 434,305 字符 ≈ 111K token,**是 258,048 窗口的 43%**(`_FACT_LIST_ITEMS_SHOWN=8` 的封顶在守着);**6 次真调用 6 次通过**。按记忆里那条「估通过率至少跑 6 次,3 次不够」的判据,这一格是过的。 🔴 **真正还坏着的东西是审计出来的,不在那张表里:失败路径会毁掉自己的诊断。** 注两个**真实**故障(不是 mock 抛异常),各暴露一个缺陷: - **模型答题期间连接被掐掉**(这个 handler 被登记成 `weight="heavy"` 正因为它把连接握过 120 秒的 LLM 调用)——告警内容是 `AI 大脑每日跨域简报生成失败:7s2a`。 - **厂商 `_meta.model_used` 比 `String(128)` 宽** —— 告警是 `…失败:9h9h`,而它**丢掉的是三次校验尝试已经一致同意的** `Narrative contains uncited numbers: ['9999']`,连审计行都没写成。 `7s2a` / `9h9h` 是 SQLAlchemy 的**文档锚点 slug**(`PendingRollbackError` / `DataError`)。它们能进告警,是因为 handler 写的是 `getattr(exc, "code", None)` —— 看着像鸭子类型的安全写法,而**每一个 DBAPI 异常都回答 `.code`**,答的是文档编号不是错误码。这和 08-17 那次 `MissingGreenlet` 是同一类:不是任务失败了,是失败报告了它自己内部的故障、盖住了世界上真正的故障。四处修: 1. 🔴 **except 分支不再读 ORM 实例。** 它们此前把 `row.model_used` 等**当参数**传给 `_mark_failed`,而 Python 先算参数——于是掉线那次,这个读在 `_mark_failed` 进入之前就抛了 `PendingRollbackError`,审计行**一次都没尝试写**。改成在 pending 行落库后立刻把 `row_id` / model / token 数镜像进局部变量,失败路径再也不碰它正在恢复的那个 session。这正是 08-17 在上一层学到的同一课(handler 里的 `snapshot_id = str(snapshot.id)`)。 2. **`_mark_failed` 改为 best-effort**,和它的姊妹 `_analysis_failure_reason` 同一契约:审计行写不进去要记日志,但**不能顶替调用方的真实原因**——丢审计行是坏事,丢诊断更坏,这是排序。 3. **`model_used` 两处写入都按列宽截断**。旁边的 `code[:64]` / `message[:512]` 一直是截断的,唯独这个**来自厂商**的值没有。 4. **兜底 except 分支现在把故障本身写进审计行**(`类名: 首行`,经 `_scrub_message`)。「Unexpected model generation failure.」描述不了掉线、死锁或序列化冲突中的任何一种,而这条分支**没有别的地方**记录原因:没有厂商码,也没有接地规则。 **修完之后同样两个注入的输出**:掉线 → `…失败:INTELLIGENCE_GENERATION_FAILED —— Unexpected model generation failure: PendingRollbackError: …`;超宽 model id → `…失败:INTELLIGENCE_OUTPUT_INVALID —— …uncited numbers: ['9999']`,审计行完整落库。 **没有碰接地闸的任何阈值。** `_MAX_PAIRWISE_FACTS` 原样不动 —— 记忆里量过:调高它会派生出 51,862 个可接受值,一位小数的百分数 100% 放行,闸自己点名要拒的 `312` 也被放行。包变大要收窄事实面,不是放宽闸。 **验证**:5 条新测试,**每一条都做过变异验证**(逐条摘掉对应修复 → 红,已复原)。其中两次变异有信息量:两处 `[:128]` 互为冗余,**只摘一处仍然绿,必须两处都摘才红**(所以是纵深防御,不是重复代码);摘掉 handler 那条修复,泄漏出来的是 `8s2b` —— 一个**实例级**的 slug,不在任何类属性里,所以测试里那个从模块反射出来的 slug 集合**接不住它**,真正接住的是每条测试都同时写了的**正向断言**(该说什么),这一点已写进测试注释,免得后人误信那个集合。`tests/test_intelligence` 244 条全绿;mypy 棘轮 1270 = 基线;ruff 全绿。 > **2026-09-06(独立修复,不属于当日两个主题系列)— fix(offboarding): Zoom 终删的「转交对象被拒」按种类分流 —— 顺带更正一条我们自己写错的故障判断(0 迁移 / 0 端点 / 0 MCP / 0 RBAC)** **先更正记录。** 本文件里 #3469(定时任务收尾)那条写着「`hr.offboarding_zoom_account_delete` 撞 Zoom 400「data receiver does not exist」(数据转移目标账号不存在,导致一个离职者的 Zoom 号永远停在挂起态)」。查生产之后,**这句话两处都错**:① 真实报文是 `Unable to transfer data because data receiver does not have Zoom **Webinars licenses**.` —— 收件人存在,只是没有 Webinar 许可;「does not exist」是把 200 字截断的日志行(`...data receiver doe`)补全成了另一个意思。② 那个账号**没有**停在挂起态:施宇航的 Zoom 号已于 **2026-08-23 16:21** 删除(账本 `data_transfer: skipped_no_webinar_license`)。该任务 08-20~08-23 连红 4 晚,#3152 当天修掉,**08-24 至 09-05 全绿**;当前**没有任何离职者卡在删除队列里**(全库 zoom / google 两条删除账本中 `failed` / `skipped_no_successor` / `no_integration` 均为 0 行)。每晚 `skipped: 65` 是 2026-08-04 停用闸上线**之前**的存量离职者(最新一个离职日 07-31),按 ROADMAP 既定决策不追溯清理 —— 停用闸之后的离职者卡住的有 **0 个**。 **真正要修的是那次修法的形状,不是那次故障。** #3152 的修复是**对一句厂商散文做子串匹配**(`"data receiver does not have zoom webinar"`),它只认自己见过的那一句。Zoom 是**先校验 `transfer_email`、再决定删不删**,收件人不合格就整个调用拒绝 —— 而这一族里的**其它**拒绝(最主要的就是那句被我们误读成真实报文的「data receiver does not exist」,即解析出的交接人在 Zoom 里根本没有账号)会掉进通用 `failed` 分支:**非终态 → 每晚重试 → 每晚重新报错 → 永远到不了终态**。这正是「每天都响、于是没人再看」的那种告警。抽查生产:416 名在职员工里 **6 人在 Zoom 快照里没有账号**;他们今天都不是任何流程的交接人,所以这条路径还没被走到 —— 但只要其中一人当上 lead 或被指为默认交接人,它就会走到。 **改成按标签分流。** driver 新增 `ZOOM_TAG_TRANSFER_RECIPIENT_NO_WEBINAR` / `_INVALID` 两个标签(锚在 Zoom 对这一族固定使用的名词 `data receiver` 上 —— 唯一在生产验证过的整句只有 webinar 那一条,其余的句子**不猜**),coordinator 以 `transfer_refusal` 透传(这个接缝此前把 `error_tag` 丢掉了,才逼得上层只能重新解析散文),sweep 只读标签:**没有 Webinar 许可** → 维持 08-23 的运营决定(不带转移重删 + 审计留痕);**其它收件人拒绝** → **拒绝删除**,记 `blocked_transfer_recipient`(非终态)、独立计数器(不进 `errors`,沿用 DECISIONS 2026-08-13 (d)「安全的拒绝不是故障」)、独立提醒种类 `del_blocked_zoom_recipient` **只告警一次**,账号保持停用。每跳仍重试,所以 IT 改一个有 Zoom 账号的交接人之后**自动就好,不需要补跑**。绝不在这里「不带转移重删」:收件人不存在时那一定成功,云录制随号永久消失(Zoom 无 undelete),而日志会显示一次干净的删除 —— 正是 2026-08-13 推翻掉的那个结局。 **顺带清掉一条会「永远卡住」的死路。** `_handoff_zoom_delete_to_software_owner`(08-20 那版的软件负责人手工任务)自 #3152 起已不可达 —— 而它当初失效的原因也正是 08-21~08-23 连红的直接原因:它要求该流程存在 Zoom 坐席 blocker + 活跃连接器,查不到就返回 None、掉回 failed。本次删除该函数及 sweep 里对应的死分支,并把 `manual_handoff` 从 `_DELETION_TERMINAL` 移除 —— 它是一个**没有任何代码能写入、却被当作终态**的状态,留着等于给「永远卡住」留了一条后路(生产零行)。 **验证**:`tests/test_offboarding/test_offboarding_zoom_account_delete.py` +4(标签驱动的拒绝 / 无标签时的报文兜底 / 只告警一次且自愈 / 非收件人故障仍然大声失败)、`tests/test_integrations/test_zoom_driver.py` +6(含截断报文不改变分类、**未请求转移时绝不打转移标签** —— 这一条是写测试时抓出来的自身缺陷:兜底原本会把 Basic 池挤出的删除误判成收件人拒绝,已加「看得见收件人才允许兜底」的闸)。两文件全绿;ruff 干净;mypy 棘轮 1270 = 基线。 > **2026-09-06(独立修复,不属于当日两个主题系列)— fix(identity-sync): 一条 NetSuite 告警查下去 —— 报警的那一半是对的,真正坏掉的是另一半:调度器的 `ran_failed` 闸从来没生效过(0 迁移 / 0 端点 / 0 MCP / 0 RBAC)** 上一轮把 `identity_sync.staleness_watchdog` 报 netsuite 的那条列为「平台在正确报告别的域的真问题」单开了任务。查完了,结论比原判更值钱:**看门狗确实是对的,但它说的那句话是错的,而顺着这句错话摸下去,摸到了一个从上线起就没工作过的告警闸。** **先把现场说清楚(证据全部来自生产只读)。** netsuite 的定时 sweep 在 **2026-08-20 02:02 → 08-23 16:15** 之间**一次都没成功过**:08-20 四次 `suiteql HTTP 401: Invalid login`,08-21~23 每晚 `dept phase had 5 failure(s)` + 139~169 人失败、零成功写入,08-23 15:55 一次 `HTTP 406: Language header`,16:15 恢复,当次 `updated=292` 把积压一次性追平。看门狗在这期间连续失败 **14 跳**(08-20 12:37 → 08-23 12:37,每 6h 一跳),此后 13 天全绿。**所谓「间歇性:56 跳里失败 4 跳」是窗口裁出来的假象** —— 它是一整段连续失败的尾巴刚好落进最近 14 天,不是时有时无。而 `identity_sync_targets.last_run_at` 显示 9-05 也没错:那一列被**每一次**运行刷新,包括单人 event 运行和失败的 sweep,看门狗当年正是为此才不读它。 🔴 **真正的 bug:`run_due_targets` 的 `ran_failed` 闸是死代码。** `run_target` 在 `self.db` 里建 `running` 行,却通过 `_finalise_run` **自己的 session** 落终态;结尾那次「重新查一遍」是普通 `select()` —— 而 **ORM 的 `select()` 不会覆盖 identity map 里已加载实例的属性,只有 `populate_existing` 会**,加上 `async_session_factory` 本来就是 `expire_on_commit=False`,那行从头到尾都是 `status='running'`。所以**凡是「不抛异常、只把 run 落成 failed」的路径,调度器都读成成功**。那段代码的注释写着「防的是未来某天 `expire_on_commit` 改成 False」—— 工厂一直就是 False,这道防御一天都没生效过。生产实证:08-21/22/23 三晚 netsuite 落 `failed`,`identity_sync.dispatch` 三晚都报 ok,`notification_outbox` 里 08-21→09-06 整段**零张**「数据同步中心 · 主调度」失败卡;`google-dept` 9-01 那次 `failed` 同样无人被告知。近 30 天共 **10 次** failed sweep 全部静默。**这正是当初建这道闸要防的场景**(2026-08-14 aws-ai 凭据被吊销那次的复盘原话:「一个被吊销的厂商凭据可以悄无声息地把每晚的离职兜底杀死好几周」)—— 而那次修复的验证测试把 `run_due_targets` 整个替身掉、手工喂了一个 `ran_failed` 列表进去,**只证明了 handler 会抛,从没证明过有任何东西能把目标放进 `ran_failed`**。修法:新增 `_reload_finalised_run()`,用一条**独立 session** 读回终态。不用在调用方 session 上 `rollback()/commit()`,因为 `_execute_manual_run` 和 MCP `trigger_identity_sync_target` 都在 sweep 之前读过库、握着 REPEATABLE READ 快照(光加 `populate_existing` 治不了),而 rollback 会把 MCP 那条待提交的 tool-call 审计行一起丢掉。**顺带修好一个用户可见症状**:MCP `trigger_identity_sync_target` 此前每次都回 `status: "running"` + `summary: null`。 **看门狗:两种形状分开说。** 「压根没跑」和「跑了但失败」此前共用一句「silently stopped running」,而这句话在 08 月那次是**反的**,两周后正是它把读的人引向 `last_run_at`,让两个事实读起来像自相矛盾、让看门狗看起来像坏的那个。现在按 `last_attempt`(不限状态的最近一次 scheduler 运行)分成 **silent**(调度器没有触发过 —— 这才是本任务的本职盲区,别处无人报)与 **failing**(跑了并失败 —— 修好 `ran_failed` 之后调度器会同时报,看门狗从此是双保险而非唯一保险),文案分别是 `DID NOT RUN` / `RAN BUT FAILED` 并给出「最后一次尝试」和「最后一次成功」两个时刻。**两种都照旧 raise** —— 超过一个周期没有成功的全量 sweep,不管哪种形状都是真的离职兜底缺口,分形状是为了让人一眼知道该往哪查,不是为了少报。`result_summary` 新增 `silent` / `failing` 两个桶,`stale` 保持为二者之并集,既有读者不受影响。 **残留影响:无。** 08-23 16:15 那次成功运行 `updated=292` 已把三天积压全部追平,`deactivated` 未丢;此后 13 天 13 次 `ok`。当前 12 个 target 全部 ok/partial,所以修好的闸不会带来告警洪水 —— 按近 30 天真实数据回算,它会多报约 10 次,每一次都是今天无人知道的真失败。 **验证**:新增 [`test_dispatch_failed_run_gate_2026_09_06.py`](../server/tests/test_identity_sync/test_dispatch_failed_run_gate_2026_09_06.py) 3 条 —— 走**真实**的 `run_target` / `run_due_targets` 通路(不是替身),修复前红在 `assert 'running' == 'failed'`,并守住反向(干净的 sweep 仍留在 `ran`);[`test_staleness_watchdog_2026_07_14.py`](../server/tests/test_identity_sync/test_staleness_watchdog_2026_07_14.py) +5 条覆盖 silent/failing 分流两侧与「从未成功过」分支。`tests/test_identity_sync` 全绿无回归;ruff 净;mypy 棘轮 1270 = 1270。 > **2026-09-06(第三轮)— feat(automation-exception): AI 分诊 + 平台自身 LLM 调用台账 —— 我们替全公司管 AI 花费,自己却没记过一笔(迁移 619 / +1 cron / +1 MCP→hint 625 / 0 新 RBAC)** 自动化异常闭环 PR2。两件事,共用一个前提:**平台自己也是 AI 的消费方,而此前它是唯一没有账本的那个。** 🔴 **29 个模块调共享 LLM 客户端,只有 2 个(`ai_labs` / `intelligence`)记过 token。** 所以「平台自己烧了多少、烧在哪个功能上」不是答得不准,是**根本没有答案**。`ai_spending` 一直在按 API key 拆厂商账单给财务看,但账单答不出「哪个功能」。新增 `llm_call_ledger`:每次调用一行,记功能 / 模型 / 操作 / token / 成败 / 耗时 / trace / actor。 **三条刻意的性质。** ① **不存内容** —— 提示词与回复一律不入库,这是 schema 的性质而不是约定:表里**没有**放它们的列。一张运营表若积累了员工工单文本与赏金报告,就成了没人签字同意的披露面。② **记 token 不记钱** —— 本仓没有按模型的单价表,本模块**不发明一张**。厂商发票仍是钱的真相;台账回答发票答不出的那半个问题。前端与 MCP 描述里都写死了这句,因为读的人会按看到的数字行动。③ **记账绝不失败调用** —— 每次写用**自己的**短命 session 并吞掉错误,调用方的事务一个字都不碰(包括调用方事务已经废掉的情况:一次死在 failed flush 里的 LLM 调用照样发生过、照样烧了 token)。 **埋点在客户端的四个出口,失败路径也记。** `_call`(供 `chat_json`/`chat_text`)、`chat`(compat)、`chat_stream` 全部按「包一层」而不是「在里面记」—— 这正是**失败也进台账**的原因,而失败行恰恰是管理员最想要的:一把过期的 key 会先在这里堆成一面同码的墙,然后才有人来报「功能坏了」。30 处客户端构造**全部**带上了 `purpose`(逐个解析确认,0 遗漏);没声明的调用记进 `unattributed` 而**不是丢掉** —— 丢掉会让台账与发票对不上,而且是看不见的对不上。 **AI 分诊:按签名调用,不按发生次数。** PR1 的规则表对能一眼认出的错误给了确定性根因,剩下的残渣停在 `unknown` + 通用「去查」——那正是管理员必须去读原始厂商文本的那批行。现在一个出现 4000 次的签名是**一次**模型调用,答案缓存在行上。四种情况不问模型:人判过 / 规则定过 / 这个签名问过 / 行已解决 —— **所以规则表越长,这条任务越便宜**。模型只能从 `ROOT_CAUSES` **闭集**里选(自由文本根因会破坏 `REMEDY_BY_CAUSE` 的全覆盖,把行重新变成死胡同),解释里每个数字都必须在事实包里,否则**整条**回复作废。分诊**不关闭任何东西、不通知任何人、不覆盖人工判定**,并在模型返回后**重查一次**人工判定(模型调用要好几秒,那是一个真实的窗口)。 **写这一轮被抓出来的两个真 bug(都是静默的)。** ① 台账的独立 session 绑的是**应用**引擎,而重定向到测试库的钩子挂在 `client` fixture 上 —— 我的测试没取它,于是写进了共享 dev 库。它们之所以曾经「通过」,只是因为那张表当时恰好在那个库里存在;这与前端测试逃出 jsdom 打到真 dev server 是同一个形状。② 读侧按 `called_at <= now` 过滤,而 **MySQL 把 `DATETIME` 四舍五入到整秒** —— 12:00:00.6 落库成 12:00:01,被 12:00:00.8 的上界排除。「不在未来」这个上界永远排除不掉真行,却会**随机排除掉最新的行**,而最新的行正是最不该出现静默缺口的地方。上界已整个去掉。 **验证**:`tests/test_automation_exception/` **126 条**(新增 26 条:purpose 归一 / token NULL≠0 / 成功与失败都落账 / 记账失败不影响调用方 / purpose_scope 异常也复位 / 窗口钳制 / 未归属可见 / 「厂商未报用量」单列 / 失败带错误码);迁移在**真正的**scratch 库上跑到 head=619(上一轮我把 `SYNC_DATABASE_URL` 写成了 alembic 实际读的 `DATABASE_URL_SYNC`,env 被静默忽略、迁移落到了共享 dev 库 —— 已 downgrade 回 618 与 main 对齐,本轮改用正确变量名并**查库确认**而非只读日志行);两列 id 与 `identity_persons` 逐列同类型同 collation;`ruff` 干净;mypy 棘轮无新增;前端 lint 13 道 / vitest 1431 / typecheck / build。 > **2026-09-06(同日第三轮)— feat(scheduled-jobs): 收尾 —— 链路兜底次数可见,以及两条我否掉自己的设计决定(0 迁移 / 0 端点 / 0 MCP / 0 RBAC)** 定时任务域优化第五批,也是最后一批。这一批小,原因值得写下来:**原计划的两件事在量完之后都不该做**,而把「不做」和理由留在树里,比硬做一遍有价值。 **链路兜底次数进管理台。** 链是靠「上游跑完时直接拉起下游」推进的(快路径),`scheduler.chain_advance` 是兜底。一个成员**每天都要被兜底捞一次**,说明它的快路径坏了 —— 而链照样在推进、所有状态都是绿的,所以在这个数字出现之前没有任何地方会说。`chain_graph` 现在按成员统计近 7 天 `triggered_by='chain_advance'` 的运行数,面板上超过 5 次转橙。只认对账触发的那一种:正常的链式运行(`chain:`)不能把这个数字抬起来,否则它就退化成「这个任务跑了几次」。变异验证:摘掉 `triggered_by` 过滤 → 红。 🔴 **决定一:三处到期提醒**不**接统一引擎 —— 我在 PR1 的分析里提议接,读完代码之后否掉了自己。** 它们不是同一个产品实现了四遍,是四个不同的产品。统一引擎(证书/域名)的阶梯是 T-30 一次 → T-14 一次 → ≤7 天每天 → 过期后每天,收件人在最后一公里升级到**域名负责人 + 直属上级**,owner 标「续期中」可以全面静音,还有首次启用的存量防轰炸;`apikey.expiry_check` 是 days_left 恰好 7 与 1 各一次,收件人**始终**是申请人 + 直属上级,去重键是 `(assignment, threshold, valid_until)`,而且**申请人已离职就直接跳过**(离职级联接管)——引擎里没有这一层,因为组织资产不会「离职」。引擎的模型是「一个有负责人的组织资产,沿责任链升级」;API Key 和 PAT 是**个人凭证**。统一就必须选一种产品行为:保留各家阈值和收件人(开工时对用户的承诺)又要共用,只能把引擎参数化成「阶梯策略 + 收件人策略」再配三份实现 —— **那是更多代码不是更少**;不参数化,员工收到提醒的频次会从 2 次变成 ≤7 天每天,那是没人要求过的产品变更。**结论:保持四份实现**,理由写进 DECISIONS,因为「四处手写到期阶梯」在任何一次体检里都会自动重新浮上来。 🔴 **决定二:云资源目录增量投影暂缓,并把那个陷阱记下来。** PR1 已经把它从 15 分钟改到每小时(41,095 → ~10,000 slot-秒/天),剩下的「只投影变过的东西」没做,理由有两条。收益已经不急:改完之后重量级类整体占用是 **13%**,再省 ~8,000 秒/天是把 13% 变成 11%。而**最直觉的做法是错的,并且错得静悄悄** —— 「按 `max(synced_at)` 给每个集成打水位,没变就跳过」看起来显然正确,但 `_safe_sweep` 软删一行时**只写 `deleted_at`,不碰 `synced_at`**:一次「云上这个资源没了」的同步不会抬高水位,投影跳过该集成,**目录里那条已经消失的资源会一直挂着,而且没有任何报错**。这张表喂的是员工可见的云资源目录和治理发现,投影错的后果是资源凭空消失或凭空存在,不是慢一点。做的时候要用 `GREATEST(synced_at, deleted_at)`,并且配一次每天的全量兜底负责消失检测。 **顺带更正一条我自己此前写错的判断。** PR1 的分析里我把 `onboarding.reconcile_processes` 列为「每 5 分钟跑一次、零处理却要 15~20 秒」的空转候选。量完之后是错的:生产上有 **15 条 open 流程**(1 preparing + 14 live),这一跳是在逐条重新核对它们的 blocker,`blockers_flipped: 0` 是「没有需要翻的」而不是「什么都没做」。它每天 288 跳 × ~5 秒 = 1,440 slot-秒,占轻量级容量(691,200)的 **0.2%**。不是 bug,不改。 **另外三条失败是平台在正确地报告别的域的真问题,不是定时任务的 bug**,已各自单开任务并附证据:`identity_sync.staleness_watchdog` 报 netsuite 自 8-19 起没跑过 scheduled full sweep(而该 target 的 `last_run_at` 是 9-05 —— 两半里有一半停了,值得查);`hr.offboarding_zoom_account_delete` 撞 Zoom 400 的数据转移拒绝(**这条当时读错了,见本文件顶部同日 fix(offboarding) 那条的更正**:真实报文是「data receiver does not have Zoom Webinars licenses」,不是 does not exist;该账号也没有停在挂起态,已于 08-23 删除);`intelligence.analysis_daily` 30 天里 10 次 `INTELLIGENCE_OUTPUT_INVALID`(接地闸在正确工作,不能为了让任务变绿去放宽它)+ 1 次 `MissingGreenlet`(这一条是真代码 bug)。 **验证**:1 条新测试 + 1 处变异验证;`tests/test_scheduled_jobs` + `tests/test_alembic` 全绿;四道守卫(alembic / TiDB parity / savepoint / mypy 棘轮)全绿;前端 typecheck + 13 道 lint 守卫全绿。 > **2026-09-06(第二轮)— feat(automation-exception): 「一次没走通的自动化」成为一等对象 —— 五个域各说各话的失败,归并成一张有负责人、有根因、有下一步的台账(迁移 618 / +3 cron / +3 MCP→hint 624 / 0 新 RBAC 角色)** 自动化异常闭环 PR1。平台已经有**五份**失败记录:建号任务的 `failed`、通知出箱的 `dead`、定时任务运行的 `failed`、身份同步条目的 `failed`/`blocked`、集成的 `last_test_status`。缺的从来不是第六份日志,而是**它们上面的那一层** —— *这一个问题,自周二起出现 47 次,在这个集成上,这样修*。那才是人会去分诊、指派、修复、关闭的对象。 🔴 **真正的盲区是集成凭证根本没有定时体检。** `integrations.last_test_status` 此前**只在管理员手点「测试连接」时**被写过(`integrations/service.py:830`),scheduled_jobs 里一条集成健康 cron 都没有。于是凭证过期在集成这一层永远不会被发现,只会表现为下游五个域各自报出的、看起来彼此无关的一堆失败。新增 `integrations.health_check`(每日 01:20 UTC,heavy)对每个**启用**的集成跑一次驱动自带的 `test_connection`,每个探测独立 SAVEPOINT、探测间隔 1 秒。它**只确立事实、不发任何通知** —— 告警与派工统一由异常台承担,免得一次凭证过期又变成四张卡(#2983 的教训)。 **两张表,分工是这次设计的全部。** `autoexc_exceptions` 是归并后的问题,身份 `(source, scope_key, signature_hash)`;`scope_key` 进身份是有意的 —— 同一句厂商报错来自两个集成就是两个问题、两种修法。`autoexc_occurrences` 是每一条失败源行,`(source, source_ref_type, source_ref_id)` 唯一,这是所有采集器的幂等键。父行计数**一律从子行重算,绝不累加**:累加更快,但第一次 tick 叠 tick 就会漂,而这个平台确实会叠(部署打断一次运行、手动触发撞上定时触发)。 🔴 **恢复判定由采集器逐个表态,而不是引擎一刀切 —— 判错方向的代价是不对称的。** 建号任务与集成体检扫的是**完整的当前失败集**,所以「这次没报」可以证明已恢复;定时任务运行和身份同步条目是**历史事件**(周二那次失败永远都会是一次失败),缺席什么都不能证明,只能由采集器给出「之后成功过」的显式证据(该 job 之后有 `ok` 运行 / 同一 (target, person) 之后有健康条目)。采集器自己读挂了会把结果标 `partial`,此时引擎**不做任何**基于缺席的关闭 —— 否则一次读取异常就会把这个来源下所有未解决的异常静默判为「已修复」,那比没建这张台账更糟。 **建号采集器刻意把「重试等待中」也算成异常。** 一次 Zoom 429 在第三次尝试成功,今天**在任何地方都不留痕**,所以平台自己的失败计数是幸存者偏差。现在这个回合会被登记,重试成功后自己解决 —— 不需要任何人做事,而「这个厂商到底拒了我们多少次」终于有答案。判据收得很窄:`attempt_count > 0` **且**有错误文本**且** `not_before` 还在未来;刚建的任务和退避已过的任务都不是失败。 **根因是闭集,处置由根因派生,`REMEDY_BY_CAUSE` 对 `ROOT_CAUSES` 全覆盖(有测试断言)。** 一个没有下一步的根因,正是这套东西要消灭的死胡同。规则层只认「管理员一眼能认出」的措辞,**拿不准就返回 None**:多一行留在 `unknown` 等分诊,代价是一行;一个自信的错判,代价是管理员照着错的处置去做(PR3 落地后还会是一次注定被厂商拒绝的自动重放)。数字型错误码全部**按词边界**匹配 —— `"429" in text` 会命中 `"group 4290 not found"`,建号域的暂时性分类器就是为这个在复审里被修过一次。 **负责人只从既有权威来源解析,解析不到就如实写「无人负责」。** 顺序是系统台账 owner → 台账 backup owner → 软件台账 owner → 软件台账 IT 接口人,每一跳都校验在职(离职的人不是负责人)。**刻意不兜底到 IT**:兜底会同时隐藏缺口、并让这一列在大多数行都是同一个值之后彻底失去意义。前端把无负责人渲染成一个 warning 标签而不是一个破折号,因为它是结论不是缺数据。 **页面是 `/admin/health` 的第一个 tab,路由和菜单位一个都没动。** 原有四块 KPI 面板原样成为第二个 tab「健康总览」——管理员已经知道去哪找的东西还在那儿,只是先打开的是可处置的那一半。列表按严重度排序走显式 CASE(`critical` < `high` < `low` < `normal` 是字母序,直接 ORDER BY 会把 low 排到 normal 前面),表格与详情抽屉一律引用**未恢复次数**而不是发生总次数 —— 两者的差额是已经自己好了的部分,混在一起会把一次自愈的抖动显示成一场故障。词表(来源/状态/严重度/根因/处置)**从后端拉取**,i18n 只存标签不存列表。 **三个 MCP 只读工具**(`list_automation_exceptions` / `get_automation_exception` / `automation_exception_overview`,hint 620 → 623):AI 客户端在回答「某某为什么没拿到账号」「我们自动化健康吗」之前,必须能问到这个。四个人工状态迁移**不给工具** —— 每一个都是人对一个仍在发生的问题下判断,尤其「不修关闭」会让一个真实故障从台账上消失,同既有先例(不给「按人回收账号」「撤某人坐席」工具)。 **写这一轮时被测试抓出来的四个真 bug,值得记下来**:① 从 MySQL 读回的 `DATETIME` 是 naive,和采集器构造的 aware 值一比就 `TypeError`,而比较恰好全在 ingest 主路径上(两个模块各中一次,已收敛到 `timeutil.aware`);② `recompute_exceptions` 只改内存不 flush,调用方随后的一次 refresh 会把重算结果静默丢掉;③ 通知桶的词表被我按印象写成 `actionable` / `critical`,而真值是 `action` / `info` / `social` —— 那个集合会一个都匹配不上,把每一条没送到的 actionable 通知都评成 `normal`;④ 定时任务的成功状态是 `RUN_STATUS_OK` 不是 `RUN_STATUS_SUCCESS`。三条都是**照记忆写常量**,不是逻辑错 —— 所以新增了一条 i18n 标签对账测试,两侧都从各自的定义读取再比对,而不是任何一侧重述一遍。 **验证**:`tests/test_automation_exception/` **100 条**全绿(签名归并 / 规则优先级与词边界 / 幂等 / 恢复四态 / partial 不关闭 / wont_fix 不复活 / 人工判定不被覆盖 / 五个采集器打真行 / cron 幂等 / RBAC / i18n 三语对账);`scripts/check_mypy_baseline.py` 仍在基线 **1270**(新代码零新增);`ruff check app` 干净;迁移在本地全链跑到 head=618,两张表列类型与排序规则与 `identity_persons` / `integrations` 逐列一致(避免 612 那次 CHAR(32)/CHAR(36) 卡死生产链的形状),三条 cron 已按 `enabled=1` 播种。 > **2026-09-06(同日第二轮)— fix(scheduled-jobs): 云 IAM 三件套按账号串链,消掉一个 29 天的静默故障;顺带修掉一条昨天刚上线的反向依赖(迁移 **617** / 0 端点 / 0 MCP / 0 RBAC)** 定时任务域优化第四批。PR3 造了链式原语,这一批把它用在最该用的地方。 🔴 **这不是优化,是消除一个有据可查的静默故障。** `cmdb.scopes_sync` / `roles_sync` / `grants_sync` **共用同一把 `cloud_sync:{integration_id}` 锁**,却作为三条相隔几分钟的独立 cron 跑。上游一超时,下游拿不到锁就不跑 —— `cmdb.scopes.aws-primary` 因此在 2026-07-07..08-05 **连续 31 天里有 29 天没跑**(roles 04:09 起跑要 ~15 分钟,scopes 04:18 撞进被持有的锁),新的 AWS 子账号一个多月对 Helix 不可见。串链之后它们**在结构上不可能再争同一把锁**:下游是因为上游结束了才开始的。顺序同时也是真实的数据依赖 —— role 挂在 scope 上,grant 挂在 role 上。 **形状守卫而不是逐行写死。** 13 个账号 × 2 条边,按「仍是播种时那个小时」的正则形状匹配(`^\d+ 4 \* \* \*$` / `^\d+ 5 \* \* \*$`),管理员把某一行挪到别的小时就放过它。上游在这个部署里不存在时也不连 —— 它本该保证的顺序在这里也不存在,把下游留在自己的 cron 上才是对的。降级还原成**同小时、名字派生的分钟**(原分钟不可恢复,而且不需要恢复):要紧的是别让整个车队都落回 :00,那正是迁移 418 消掉的惊群。 🔴 **顺带修掉一条昨天刚上线的反向依赖。** `software_seat.usage_signal_refresh`(迁移 612,2026-09-05 播种)在自己的描述里写着「每日 02:40 UTC(**排在 software_seat.idle_reclaim 之前**)」—— 而 02:40 在 idle_reclaim 的 02:00 **之后** 40 分钟,并且 `idle_reclaim` 确实读 `asset_seat_usage_signals`(`_evaluate_signal_vendors`)。也就是说自采集器上线起,消费者每天都在用**整整晚一天**的信号判闲置,上线第一天读到的是一张空表。串链把 idle_reclaim 挪到采集器**之后** —— 是往后挪,不是往前 —— 既修了顺序也把意图编码进了平台。另两条具名边同理:离职回收的写侧 → 只读校验侧,以及 `cmdb.leaver_grant_sweep` → `cmdb.leaver_iam_residue_sweep`(在常规回收链路跑完之前扫残留,只会造出一批马上就要被清掉的治理待办)。 **账单路径一条边都不连,这是这条迁移的承重约束。** 每条链式边都会让下游比今天**更早**开始(今天的间隔都很宽裕),而 `cost_facts_sync` / `billing_daily_sync` / 月结 / 对账拉的是厂商前一天的账单批次 —— 提前开始有可能读到厂商还没写完的批次,那是一次**披着排程外衣的数据正确性变更**。`efficiency_compute` 另有原因:它自己的描述说要排在利用率采集 **和** 成本明细 **和** 日账单之后 —— 三个上游,而 `chain_after_job_id` 是单父,唯一忠实的编码是一条穿过三者的线性链,那会把账单步骤一起拖早。**有一条测试直接对着迁移里声明的边列表断言「没有任何账单任务被串链」**,所以以后有人加了这样一条边,会在这里红,而不是在某次月结对账时。 **台账体检新增两个状态,堵上 PR3 自己开的口子。** `chain_orphaned`(上游那一行被删了 —— 外键把边置空而不是级联删除,所以这一行永远不会再触发,而在列表里看起来完全正常)与 `chain_stalled`(上游被停用,可恢复、也可能是刻意的,所以和 `integration_disabled` 同级)。两者都是「看起来活着、其实不干活」这一族,正是体检存在的理由。 **新增顺序清单与棘轮 —— 这一条是让原语不腐烂的东西。** `ordering_inventory.py` 记下每一条「B 要排在 A 之后」的声明与我们对它的处置(chained,并写明是哪条迁移连的;或 deferred,并写明理由),配套测试扫描所有 handler 的描述与 docstring:**一个 handler 在顺序词附近点名了另一个 handler,就必须出现在清单里**,否则构建失败。扫描器的邻近窗口是**量出来的不是猜的** —— 树里 8 条真实声明的标记词距离被点名的 key 在 **1~22 字符**(真声明会把两者放在同一个从句里),而两条**不是**声明的提及分别在 59 和 375 字符外(一条是说「已入队的行仍由 outbox_retry 兜住投递」,另一条是在划清界限:「NOT the same as … 这个是重拉金额」)。取 30,对真声明留足余量、把两条非声明排除在外 —— 一个会吐出没人能处理的配对的棘轮,是会被学着无视的棘轮。第一版没有窗口,正是它把这两条误报成了「待决策」。 **验证**:15 条新测试(3 条链式失效态 + 4 条顺序棘轮自身 + 8 条迁移 617)。**3 处变异验证**:摘掉 `chain_orphaned` 分支 → 红;摘掉 `chain_stalled` → 红;把邻近窗口放宽回 400 → 棘轮红(两条误报回来了)。`tests/test_scheduled_jobs` + `tests/test_alembic` **492 passed**;四道守卫(alembic 链 / TiDB parity / savepoint / **mypy 棘轮 1270 = 基线**)全绿;前端 typecheck + 13 道 lint 守卫全绿。运维视角写进 `cloud-lifecycle-ops.md` §5b-fixed,明说停用链起点会连带停掉下游、以及为什么账单路径不连。 > **2026-09-06 — feat(scheduled-jobs): 链式触发 —— 「排在 X 之后」从两个 cron 分钟数之间的空隙,变成一条能被兑现的声明(迁移 **615**(列)+ **616**(六条边)/ +1 端点 / +1 MCP → hint **621** / 0 RBAC)** 定时任务域优化第三批。前两批修的是「看不见」和「看见的是假的」,这一批修「说好的顺序其实没人保证」。 🔴 **代码里至少八处顺序依赖,写法是两个 cron 分钟数之间的空隙,意图只写在注释里。** 原话就长这样:`ai_spending.cost_drift_check` 的「每天 07:00 UTC(在 ai_spending.period_rollup_refresh 06:30 之后)」、`feed.notify_celebrants_and_leads` 的「紧随扫描任务」、`hr.leave_insight_snapshot` 的「排在 hr.leave_account_sync 之后运行」、`auditor.compliance_posture_summary` 的「先有证据,再谈覆盖率」、`offboarding.account_assurance_rosters` 甚至把上游的钟点写进了自己的描述里。**一个分钟差是平台兑现不了的承诺**:上游一超时,下游就在旧数据上跑,而且没有任何地方会说出来。更糟的是并发闸让「超时」成了常态而非例外 —— 凌晨那一段,任务在拿到 4 个重量级槽之一之前就要先排队,实测 `cmdb.grants` 的 aws-sg 在一次 9 秒的运行前面排了 **1,384 秒**,`cmdb.roles` 的 aws-primary 均值 **1,055 秒**,而它后面那个任务的 cron 只让开了 9 分钟。 **新增 `trigger_type='chained'` + 自引用的 `chain_after_job_id`。** 一条链式行没有 cron 也没有 interval,worker 不给它挂 APScheduler 触发器 —— 上游跑完就是它的触发。外键刻意是 `ON DELETE SET NULL` 而不是 CASCADE:删掉上游应该让下游变孤儿(停跑、并在体检里现形),而不是把它一起删掉;丢一行任务从来不是「丢了它的上游」的正确答案。 **两套机制,刻意分开。** 快路径是执行器:上游到达终态就直接拉起下游,它只管延迟。**保证**是 `scheduler.chain_advance`(每 5 分钟):它比较的是两个时间戳而不是记住一个事件,所以无论快路径是**怎么**漏掉的 —— 发布打断、worker OOM、Redis 抖动、刚刚才配好的依赖 —— 都会收敛,而且条件在下游跑过之后自动消失。任何事件驱动的东西都有一个正好等于「事件没发生」的洞,对账没有。**每跳只推进一层**:在同一跳里把孙子也拉起来,恰好会破坏这套机制要建立的那个顺序;单次上限 12 个,防止一次批量改链把整个车队同时放出去、重演凌晨的排队。 🔴 **链推进的条件是「上游跑完了」,不是「上游成功了」——`ok` / `skipped` / `failed` 都放行。** 这条会让人皱眉,所以说清楚:上面那八对**今天就是无条件跑**的,因为下游有自己的 cron。改成「失败就卡住」是一次**降低覆盖**的行为变更 —— 一次失败的 `leaver_assurance` 会新增地让名册对账**根本不跑**,一次失败的 `period_rollup_refresh` 会让漂移检查再也报不出来。那不是安全特性,那是一次本该无害的重构引入的新故障形状。链买到的是「下游在上游**真的**跑完之后才开始」,不是一个成功前提。唯一的例外是 `interrupted`:进程正在离开,往一次停机 drain 里塞新工作没有意义,开机后对账会把链接上。 **环在写入边界上就不可表达。** 环不是运行时能优雅恢复的状态:每个成员会永远重新触发下一个,每次运行都烧掉一个并发槽和它 handler 碰的厂商配额。PATCH 直接拒(`SCHEDULED_JOB_CHAIN_SELF` / `SCHEDULED_JOB_CHAIN_CYCLE`),运行时另有一道有界游走 —— 环仍然可以从直接改库进来,而每一个读这张图的地方都要走它,无界地走一个环就是 cron 里的死循环。**接上游会替换掉这个任务自己的时钟**:两者都留着不是「更丰富的排程」,是一个周期里跑两次,一次按顺序一次不按。**解除依赖时如果没同时给回 cron 会被拒**(`SCHEDULED_JOB_CHAIN_ORPHANED`)——一条 chained 又没有上游的行永远不会触发,静默留下它正是这条拒绝要避免的。 **迁移 616 转换的六条边,是按一条明确的门槛挑的:下游本来的排程必须已经落在上游的同一天同一窗口内**,这样转换只改变「在窗口内什么时候跑」,不改变别的。两对**故意没转**:`evidence_precompile`(2 号)→ `compliance_posture_summary`(**3 号**)会把一份月度报告提前一天,那是产品可见的变更不是基础设施变更;`cost_facts_monthclose`(5/12 号)→ `cost_recon.aliyun_bq`(14 号)的两天间隔正是那个排程的用意。也排除了 `efficiency_owner_digest`:它是**周报**而它消费的 `efficiency_compute` 是日跑,把周任务接在日任务后面会静默让它变成日跑,对一份摘要来说就是七倍的通知。每条边照旧只在「下游还带着代码播种的那个 cron」时才应用,downgrade 精确还原各自原来的 cron。 **前端**:任务列表在原本显示节奏的那一格改显示「接在「X」之后」(此前的 fall-through 会显示「未配置」—— 而没有节奏正是重点,读起来却像坏了);「容量与体检」页新增任务链面板,按整链耗时倒序、逐步显示各步实测均值与整链总时长(要回答的问题不是「有没有这条边」,而是**这条链还塞不塞得进它的窗口**),并单独告警「上游已被删除」的孤儿行 —— 那种行在任务列表里看起来完全正常;编辑弹窗新增依赖选择器(不改 / 接在某任务之后 / 解除)。三语齐全。排程时间轴也补上了链式任务:它们没有 cron,此前会**从时间轴上整个消失**,现在按「上游的触发时刻 + 上游的典型耗时」画出来并标明这是估算 —— 一个标了是估算的估算,好过一个看不见的任务。 **验证**:29 条新测试(21 条链语义 + 8 条迁移)。**5 处变异验证**:只在 ok 上推进 → skipped/failed 两条红;摘掉环检查 → 红;接上游时保留 cron → 红;对账不避开正在跑的上游 → 红;worker 对链式行打 warning 而不是 debug → 红。`tests/test_scheduled_jobs` + `tests/test_alembic` **461 passed**、`tests/test_core` **578 passed / 2 skipped**;ruff 干净、mypy 与基线同为 11 条;前端 typecheck + 13 道 lint 守卫全绿。**浏览器实测**抓到并修掉一处真缺陷:文案里的 `**加粗**` 会原样渲染成星号(i18n 的 markup 守卫只认 HTML 标签,认不出 markdown),已把新增文案里的星号全部去掉;并通过真实 HTTP 栈验证了链图顺序(depth 0/1/2)、整链时长、孤儿检出、以及闭环 PATCH 返回 400 `SCHEDULED_JOB_CHAIN_CYCLE`。 > **2026-09-06(第一轮)— fix(types): mypy 棘轮在 main 上是红的 —— #3462 留下的 4 条,两条各有一个能真出错的形状(0 迁移 / 0 端点 / 0 MCP / 0 RBAC)** `go-ci`(Backend Release Guard)自 #3462 起在 `main` 上就是红的。#3463 修掉了 savepoint 那一半,mypy 这一半留到现在(`ea01ae86b` 仍红): ``` app/mcp/tools.py: [no-any-return] 148 -> 150 (+2) app/scheduled_jobs/hygiene.py: [operator] 0 -> 2 (+2) ``` **没有抬基线。** `check_mypy_baseline.py` 自己的文案写着 `--update` 只给「确实修不了、且经过复审」的情况用;棘轮的意义就是只许缩不许涨,这四条都是能改的。 🔴 **`hygiene.py` 那两条 `[operator]` 是「字面量先建好、事后再往里塞键」这个写法的必然产物。** `classes` 的三个初值分别是 `str` / `int` / `float`,mypy 对字面量取值类型的**联合上确界**,推出 `list[dict[str, object]]`;随后循环里 `entry["slots"] * 86400.0` 就成了 `object * float`,`entry["demand_seconds_per_day"] / capacity_seconds` 同理。这不是噪声:同一个写法下,任何一次「往 `classes` 里塞一个不是数的键」都不会被这两处算术挡住,而容量模型的分母恰恰是从这里来的 —— utilisation 算错在页面上仍然是一个体面的百分数。改成**算完再 append 一个显式 `dict[str, Any]`**,不再事后写回。三处口径逐字保持:键的插入顺序不变、`utilisation` 的分子仍是**已经四舍五入过的** `demand_seconds_per_day`(不是原始 float)、`capacity_seconds > 0` 的兜底仍返回 `None`。输出形状对前端与 MCP 都是不变的。 **`tools.py` 那两条 `[no-any-return]` 是新工具直接 `return serialize(...)`。** `app/mcp/runtime.py::serialize` 的签名是 `Any -> Any`(它得吃 Pydantic / ORM 行 / dict / 标量,没法用一个具体返回类型描述),所以在声明 `-> dict` 的工具函数里裸返回它必然触发。本文件里早就有既定写法 —— `payload: dict = serialize(...)` 再 `return payload`(`tools.py` 里十几处,例如 18627 行),`scheduled_job_capacity` / `scheduled_job_hygiene` 照抄同一形状,不新造第二种。刻意**没有**去给 `serialize` 加 `@overload` 把 148 条一起消掉:dict 入参在循环引用兜底分支里会返回字符串 `"...[cycle]"`,overload 会把这句写成谎,而修一条红线不值得在序列化边界上留一个假签名。 **验证**:`scripts/check_mypy_baseline.py` 由 1274 回到基线 **1270**(四条全消,无一条靠 `--update` 或 `# type: ignore`);`ruff check app` 干净;`tests/test_scheduled_jobs/test_hygiene_capacity_2026_09_05.py` 18 条全绿(容量模型的口径断言正是这次改动最该盯的地方)。 > **2026-09-05(同日第十二轮)— fix(scheduled-jobs): 被部署打断的运行不再是「失败」—— 30 天里 452 次失败有 386 次是这个假象(迁移 **614** / 0 端点 / 0 MCP / 0 RBAC)** 定时任务域优化第二批。上一批把「看不见」修了,这一批修「看见的是假的」。 🔴 **红队列里五分之四是假的,而机制是三段无辜的代码接在一起。** 生产每天发布约 **15 次**,每次 SIGTERM worker;drain 给在跑的任务 **8 秒**,超时就 cancel;`_run_scheduled_job` 的 `CancelledError` 分支**刻意什么都不写**(注释写得很清楚:这是有序停机不是任务失败);于是运行行停在 `running`,**6 小时后**被僵死行清理器盖上 `failed` + `auto-fail: stale running row swept after 6h (worker likely died mid-run)`。30 天 452 次 scheduler 失败里 **386 次是这一句**;抽样 29 条,**28 条在下次开机后 15 分钟内已经重跑成功**。它们不可确认地躺在红队列里、霸占 `helix_scheduled_job_unacked_failures`、把失败率变成一个虚数。 **新增终态 `interrupted`,并且它刻意不碰两个计数器。** `run_count` / `failure_count` 供着 Prometheus 的恒等式 `helix_scheduled_job_runs_total{ok} = run_count - failure_count`;第三个终态如果只抬其中一边,`ok` 计数器会静默漂移。那两列描述的是**跑完了的尝试**,而被中断的运行什么都没跑完 —— 所以两列都不动,`last_status` 也不动(它是「上一次跑完是什么结果」)。成功率与 SLO 的分母本来就只认 `ok + failed`(Round-62 定的),所以 `interrupted` 天然被排除,不需要再改一处。取消路径也不发失败卡:一天 15 次发布、每次都有重量级云同步在跑,这会是平台里最响也最没用的告警。 **取消时的记账是「新 session + shield + 3 秒上限」,三个修饰词各有原因。** 这段代码执行时任务已经被取消、进程正在离开:*新 session* 因为 handler 自己那个可能正在事务里或已被取消污染;*shield* 因为第二次 `cancel()`(第二个 SIGTERM,或 docker 升级到 SIGKILL 的宽限)不能把记账写一半;*3 秒上限* 因为停机绝不能挂在记账上 —— 单条带索引的 UPDATE 远用不到 3 秒,而 DB 真不可达时我们退回到 6 小时清理器,也就是**退回到这段代码存在之前的状态**,失败模式是「退化」而不是「容器卡住」。 🔴 **清理器现在能分清「死了」和「跑得久」,靠的是问单飞锁还在不在。** `is_lock_held()` 的 docstring 早就写着它是给这种 reaper 用的,而此前没有 reaper 用它。`execute_job` 现在带 `auto_renew=True` 拿锁,并且只在终态写回之后才释放 —— 所以一条 `running` 行、锁却没了,就是**没有主人**(硬杀 / OOM / 容器超过 stop grace 被收走),在这条每小时任务的下一跳就能收敛,而不是等 6 小时。6 小时绝对兜底保留,因为上面那条依赖 Redis。Redis 出问题**失败闭合**:解析不出活性就把行留给兜底,错判一条活着的运行会让第二份拷贝对同一个厂商 API 跑起来。另加 5 分钟启动宽限。 **`auto_renew=True` 不是顺手加的,它是上面那条的前提。** 锁 TTL = 单次超时 + 300 秒 buffer,而**排队发生在锁里面**:生产记录过一次 1,617 秒排队 + 809 秒运行 > 2,100 秒 TTL,锁在运行中过期。不修这个,活性检查会把一个正在干活的任务读成孤儿。顺带把锁 key 的构造抽成 `single_flight_lock_key()` —— reaper 要从另一侧问同一个 key,第二份手写的 key 形状会让它去查一个没人持有的键,然后宣布每一条活着的运行都是孤儿。 **迁移 614 把存量 386 行改判。** 这不是「改写历史」:谓词只认 reaper **机器生成**的那句前缀(一条被人诊断过、写了真实原因的 failed 行永远进不了这个桶,测试里连「文案里提到了这句话」的行都钉住不动);`interrupted` 不是成功,它说的正是原文案已经用散文说过的事,只有那一列在唱反调;两个计数器不动,因为创建这些行的 bulk UPDATE 从来也没抬过它们;原文案原样保留并追加一个标记,所以改判从行本身就看得出来。downgrade 只还原带标记的行,不碰上线后新代码正常写出的 `interrupted`。 **打开 `auto_renew` 顺带造出了第二种「被取消」,所以中断原因不能靠猜。** 锁在持有期间丢失时(Redis 驱逐 / 故障切换 / 手动 DEL),`distributed_lock` 的续期看门狗会**主动取消持有者**再转成 `LockBusy`。把这种情况写成「发布时的优雅停机」会让运维去翻一份根本不存在的发布记录。worker 在开始 drain **之前**先置一个 `_DRAINING` 标志,执行器据此选词 —— 一条测试直接读 `_stop_schedulers` 的源码钉住这个顺序(变异验证:把置标志挪到取消之后 → 红),因为能坏掉的正是「有人把这行挪下去」。 **观测**:新增 `helix_scheduled_job_runs_interrupted_24h{handler_key}` gauge。因为 `interrupted` 被排除在失败率之外,一个每晚都被杀的 worker 会在指标里彻底隐身 —— 发布日的尖峰是自解释的,而安静的一天上有一条非零地板,意味着 worker 正在因为没人看过的原因被杀(OOM、stop grace 不够)。窗口式而非累计式:运行台账是按保留期裁剪的,从它派生单调计数器正是 Round-62 修掉的那个 bug。 **前端**:三处状态标签收编成共享组件 `ScheduledJobStatusTag`(「被中断」单看像故障,而它的意思正相反 —— 解释必须跟着标签走,而不是写在恰好加了它的那一页);运行状态筛选器与分析页的日趋势都补上 `interrupted` 序列(`runs_in_window` 是所有状态之和,少一条序列就会让图表的堆叠总数和头部 KPI 静默对不上 —— 这正是当年 `running` 序列被补上的原因)。运行状态联合类型此前在 API 客户端里写了 5 份,已收敛成一个 `ScheduledJobRunStatus` 别名。三语齐全。 **验证**:15 条新测试(11 条中断语义/清理器活性/锁 key/drain 顺序 + 4 条迁移 614)。**4 处变异验证**:摘掉取消分支 → 中断测试红;摘掉 `auto_renew` → 续期测试红;让清理器无视锁活性 → 「活着的长任务不许动」与「Redis 挂了要失败闭合」两条红;把 `mark_draining()` 挪到取消之后 → 顺序测试红。`tests/test_scheduled_jobs` + `tests/test_alembic` + `tests/test_core` 全绿;ruff 干净;mypy 与基线同为 33 条(新写的 `.rowcount` 用了仓库既有的 `getattr` 形态,没有新增第 34 条);前端 typecheck + 13 道 lint 守卫全绿。 **顺带发现并已分头修掉:savepoint 隔离守卫在 main 上本来就是红的**(checkout `origin/main -- app tests` 后同样复现),四个文件超出 `savepoint-baseline.json` 的配额,形状全是「逐条循环里吞掉写操作的异常」。本 PR 只修自己那一条(`hygiene.py` 是只读 SELECT,按守卫文档打 `# savepoint-exempt:`);其余四条由同日的 #3463 单独修掉 —— 刻意不在这里顺手抬基线,抬基线等于把唯一的信号删掉。rebase 时 `hygiene.py` 的标记与 #3463 撞了,取先落地的那份措辞并补上本 PR 多说的那半句(前置闸的 handler 自己会再查一遍)。 > **2026-09-05(同日第十二轮)— fix(txn): savepoint 棘轮在 main 上是红的 —— 四个「一个失败不能拖垮整批」的承诺,其实一个都不成立(0 迁移 / 0 端点 / 0 MCP / 0 RBAC)** `tests/test_core/test_savepoint_guard.py::test_baseline_file_is_in_sync_with_the_tree` 在 `origin/main` 上就是红的(checkout `origin/main -- app tests` 原样复现),五个文件超出 `savepoint-baseline.json` 配额。棘轮**只许缩不许涨**,所以没有抬数字这个选项 —— 逐个读、逐个判。 🔴 **四处是真的 2026-08-06 Zoom 坐席事故形状。** 逐项循环体调用写库函数,外面裹 `except Exception` 说「一个失败不能拖垮整批」—— 而失败的 `flush()` 会让**整个事务**失效,于是吞掉的那次「成功」了,**后面每一次**迭代都以 `PendingRollbackError` 告终。承诺是反的:一个失败恰恰拖垮了整批,还给出 N-1 条看起来很合理的假错误。四处按 `app.core.txn.best_effort` 包 SAVEPOINT,失败走 `step.ok`: * `apikey/idle_alerts.py::sweep_idle` —— 第一把 Key 一炸,后面全部跟着炸,IT 拿到的是一张**被截断的闲置名单**,而摘要里的 `errors` 有 N 条; * `sso/removal.py::SsoRemovalService.reconcile` —— 后面的 grant **拿不到撤销任务**,IdP 侧的清理从此没人追; * `access_certification_coordinator.py::enqueue_self_service_removal_for_cert_item` —— 那句「决定已保留、标记为 failed」死在它**自己的** `db.flush()` 上,员工的自证请求 500,决定真的丢了; * `apikey/service.py::_sync_attestation_items` —— 「决定本身不能失败」死在调用方的下一次写上,整个 approve/reject 回滚。 **一个反直觉的副作用**:savepoint 回滚会**过期**块内弄脏的每个对象,主键也不例外。日志行里的 `item.id` 于是变成一次同步惰性加载 → `MissingGreenlet`。四处一律在进块**之前**把 id 取出来;凭证域那处另加一次显式 `db.refresh`,让「重新加载」不隐式依赖后面那次 flush 的顺序。 **三处是真的安全,给了理由而不是数字。** `apikey/service.py` 的 `reconcile_submission_intents`(**逐 intent commit 后继续干活** —— SAVEPOINT 会被那次 commit 关掉,正是 `txn.py` 明令不许包的形状;两个 handler 本来就先 rollback)、`_notify_transfer_rotation_manual` 的管理员解析(纯只读)、`scheduled_jobs/hygiene.py` 的集成前置闸(单条只读 SELECT,失败开放)。转岗轮换那处 `start_rotation` **提交两次**(云调用前的防泄漏墓碑 + 之后的原子换绑),既不能包 SAVEPOINT,**也不能**在 handler 里 rollback —— precheck 阶段抛错时 rollback 会静默撤销上游 `apply_transfer` 的归属改写,「丢了转手却报成功」比一次响亮的失败更糟;理由写在标记里。 **棘轮缩了一格**(`apikey/service.py` 的 1 → 移除条目;总量 33 → 32)。 **验证**:新增 `tests/test_core/test_savepoint_isolation_call_sites_2026_09_05.py` 4 条,每条注入的都是**真实 DB 失败**(指向不存在行的外键插入),不是 mock `raise` —— 后者不会让事务失效,根本分不出修好的和坏的。变异验证:把 `best_effort` 里的 `async with db.begin_nested()` 摘掉 → 四条全红,报的正是 `PendingRollbackError`;装回 → 全绿。`tests/test_core` + `tests/test_apikey` + 四个域套件全绿;ruff 零新增。(mypy 棘轮在 `app/mcp/tools.py` 与 `hygiene.py` 上本来就是红的 —— 与本 PR 无关,hygiene 这边的改动只有注释。) > **2026-09-05(同日第十一轮)— feat(scheduled-jobs): 台账体检 + 执行容量模型 —— 一个任务吃掉七成重活算力,而管理台看不见它(迁移 **613** / +2 端点 / +2 MCP → hint **620** / 0 RBAC)** 用户问「定时任务这块有什么可以合并或者优化的」。**先量再改**:只读拉了生产 `scheduled_jobs`(344 行 / 294 启用)与 30 天 `scheduled_job_runs`(12,322 行),对上代码里 AST 抽出的 202 个已注册 handler。结论是**不该合 handler** —— 同一个云账号一天的全部同步串起来 alicloud 均值 3,073s / 最差 5,042s,超过默认 1,800s 单次超时;按「云账号 × 能力」拆行是迁移 046/418 定下的,一步失败吞掉其余步骤的结果与告警。真正的问题在别处,这个 PR 是第一批: 🔴 **一个任务占了重量级 77% 的算力,而它三次里有两次什么也没发现。** `cmdb.resource_directory_refresh` 每 15 分钟一跑、每次 400~450 秒全量投影 106,518 行,**41,095 slot-秒/天**,永久占住 4 个 heavy 槽中的一个;30 天 94 次成功里**只有 27 次**有任何变化 —— 因为它投影的源表自己是 4h/12h 节奏(迁移 418),四次里有三次在重算「什么都没动」。改每小时:仍然远快于源表的新鲜度,每天还回约三个重量级槽小时。同批四条同源纠偏:`cmdb.resource_inventory_refresh`(每小时 heavy,最近 100 次全部 `inventory_skipped=8, seen=0` —— 广覆盖是逐集成 opt-in 而没人 opt in)改每日**而不是停用**,停用需要有人在将来记得它,每日则自己在 24 小时内发现 opt-in;两个半年度开盘任务(`approval_registry.owner_confirmation_semiannual` / `auditor.access_self_attestation_auto_open_semiannual`)每天跑、只在 6/1 与 12/1 后 7 天内真开盘,365 次里 351 次只为回答「不」—— cron 改成 `1-7 6,12`,和 handler 自己的 `[boundary, boundary+7d)` 谓词**同集合**(有参数化测试直接对着 `due_boundary` 钉,不是抄一份日期算术);`cmdb.auto_owner_grant_backfill` 每 10 分钟、单次 16~51 秒、最近 100 次 `scanned=1 fixed=0`,4,143 秒/天,改每小时。**每一条改写都带 `AND cron_expr = :expected` 守卫**(沿用迁移 418 的纪律):管理员已经调过的行代表一个这次迁移不知道的判断,静默盖掉比留着旧默认更糟;downgrade 用同样的对称守卫。 🔴 **35 行绑定在已停用集成上,每天各占一次 heavy 槽只为发现自己没事可做。** 每个 per-scope 云 handler 本来就会返回 `{"status": "skipped", "reason": "integration disabled"}` —— 但它是**在 handler 内部**发现的,那时槽已经拿到手、session 已经开了,而且正好发生在实时同步排队的凌晨。新增 `integration_gate_state()` 在**拿槽之前**判定,handler 内的检查作为纵深防御保留。两个刻意的设计:① **失败开放** —— 解析集成出任何错都放行让 handler 决定,一个卫生优化绝不能成为同步没跑的原因;② **只记状态转移** —— `MAX_RUN_HISTORY_PER_JOB=100`,一个永久关闭的集成如果每跳写一行相同的 skip,几天内就会把这个任务的真实历史挤掉,也就是把第一行想保住的那个证据本身冲走。变异验证:把去重改成永远记 → 「只有一行」的测试红;把整个前置闸短路 → 三条测试红。 🔴 **「这一行为什么不干活」在产品里没有答案。** 新增 `hygiene.resolve_job_health()`,把五种在列表里长得一模一样的失效形状分开命名:`handler_missing`(handler 改名后旧行没退休,永远跑不起来)/ `integration_missing`(集成行已删)/ `integration_disabled`(集成关了,每跳跳过 —— **合法状态**,重新启用集成会自动恢复)/ `never_run`(启用超两天从未触发)/ `idle_skipping`(近两周 ≥10 次运行**全部**是跳过)。两次查询覆盖整页(集成状态 + 一次分组聚合),不是逐行 N+1。`never_run` 带两天宽限期 —— 今早播种的月度 cron 不是坏了。 **「为什么晚点 20 分钟」也终于有答案。** `capacity_summary()` 把运行台账变成需求 vs 槽位天花板:按权重类的每日 slot-秒占用率、按 UTC 小时的需求与排队热力、按任务排名的消耗者、以及排队最久的任务。**全部取自实测墙钟,不解析 cron 表达式** —— cron 说的是计划,台账说的是实际,两者不一致时运维需要的是后者。生产实测这套模型立刻答出:云同步全部加起来一天只要 3.5 个槽小时(容量 96),凌晨排队是**队头阻塞**不是容量不足 —— 4 点同时到期 33 条 heavy,aws roles 1,055s / alicloud 指标 1,726s 三条长任务占满剩余槽,导致自己只跑 9 秒的 `cmdb.grants.aws-sg` 平均排队 **1,384 秒**。排名按「每天占用 = 每天次数 × 平均耗时」,不是单次耗时 —— 后者会把该动的行排到看不见的地方。失败运行**不计入**需求:一次撞超时被杀的运行是真实墙钟,但不代表这个任务平常需要的时间。 **新增 `scheduler.ledger_reconcile` 日体检 cron。** 台账是本仓唯一没有主人的表:行由迁移播种、用无类型 JSON 绑定集成、被绑的东西消失时没有外键可级联。它**只报不改**,唯一动手的一种情况是「绑定的集成行已被删除」—— 这一行在任何未来状态下都不可能再跑,自动停用 + 记审计,重新启用只要一次点击。**刻意不 raise**:本仓拿告警的常规手段是抛异常(`identity_sync.staleness_watchdog` 就是这么报漂移的),但在这里用它会把一次**完全成功**的运行记成 `failed`、抬高 `failure_count`、踩掉自己的 SLO —— 和 `_run_status_for_summary` 在另一个方向上防的是同一类台账谎言。证据落在审计日志、运行摘要、体检面板三处,都不需要一张红卡。 **前端**:`/admin/scheduled-jobs` 新增「容量与体检」Tab —— 权重类占用率进度条、按小时的需求与排队双序列柱图、消耗排行表(带最长耗时/最长排队的 tooltip)、体检面板按病因分组并可一键跳到筛好的列表;任务列表新增健康标签(带解释 tooltip)与「重」权重标签、健康态筛选器(`?health=` 可深链)。三语齐全。**+2 只读 MCP**(`scheduled_job_capacity` / `scheduled_job_hygiene`,1:1 对齐两个新端点,hint 618 → 620)—— 只读是刻意的:它们的用途是解释一个 cron 为什么晚点或空转,而对应的动作(改节奏、停用、重新启用集成)都是已有的、带审计的人类操作。 **验证**:新增 17 条 hygiene/capacity 测试 + 12 条迁移 613 测试(含幂等、守卫不覆盖管理员改动、downgrade 对称、新行 handler 必须已注册 —— 否则 worker 的开机守卫会在下次发布时硬崩)。三处变异验证如上。`tests/test_scheduled_jobs` + `tests/test_alembic` 共 **416 passed**;ruff / mypy 零新增(11 条 mypy 报错在改动前的基线树上一字不差地存在);前端 `pnpm typecheck` / `pnpm lint`(含 i18n 平行度、图表主题、内链等 13 道守卫)全绿。 > **2026-09-05(同日第十轮)— fix(migrations): 迁移 612 的 `sa.Uuid()` 把生产迁移链卡死在 611;顺手把这个盲点补进 TiDB-parity 守卫(0 迁移新增 / 0 MCP)** 发布转岗复核那批时,`alembic upgrade head` 在生产上炸了 —— 不在我的 610/611(两条都干净应用了),而在**别人的 612**: ``` (3780, "Referencing column 'person_id' and referenced column 'id' in foreign key constraint 'fk_1' are incompatible.") ``` **根因是一个名字。** 本仓每个模型都写 `from app.core.sql_types import GUID as Uuid` —— 模型里的 `Uuid` 是 **CHAR(36) 的别名**。迁移文件里的 `sa` 却是真正的 SQLAlchemy,而 **`sa.Uuid()` 在 MySQL 上渲染成 CHAR(32)**。于是同一个词在两个文件里指两种类型:612 建出的 `person_id` 比 `identity_persons.id`(生产 CHAR(36))窄四个字符,外键被直接拒绝。 **为什么测试全绿。** 测试库是从 **ORM metadata** 建的 —— 那里父表和子表**都是**那个 CHAR(36) 别名,两边一致,不存在矛盾。矛盾只存在于**真实迁移链**里,因为链上的父表 CHAR(36) 来自很多年前的另一条迁移。**这就是它必须是一道文本守卫、而不是一条测试的原因。** 修复两层: 1. **612 改用 `id_type_for("identity_persons")` + `table_kw_for(...)`**(本仓既有助手,读 information_schema 拿父表的类型**和排序规则**)。612 在任何环境都没成功应用过 —— 它在哪里都会以同样的 3780 失败 —— 所以就地改是安全的,不需要 613 补丁(而且也补不了:612 会先炸)。空库上跑完整链现在到达 **612**,子列与父列逐字段一致,外键建成。 2. **守卫补第 (1c) 类**:迁移的 DDL(`op.create_table` / `op.add_column`)里出现 `sa.Uuid()` 一律拒绝。与 (1)/(1b) 不同,**这一类不看有没有外键** —— ORM 按 CHAR(36) 查询一个 CHAR(32) 的列,本身就已经错了,哪怕它是主键。为 bulk INSERT 搭的轻量 `sa.Table(...)`(迁移 545)不发 DDL、不声明宽度,不算。变异验证:把 612 退回原样 → 守卫红并逐行点名两列;改回 → 全树绿。5 条新单测(捕获 / add_column / `id_type_for` 正确形态不误报 / 545 形态不误报 / 豁免标记生效)。 顺带修正:上一条 CHANGELOG 写的 MCP hint 是 **617**,合并时与并行分支撞号后按 `len(@mcp_server.tool)` 重数为 **618**,树里就是 618;那行数字已订正。 > **2026-09-05(同日第九轮)— fix(role-change): 转岗复核四个 PR 的合并后复审 —— 七处修复,其中两处是同一个事故换了个粒度又回来了(0 迁移 / +1 端点 / +1 MCP → hint **618**)** 四个 PR 全部合并后按仓库规矩做对抗式复审(4 轮,重点审「修复本身」)。七处,按严重度: 🔴 **1. 「回收全部」的形状在 role 粒度上活了下来。** PR3 的 `policy_universe` 拦住了「**空策略表**⇒ 什么都是多余的」,但它对「**空期望**」无能为力:一个人转入**一个自己没有任何策略的部门**时,`expected` 仍然是空集,于是他持有的、落在**全局** universe 里的每一项都会被判成 `policy_unexpected`。这就是 `preview_role_change` 那个「对每个人回收全部」的形状,从表粒度降到了角色粒度 —— **同一个事故换了个粒度又回来了**。修法:policy 判定需要**两个**条件 —— 策略**本来可能**被写到这类持有物(`universe`),**并且**策略确实写到了**这个角色**(`matched_any`)。「没有策略匹配这个人」意味着*我们不知道这个角色该有什么*,不是*这个角色什么都不该有*。变异验证:去掉 `matched_any` 那半 → 新测试红。通配策略(`department_name IS NULL`)仍然算匹配,另有一条测试钉住。 🔴 **2. 夜间 cron 的 MissingGreenlet。** 差异引擎里用 `IdentityPerson.primary_department` 做部门名回退 —— 那是一个走 `org_memberships` 关系的 Python property。虽然映射声明了 `lazy="selectin"`,但 `db.get` 拿到的、commit 之后**已过期**的实例,一碰这个 property 就是从同步代码里发起 IO → MissingGreenlet。**只在「包裹的部门码查不到组织节点」这条分支上触发**,所以躲过了此前所有测试,而它炸的是新加的夜间重算 sweep。改成按 SQL 查。变异验证:把 property 访问放回去 → 红。 **3. 引擎的核心承诺此前没有任何东西在守。** `build_review_packet` 会跑差异引擎,但 `review_backfill` 只为「没有包裹的移动」调它 —— 于是既有包裹的差异被**冻结在建它的那一刻**,而引擎的全部承诺正是「空策略表时建的包裹,会在策略配好的那天开始有意义」。没有这一步,那句承诺需要有人记得**逐份**点「重新扫描」。现在那条 cron 同时重算开放包裹(按 `delta_computed_at` 最旧优先,`limit` 内轮转),并有测试钉住它**复活不了** withheld 戳或任何已做的决定。 **4. 同一条规则写了两遍。** 「同时改了部门和经理的移动**是**一次部门变更」这条优先级,既决定控制台的标签,也决定**要不要建包裹**。控制台自己实现了一遍 —— 两份拷贝会让控制台说一套、包裹按另一套建,而且任何一边被改动的第一天就会漂移。改成调 `classify_move`,并有一条测试对四种组合逐一比对两者。 **5. 差异横幅在你答完之后还在催你。** `delta_items` 是关于**这次移动**的事实,不随决断减少 —— 于是刚答完四项的人看到的还是「让 4 项需要重新判断」。新增 `delta_undecided`(读时算,因为它取决于决断,而引擎分类时不可能知道),横幅在还有剩余时报**剩余**、答完后换成「这 4 项你已经全部答完了」。 **6. preflight 的两处误导。** ① 一份「有真实差异、但来源不在认可清单里」的包裹被记成「没有差异」—— 那会告诉操作者平台什么都没找到,而实际是他自己配置成不关心;而这**恰好是三个桶里唯一他能在当前弹窗里改的**。新增第三个桶,并且**顺序**是先测差异下限再测来源:两者都不满足时说「来源被拒」会把他指向一个改了也没用的开关。② 扫描此前**无上界** —— 今天十几份没事,一千份就是弹窗超时;加上界并在触顶时明说「以上是下限不是总数」。 **7. MCP 同 PR 补工具(本仓 NON-NEGOTIABLE)。** 新增的自助面 `GET /role-changes/my-scope-grants` 漏了它的 1:1 MCP 工具。补 `list_my_cloud_scope_grant_reviews`(**只读** —— keep/revoke 是人的动作,而 revoke 会拆真实的云 IAM 绑定),hint 616 → **618**(合并时与并行分支撞号,按 `len(@mcp_server.tool)` 重数),并核过 `len(@mcp_server.tool)` 与 hint 相等。 **另外**:删掉一句自己编的数字(某处注释写了「unactionable for eighteen months」,而那条 sweep 从迁移 236 起才存在,是几个月;一个没人核过的数字正是会误导下一个读者的东西);新增 `RoleChangeEntry.test.tsx`(6 条:管理员渲染控制台不变 / 别名与 leadership 读档都放行 / 普通员工带卡片链接落到自己的包裹 / 不带则回收件箱 / **不代非管理员发出任何 admin 请求** / 构造的 `review=%2F%2Fevil.com` 不能把人带出站点)。 **验证**:后端全量 / 前端 1431 条 / lint 13 道闸 / build 全绿;三处修复各自做了变异验证。 > **2026-09-05(同日第十一轮)— feat(access-lifecycle): 访问对象闭环 PR4 —— 闲置坐席回收从「只认 Atlassian」扩到多厂商;拿不到活跃度的厂商如实说「看不见」而不是装作零闲置(迁移 612 / +2 端点 / +1 cron / +1 MCP → 617)** `software_seat.idle_reclaim` 有一台做得很完整的状态机(警告 → 宽限期 → 自助保留 → 回收),但它**只能回收 Atlassian 的坐席** —— 因为 Atlassian 是唯一一个 Helix 会读活跃度的厂商。Google Workspace 与 Zoom 的付费坐席只能靠人注意到。**这一轮不重建那台状态机,只换它的证据来源。** **新表 `asset_seat_usage_signals`**:`(人 × 厂商 × 产品) → 最后活跃`,由各厂商采集器写、由回收作业读。加一个厂商 = 加一个采集器,不是改状态机。承重列是 `state` 而不是 `last_active_at`,四态:`active`(有真实时间戳)/ `never`(厂商**明确**说从未登录)/ `unknown`(厂商答了但没给可用值)/ `unsupported`(该厂商根本答不了)。 🔴 **`unknown` 和 `unsupported` 绝不能读成「闲置」。** 同一个错误这个仓库犯过两次:身份同步零信任对账首跑 48 条里 36 条误报,是把「快照作证不了」当成「账号还开着」;2026-06-11 之前的闲置坐席尝试把 sandbox 冻结的时间戳当真,把日活用户判成两年没用。所以四态一路带到界面,不在中途拍平成一个数字。 **`never` 是可回收的,但闲置时钟从「发放坐席」那天起算** —— 不是从一次没发生过的登录起算。少了这一条,今早刚发的坐席就是全公司最闲置的那一个。 **新鲜度闸**:每行带 `collected_at`,超过 36 小时的行一律降级回 `unknown`。所以**采集器坏掉会让回收作业停止回收**,而不是拿着过期证据开始回收 —— 对一个会撤权的作业,只能往这个方向失败。 **管理员守卫要求「肯定的判定」**:厂商说不出这人是不是管理员,就按管理员处理、跳过。Zoom 只有明确的 `role_id=2`(Member)才算非管理员,字段缺失或编码不认识一律当管理员。**判错方向的代价不对称**:少回收一个坐席 vs 撸掉一个账号所有者的权限。 **新页「软件管理 ▸ 坐席使用信号」**,两半:先是**各厂商覆盖情况**(能不能看见、快照多新),再是逐人信号。**Slack / 飞书 / GitHub / Microsoft Graph / NexusCRM / manual 六个厂商逐条写明为什么看不见**(都对着本仓驱动核过,不是猜的:Slack 的 `users.list` 没有活跃度字段、SCIM 也没有;GitHub App 没有 audit log 权限、而且 App JWT 根本打不了 `/users/`;Graph 的 `signInActivity` 要 Entra P1+ 和 `AuditLog.Read.All`,这是唯一一条「license/scope 差一步」而不是「API 不存在」的)。这一半是整个功能最该有的一半 —— **「没有闲置坐席」和「这个厂商我们根本看不见」在报表里长得一样,意思相反。** **注意事项落在行上,不落在页脚**:一条过期快照渲染成 `未知` 药丸 + 旁边「曾报活跃 · 92 小时前」,而不是 `活跃` 药丸加一条页面顶部的警告条。页脚的 caveat 会被跳过,读者正在看的那一格里的标签不会。 **覆盖闸**:`test_every_seat_provider_has_a_usage_decision` 从**驱动注册表**枚举 `software_provisioning` 的 9 个 provider,每一个要么有采集器、要么有一条写明理由的豁免 —— 与 PR3 的 T+1 注册表闸同一个形状,防的也是同一件事:新加一个厂商,它的坐席悄悄不出现在闲置报表里,而没有任何东西是红的。 **MCP +1(617)**:`seat_usage_signal_coverage`(只读)。这一轮**最该**有孪生的就是它 —— AI 客户端在引用任何闲置数字之前必须能问到「这个厂商我们看得见吗」。回收动作本身**仍然不给工具**,同 PR3 不给「按人回收账号」的先例。 🔴 **自己探自己的解析器,揪出两个 bug,其中一个是「对的答案、错的原因」。** 把每个厂商真实返回的字符串逐个喂进解析器:① `2026-08-30T02:14:11.000Z`(一次普通的 Google 登录)被解析成 `unknown` —— 截断小数秒时按「从整段尾巴里抓数字」写,把 `+00:00` 时区偏移的数字也抓走了,字符串变得解析不了。不危险(只会少回收),但 Google 采集器会**看起来健康地什么都不做**。② `1970-01-01T00:00:00.000Z`(Google 对「从未登录」的哨兵值)也返回 `unknown` —— 看着是对的,但**只是因为解析崩了**,哨兵从来没被识别过。一条只断言「不是 active」的测试会以错误的理由通过,所以现在**显式断言 `never`**,并与空值/垃圾值那些合法的 `unknown` 分开测。这个区分在下游有牙齿:`never` 可回收(时钟从发放日起算),`unknown` 永远不可回收。 **路由顺序**:两个新端点**放在 `/{asset_id}` 之上**。FastAPI 按注册顺序匹配,声明在 UUID catch-all 之后的字面量路径永远跑不到 —— 它会拿自己的名字去 422「invalid character」。端点测试抓到的,处理函数本身没问题。 **验证**:后端 `tests/test_usage_signals`(21)+ `test_scheduled_jobs` + `test_asset` + `test_mcp_tools_surface` + `test_core/test_migrations` = **1298 passed, 2 skipped**;既有的 11 条 `test_idle_reclaim` 全程保持绿(Atlassian 语义逐字未变)。**变异验证 5/5 转红**:去掉新鲜度闸 / 管理员守卫改成 fail-open / `never` 时钟改回从纪元算 / `unknown` 当成闲置 / 恢复「Jira 没配就整个作业 return」的老早退(那会让不用 Atlassian 的租户所有 Google/Zoom 坐席静默不可达,而运行看起来完全健康)。迁移在真库上 `612 → 611 → 612` 往返,建表/删表、cron 播种/删除、NOT EXISTS 重跑守卫都验过。前端 `pnpm typecheck` + `pnpm lint`(13 个 guard)+ `pnpm test` **1421 passed**。 > **2026-09-05(同日第八轮)— feat(role-change): 转岗复核 PR4 —— 重新启用不再是一次纵身一跃,以及云 scope 负责人终于能回答那张问他的卡(0 迁移 / +2 端点 / 0 MCP)** 前三轮:停推送 → 页面能看 → 差异算得出来。这一轮补的是**把开关交回给人**所需要的三样东西。 **① 重新启用的 preflight —— 「如果现在打开,会发生什么」。** 在此之前,想知道重新打开推送的爆炸半径,唯一的办法就是打开它。**9/5 那九张卡就是这么来的。** 新增 `GET /role-changes/review-config/preflight`:**一封也不发**,用**发送路径自己的谓词**(`settings.may_push`,不是第二份会漂移成乐观主义的拷贝)把开放队列跑一遍,并且**两半都报**:会发出去多少张、被拦下多少份、分别因为什么。只数发送的那一半会恰好藏起操作者最需要核对的那个数。**而且报到人**——「9 张卡」和「9 张卡,其中 5 张给同一个人」是两句不同的话。策略弹窗打开时自动跑一次,改完开关再跑一次。 🔴 **preflight 刻意用「开关强制为 ON」来模拟。** 用当前(关着的)状态去算会返回 0,而操作者问的是「我打开会怎样」—— 返回一个 0 只会教会他这件事很安全。返回体里带 `push_enabled: true` 说明这是个假设不是现状。 **② 云 scope 负责人终于能回答那张问他的卡。** `role_change.scope_review_sweep` **一直**把卡同时发给 scope 负责人和 IT,而 scope 负责人常常是普通员工:卡片指向 admin-only 的控制台,`PUT /role-changes/grants/{id}/review` 又是 `require_admin` —— **它请一个人去做决定,而那个地址他做不了决定**。这与经理那张卡是同一个缺陷,换了个域,也是这条 sweep 被关掉的原因之一。 三处一起修:端点改成「global_admin **或本条授权所在 scope 的负责人**」(按 scope 逐条判,不是给云授权开一道普适的门 —— 我们问他的前提正是「你知道**你这个 scope** 的访问为什么存在」);卡片按收件人分发**不同的落地页**(负责人去自己的待办,管理员去控制台),模板正文因此**不再写死页面名** —— 写死一个,对另一半收件人就是错的;负责人的落点是「我的待办」新增的第 14 个 tab「转岗后的云授权」,列出他名下 scope 上被标记的授权,带保留 / 回收。 ⚠️ **不是把他送到 scope 详情页** —— 那是最顺手的猜测,也是错的:那一页自己的「pending」tab 是**等他审批的申请**,是另一种 pending,他会落在一个不包含卡片所问之事的页面上。**并且这个 tab 的回收按钮明说「与转岗复核不同,这一项点确认会真的开始回收云侧 IAM 绑定」** —— 复核包裹只记录,这一条会动手,两者放在同一个收件箱里,不说清楚就是陷阱。 **③ 通知分类从 `lifecycle` 里拆出来。** 此前 `role_change` 前缀落在 `CAT_LIFECYCLE`,两个后果:**桶不对**(它在 `info`,而这张卡是在要一个人做决断,红点该为它亮);**粒度不对**(一个想关掉「转岗复核」的经理,会连带关掉入职、离职、HRIS 同步、identity_sync 和 procurement 的推送 —— 一个只能整片静音的开关,最后被按下的方式就是整片静音)。新类别 `CAT_ROLE_CHANGE`:action 桶、可关、员工可见,**排在 `lifecycle` 之前**(分类器返回第一个命中的类别)。有一条测试钉住「拆出来没有把兄弟们带走」。 **顺带删掉一个空转的开关**:`admin_digest_enabled` 从配置里移除。它承诺了一个 IT 侧汇总,而**没有任何代码读它** —— 一个配置界面里读不到的开关是一句谎话,而且 IT 的覆盖本来就有(两条只写数据的 cron 失败会 raise,走既有的失败通知)。 **验证**:新增 [`test_role_change_reenable_2026_09_05.py`](../server/tests/test_hr_lifecycle/test_role_change_reenable_2026_09_05.py)(15 条):scope 负责人能决断自己 scope 上的授权 / 不能决断别人的(403)/ 无负责人的 scope 只有管理员能决断 / **sweep 给两类收件人不同的落地页**(断言里写明为什么 scope 详情页是错的修法)/ 分类拆出来且没带走兄弟 / preflight 两半都报、模拟 ON、排除已拦下与已发送、无复核人的包裹单独计数、**用发送路径自己的谓词**(靠移动 `min_delta_items_to_push` 和 `push_baseline_sources` 让它跟着变来证明,而不是读代码)/ 负责人队列只含自己的 scope、决断后离队、没有 scope 是空队列不是报错。deep-link 契约新增 `?tab=cloudGrantReview` 映射(那条闸在提交前就抓住了这个新 URL)。 > **2026-09-05(同日第十轮)— chore(asset): 回填在生产跑完了,而天花板不是我写的「约 50%」,是实测的 36.6%(0 迁移 / 0 端点 / 0 cron / 0 MCP)** 发布之后按既定顺序在生产跑完了资产金额回填(dry-run → apply),**同时发现我自己此前写进脚本、PLATFORM、DECISIONS、ROADMAP 和两条 CHANGELOG 的那个天花板数字是错的**。 **实测(生产,2026-09-05)**: | | | |---|---| | 在册资产 | 1050 | | 回填前完整 | 290(27.6%) | | pass 1 补币种 | 42 行 | | pass 2 同型号中位数 | **52 行** | | ↳ 同型号有价样本 < 3 个而跳过 | 502 行 | | ↳ 样本极差 > 1.5x 而跳过 | 3 个型号 | | ↳ 样本币种混合而跳过 | 1 个型号 | | 回填后完整 | 384(**36.6%**) | | 写入总行数 | **94** | 🔴 **我原来写的是「692 件里约 200 件可估、两遍加起来约到 50%」—— 那是落笔前的估算,实测是 52 件、36.6%,高估了约 14 个百分点。** 结论本身不变(仍在 30 分档,过 90% 只能靠财务台账走对账页),但一个没被标成估算的估算数字已经被抄进五个地方。**六处全部按实测值更正,并在脚本里写明哪些数字是量出来的。** 这正是「容量/吞吐数字落笔前问一句『这是量出来的还是读出来的』」那条纪律的又一次学费。 ⚠️ **顺带一个真机制:两遍脚本的 dry-run 会低报 pass 2。** pass 1 给 42 行补上币种,而「有价同型号样本」要求**金额和币种都有** —— 那 42 行只有在 pass 1 真的写入之后才成为合格样本。所以 dry-run 预测 50 行、apply 实写 52 行。**apply 的行数只会 ≥ dry-run,不会更少**,已写进脚本文档,免得下次有人把这个差值当成 bug 查。 **取证(不是只看脚本自己的输出)**:直连生产 TiDB 独立复核 —— 四字段完整度 `384/1050 = 36.6%` 与脚本一致;**反向 needle「有金额但无币种」= 0**;`purchase_cost_source` 分布 `recorded 998 / estimated_model 52`(估算值没有混进发票值);审计行 `asset.purchase_currency_backfilled 42 + asset.purchase_cost_estimated 52 = 94`,与写入行数逐条对得上,detail 带 `old_currency` / `new_currency` / `pass` / `reason`,整轮可从审计日志回溯。⚠️ 查审计时先按 `trace_id LIKE 'backfill:%'` 查**返回 0 行** —— `AuditService` 落库的 `trace_id` 是派生 UUID 而不是原始字符串,差点被误读成「脚本没写审计」;判据是先确认表里有没有对应的 `action`,再谈 trace 匹配。 **发布取证补齐**:上一轮汇报里「AWS 会话过期所以 `docker inspect` 没做」是错的写法(ljq 长效 IAM key 一直可用)。已用 key 在主机上核实:`compose-backend-1 / compose-worker-1 / compose-frontend-1` 三个容器的 `Config.Image` 全部是 `sha-1a79882ef010a993e0f4ddfa7f380f269be05147`,均 `Up (healthy)`。 > **2026-09-05(同日第十轮)— fix(mobile): 被取消的离职单留下的 blocker 行是「冻住」的 —— 管理员行动台把它们当成永远清不掉的紧急事项(0 迁移 / 0 端点)** 线索来自并行的资产会话:它在入职侧踩到「终态流程的 blocker 行没有任何东西会再写」,并提醒离职侧可能有同构问题。**核过之后:前提成立,后果只落在两个面上,其余读者都是对的。** **前提**:`cancel_process` 把流程翻成 `PROC_CANCELLED` 并**刻意不动** blocker 行(误标离职的正常路径),而 `offboarding/service.py` 的 `reconcile_blockers` 对终态流程**显式抛 409 `PROCESS_TERMINAL`** —— 所以那些 `pending` 行是冻住的:没有任何东西会解决它们,也没有任何管理员动作能清掉它们。`complete_process` 在有 pending blocker 时会拒绝完成,所以**取消是唯一来源**(这一条决定了修复只需要看 cancelled,也决定了回归测试要 cancel 而不是 complete)。 **两处真缺陷,都在管理员面**:`mobile/action_inbox.py` 的 `_provider_leaver_blockers` 把它们列成 `urgent` 行动项 —— 而且因为按 `created_at` 倒序取 `_PER_SOURCE_CAP` 条,**一个刚被取消的离职单的死行会把真正需要处理的活行挤出收件箱**;`mobile/aggregate.py` 的 `admin_offboarding_blocked` 把它们的流程计进首页角标,一个只增不减的数字。两处都补上与既有习惯一致的 `status.notin_([PROC_COMPLETED, PROC_CANCELLED])`。 **逐个核过、确认无需改动的读者**(记下来省掉下一次重查):`leaver_blocked/dashboard_service` 与 `health/service` 本来就用同一个 `notin_`(且注释写明「和看板同一个定义,总数才对得上」);`provisioning/service` 的写路径用 `proc.status == PROC_BLOCKED` 守着;`hr_lifecycle/digest_service` 收窄到三个开放状态;`intelligence/providers/lifecycle` 排除了 cancelled 且按 `leaver_date` 开窗。另外 `dashboard/router.py` 的 `_employee_section` 会在流程终态时照样吐 `offboarding_info`(含 `pending_blockers`),但**全前端没有任何消费者** —— 是死负载,不是用户可见缺陷,**因此没有按缺陷去"修"**。 **验证**:新增 `test_terminal_process_blockers_2026_09_05.py` 3 条(取消单的 blocker 不进收件箱 / 活流程的仍然进 —— 防止用「全都不显示」蒙混过关 / 首页角标只数活的)。**变异验证 3/3 转红**:去掉收件箱的终态过滤、把过滤反向(改成只显示终态,活的消失)、去掉角标的终态过滤。`tests/test_mobile` + `tests/test_offboarding` **582 passed**。 > **2026-09-05(同日第七轮)— feat(role-change): 转岗复核 PR3 —— 差异引擎:「这次转岗改变了什么」终于有答案,以及答不上来时的诚实沉默(迁移 **611** / 0 新端点 / 0 MCP)** PR1 停了推送、PR2 把页面做成能看的。这一轮补的是这件事**从一开始就缺的那个计算**。 **问题不是算错了,是根本没算。** 复核包裹一直数的是这个人的**存量**,而把那个数字当成转岗的后果写进卡片(「63 项待你确认」)。唯一算过真差异的 `preview_role_change` 对着空策略表得出 *expected = ∅*,结论是「对每个人回收全部」,而且返回值[从没被接住](../server/app/core/coordinators/role_change_coordinator.py)。 新增 [`mover_delta.py`](../server/app/hr_lifecycle/mover_delta.py):**三个信号,刻意不平等**。 | 信号 | 说的是什么 | 能不能解锁推送 | |---|---|---| | `policy` | 转入岗位配置好的开通策略里有没有这一项 | ✅ 唯一默认能解锁的 —— 它是一句**意图声明**,不是观察 | | `provenance` | 这一项是不是在他刚离开的那个部门时开的 | ✅ 不是「他该有什么」的意见,是「他为什么会有」的事实 | | `peer` | 新部门里多少同事也有 | ❌ 只排序不指控 | 🔴 **让 policy 安全的那条规则:一条策略只能就它「本来就可能被写到」的持有物说话。** `policy_universe` 是任何一条生效策略提到过的全部 target;不在这个集合里的持有物**得不到任何 policy 判定**。没有这条规则,一个策略只提到 3 个坐席的部门,会让转岗者携带的另外 37 样东西全部变成「不在新岗位策略里」—— **存量数字换了身衣服又回来了**。有了它,空策略表 ⇒ 空 universe ⇒ 零判定 ⇒ 推不出去,这正是今天生产的状态,而且是**由构造保证**的,不是靠记得关开关。 **部门历史是重建出来的,而且在前端是开口的。** `identity_org_memberships` 没有有效期区间(只有当前态),所以「某天他在哪个部门」只能从 `role_change` 事件账本反推。账本从协调器上线才有,所以**比账本更早的授予一律 `unknown`,绝不归给最早那个部门** —— 给一条两年前的授权盖一个自信的错部门,比说「不知道」危险得多。 **七种 `delta_kind`,其中只有两种计数。** 其余五种存在的理由是:页面必须能区分「**查过了,没问题**」和「**没有信号能说话**」。这两句话对着一份权限清单说出来,分量完全不同 —— 而把后者显示成前者,正是 9/5 那张卡的成因。所以 `coverage`(每个信号覆盖了包裹的多大比例)也一起存下来:delta=0 且 coverage=0 和 delta=0 且 coverage=0.8 是两个结论,[`DeltaHeadline`](../web/src/components/roleChange/DeltaHeadline.tsx) 把它们渲染成**三种明显不同的状态**(「让 N 项需要重新判断」/「查过了,没有」/「算不出改变了什么」),外加第四种「还没算过」。 **界面**:包裹页顶部一句话说清楚 N vs 总量,一个「只看这 N 项」的开关(同时过滤类别表和条目表 —— dev 实测第一版只过滤了条目表,而复核人在钻进类别之前看的是类别表,于是按钮**看起来什么都没做**);每条持有物一个判定标签 + tooltip 里的理由(命中哪条策略 / 授予时他在哪个部门 / 新同事里多少人也有);IT 控制台的复核进度列里,`本次 N 项` / `本次无变化` / `算不出差异` 与存量进度条并排 —— **两个数字并排是这个区别唯一能落地的方式**。 **顺带**:6 个访问类 loader 补上 `policy_target` / `granted_at` / `peer_key` 三个 detail 键,只在源表**真的有**的地方填;填不了就不填,引擎报 `unknown` 而不是猜。 **验证**:新增 [`test_mover_delta_2026_09_05.py`](../server/tests/test_hr_lifecycle/test_mover_delta_2026_09_05.py)(14 条),重心全在**拒绝回答**上:空策略表零判定(而不是「什么都不该有 ⇒ 什么都是多余的」)、策略说不了的持有物不给判定、比账本更早的授予是 `unknown` 而不是「没问题」、peer 再悬殊也不计数、同部门内换经理时 provenance 整个信号沉默。每条负向断言都配了正对照。**三次变异验证**:去掉 universe 守卫 → 3 条红;让 peer 计数 → 1 条红;把史前授予归给最早部门 → 2 条红。前端 [`DeltaHeadline.test.tsx`](../web/src/components/roleChange/DeltaHeadline.test.tsx)(4 条)钉住三态,变异(把 `coverage > 0` 改成 `true`,即把「答不上来」显示成「没问题」)→ 红。后端 324 条 / 前端全量 / lint 13 道闸 / build 全绿。dev 实测:同一份包裹从「16 项待判断」变成「**这次转岗让 1 项需要重新判断(名下共 16 项)**」,过滤后 4 个类别收敛到 1 个,云授权逐条显示「判断不了」。 > **2026-09-05(同日第九轮)— fix(me): 「IT 正在为你准备剩下的 N 项,很快就好」—— 说给一个入职单三周前就关闭了的人听,而且会一直说下去(迁移 0 / 0 新端点 / 0 cron / 0 MCP)** 第三轮复审。**这一轮推翻的是我自己上一轮写进 PLATFORM.md 的一句话。** 第八轮修「已完成入职单的 blocker 行是冻住的」时,我在代码注释和 PLATFORM.md 里都断言了一句:「这些行没有别的消费者」。这一轮按「谁 import 了 `OnboardingBlocker`」逐个模块核对,**这句话是错的** —— `/me/welcome` 就是另一个消费者,而且是**面向员工本人**的那一个。 `me_universe/welcome.py::_onboarding_snapshot` 取的是这个人**最近的一条入职单,不看状态**,然后把它的 pending blocker 数报给前端;`WelcomePage` 在 `pending_blocker_count > 0` 时渲染 **「IT 正在为你准备剩下的 {{count}} 项,很快就好」**。而一个 `completed` 流程的 blocker 行永远不会再被任何东西写。于是: * 生产里 20 个「已完成但没有电脑」的人(正是第八轮那个队列刻意包含已完成流程的原因),每一个都在自己的欢迎页上被告知 IT 马上就要做完某件**没有任何人在做**的事; * 而且这句话会在整个 90 天新人窗口里一直挂着 —— 就算他后来通过普通领用流程拿到了电脑,那条冻住的 blocker 也不会消失。 修:终态流程(`completed` / `cancelled`)一律报 0 项待处理。流程关闭之后,「还 pending」的东西是账面残留,不是有人在做的事。**面向经理的孪生面从来没有这个问题** —— `team_service` 在读 blocker 之前就先 `status.notin_(_TERMINAL_PROC)` 了。 **顺带把上一轮那句错话在代码注释和 PLATFORM.md 里都改掉**,并把「怎么验证的」写进去:逐个列出所有引用 `OnboardingBlocker` 的模块 —— `idle_computers` / `intelligence/providers/assets` / `hardware_prep` / `digest_service` / `team_service` 全都约束在 `PROC_OPEN_STATUSES`,Day-1 指标读的是 `hard_ready_at` 而不是活的 blocker。**以后新增读者必须自己约束到开放流程,否则就会读到冻住的行。** **验证**:新增 [`test_welcome_terminal_process_2026_09_05.py`](../../server/tests/test_me_universe/test_welcome_terminal_process_2026_09_05.py)(3 条:completed 报 0 / cancelled 报 0 / **开放流程照常报出来** —— 最后这条是正对照,没有它,「把所有情况都归零」也能让前两条全绿)。变异验证:把终态判断改成 `if False` → 2 红 1 绿(正对照仍绿,正是它该有的行为)。`ruff` / `mypy ratchet` 全绿。 > **2026-09-05(同日第六轮)— feat(role-change): 转岗复核 PR2 —— 那两列裸 JSON 换成读得懂的变动,并且页面自己说清楚推送为什么是关的(0 迁移 / 0 新端点 / 0 MCP)** PR1 把推送停了、把死链修了。这一轮修的是**这一页本身没法用**。 **① 最宽的两列是 `JSON.stringify`。** `变更前` / `变更后` 直接把 detail blob 打印出来:`{"dept_code":"2730378","job_title":"Head of Business Operations","manager_person_id":"2cac6612-412d-452a-8d96-66ecc3201935"}`。一个部门**代码**加一个**裸 UUID**,占满整行,而操作者想知道的「谁从哪调到哪」一个字都没有。9/5 那 8 张卡的两侧部门完全相同、**只有 manager 那一根轴变了** —— 那根轴就藏在这个 blob 里。 现在 `build_role_change_list` 把变动解析成三根**具名轴**(部门 / 汇报给 / 职级),每根带一个 `changed`,前端只渲染真的动了的那些 —— 把三对没变的原样重印,和原来那堵 JSON 是同一件事,只是更好看。🔴 **`changed` 在服务端按原始值算,不是按标签算**:组织改名之后两个不同的 dept_code 可以渲染成同一个字符串,前端拿自己渲染的东西去比,会把唯一动了的那根轴判成「没变」并藏起来。有一条测试专门造这个形状(两个 code、同一个 path)。部门 code → 路径优先用**包裹里存的那一份**(它记的是当时的路径),而不是今天的组织树 —— 几个月后打开的人要的是「他当时从哪来」,而那个节点今天可能已经改名或不存在。 **② 这一页此前完全不提「为什么什么都没发」。** 新增 `RoleChangeBaselineBanner`:读 `review-config`,把开关状态**和**基线覆盖率放在同一句话里。生产实测现值:**0 条生效策略 / 88 个有人的部门**。「推送是关的」单独看像是谁忘了打开,而它触发的动作就是去打开它;第二个数字才让正确的动作可见 —— 去配置策略(横幅上直接是链接)。三种状态三件事:没基线(闸关着且关得对,主行动是去配策略)/ 有基线但没开(现在打开是个真选择,给开关)/ 已打开(说清楚会发什么)。**没基线时开关是禁用的**:服务端其实会接受(包裹永远不达标、发不出去),但那会让操作者以为接下来会发生什么 —— 拒在前端并把原因写在旁边,而不是静默接受。 **③ 补齐了三列此前根本没有的信息。** 复核人是谁(没有在职新经理时明说「无复核人」而不是留空 —— 一个指向动不了手的人的字段比空的更糟)、复核进度(`decided / reviewable`)、以及 🔴 **通知状态的三态**:`已通知` / `已拦下` / `待通知`。中间那个是这一列存在的理由 —— 一份被**刻意拦下**的包裹和一份**只是还没轮到**的包裹长得一模一样,而 9/5 之后这正是操作者需要分辨的那件事。`已拦下` 的 tooltip 带原因和时间,并说明重新启用不会补发。 **④ 页面标题不再只说云。** 「转岗与云资源复审」→「转岗权限复核」:包裹从迁移 568 起就覆盖 24 类持有物,云授权只是其中一类,而一个只点名一类的标题会教会操作者只期待一类。抽屉标题同改(三语)。 **⑤ 按变动类型筛选**(全部 / 跨部门 / 换汇报线 / 职级变动)。刻意做在**前端**:列表是 keyset 分页的,每个服务端筛选都进了 cursor 指纹,加一个就会让正在进行的翻页失效;一页最多 100 行,而这是「只看跨部门的」这种一瞥而不是搜索。**并且把这件事写在界面上** —— 筛选生效时旁边显示「本页 N 条中 M 条匹配(只筛当前页)」,否则底下分页器仍然报服务端总数,「3 行」配「共 37 条」读起来像 bug 而不像筛选。 **顺带**:`_serialize_row` 仍然返回原始 `before` / `after`(MCP 与取证时间线读它们),前端不再用。列表 SQL 多了一个对 `hr_role_change_reviews` 的 LEFT JOIN(自然键 `(person_id, effective_date)` 是唯一索引,不可能放大行数,所以**只加在分页查询上、不加在 COUNT 查询上** —— COUNT 的结果必须可证明地与从前一致)。 **验证**:后端新增 [`test_role_change_list_move_2026_09_05.py`](../server/tests/test_hr_lifecycle/test_role_change_list_move_2026_09_05.py)(7 条):manager-only 移动解析出人名而不是 UUID、dept code 解析成路径、**两个 code 同一个标签仍然算变了**、包裹存的路径压过今天的组织树、通知三态、职级变动不建包裹,以及一条**用 `before_cursor_execute` 计数**的查询数上限 —— 「标签解析不能随行数增长」这个性质靠读代码是看不住的,把解析改成逐行后这条测试从 8 条上限跳到 **29 条**,变异验证过。前端 `RoleChangesAdminPage.test.tsx` 从 3 条扩到 **11 条**(轴渲染 / 缺 move blob 不白屏 / 三种通知态 / 无包裹 / 横幅三态 / 没基线时开关禁用),并按仓库规矩给它套上 `WithoutAntdStyleInjection` —— 顺带把这个文件从 12.56s 压到 3.41s。全量 `pnpm lint`(13 道闸)/ `typecheck` / vitest / `build` 全绿。 > **2026-09-05(同日第八轮)— fix(onboarding): 「一键补登记」对最该用它的那批人根本没生效 —— 已完成的入职单里,阻塞项是冻住的(迁移 0 / 0 新端点 / 0 cron / 0 MCP)** 第七轮修完之后的第二轮复审,读的是上一轮没有逐行看过的文件。**在 IT 硬件待核实队列里找到两个缺陷,都源于同一个此前没有被写下来的事实:一个 `completed` 的入职单,它的 blocker 行是永远冻住的。** `reconcile_blockers` 对终态流程立刻返回 0,而每 5 分钟的 reconcile cron 只选开放流程 —— 没有任何东西会再写那些行。 🔴 **① `register_device` 的「一键关闭」对已完成流程是空转。** 这个队列**刻意包含 `completed` 流程**(cockpit 只看开放流程,所以「已完成但没有电脑」的人从所有看板上掉了下去 —— 生产 20 个,这正是这个页面存在的理由)。但它关闭 blocker 的方式是调 `reconcile_blockers`,而对终态流程那一调用立刻返回 0。于是:IT 点「登记设备」→ 资产行建了、领用做了、台账修好了 → **行还留在队列里,而且再点一次会 409 `HIRE_ALREADY_HAS_DEVICE`。** 修:终态流程由这个服务自己把 blocker 置成 `RESO_PROVISIONED`(扫描器本来会写的同一个值、同一个字段)。注释里原本写着「不手动改 blocker 行,扫描器是维度状态的唯一写者」—— 对终态流程来说扫描器已经退场了,这里不是第二个写者,是**剩下的唯一一个**。 🔴 **② 队列把「已经有电脑的人」显示成红色的「无设备」。** 同样因为 blocker 冻住:一个人在入职单关闭**之后**通过普通领用流程拿到了电脑,那条 pending 的硬件 blocker 永远不会更新。这一行于是出现在队列里,前端按 `hardware_state !== 'reserved'` 一律渲染成红色 `无设备` —— **在一个专门用来说「谁没有电脑」的页面上,对一个明明有电脑的人说他没有**;而且这一行上的每个动作都会 409。修:`list_gaps` 丢掉 `hardware_state === 'assigned'` 的行,并把数量报成 `summary.already_holds_device`,在 KPI 行下面用一行次要文字说明(**刻意不做成第五张 KPI 卡** —— 它们不是待办,给同等视觉权重就是在暗示它们是)。这些行没有别的消费者(Day-1 指标读 `hard_ready_at`,`_count_pending_blockers` 只对开放流程跑),所以在这里过滤就把影响关干净了。 **验证**:两条缺陷各有回归测试并变异验证 —— `test_register_device_closes_a_COMPLETED_process_gap`(把终态分支改成 `if False` → 红,`assert 'pending' != 'pending'`)、`test_gap_queue_drops_a_hire_who_already_holds_a_computer`(把过滤条件改成 `if False` → 红)。`tests/test_asset` + `test_onboarding` + `test_scheduled_jobs` + `test_mcp_tools_surface` 全绿;`ruff` / `mypy ratchet`(1270 = baseline)/ `web` 完整 `pnpm lint`(13 guard)/ `pnpm typecheck` 全绿。新增 3 语言 i18n key 一次配齐。 > **2026-09-05(同日第七轮)— fix(asset): T+0 自动领用在最常走的那条路上根本没跑;顺带把台账健康度的三张卡片拉回同一个作用域,并给三个导出补上审计(迁移 0 / 0 新端点 / 0 cron / 0 MCP)** 同日 5 个 PR 全部合入后的整体复审。**在自己刚发的功能里找到 3 个真缺陷,其中 2 个是高危,而且最狠的那个让本系列的招牌功能对最该受益的那批新人完全失效。** 🔴 **① T+0 自动领用在「准备得最好的新人」身上从来没有触发过。** `autoclaim_reserved_for_hire` 挂在三个入口:T+0 advance cron、`advance_now`、`mark_live_manual`。**但 `_recompute_status` 里还有第四个 `→ live` 的转移**(`hire_passed` 且零 pending blocker 时直接晋升),它没有调用领用;而 T+0 advance cron 对**已经是 live** 的流程会 `continue` 跳过。于是:一个在入职日之前就把所有维度都清干净的新人(= 准备得最好的那一批,也正是这个功能为之而建的那一批),会被**每 5 分钟一次的 reconcile 抢先**晋升成 live,advance cron 再也不看他,预留因此**永远不会转成领用**;等 T+7 verify 把流程置为 completed,同日第五轮新加的 `asset.stale_reservation_sweep` 就会在当晚 04:10 把这条预留**释放掉** —— 一台已经在新人手里的笔记本被放回库存,并且新人与设备之间唯一的台账链接消失。修:在这条晋升分支里也调用领用(与另外三处同一函数、同一凭证路径)。函数上方的 docstring 原本还写着「这个转移由 T+0 cron 完成,不是扫描器」—— **正是这句错话让领用没挂上来**,一并改正。 🔴 **② 「继承离职同事的设备」这条预留流程永远无法自动领用。** `HardwarePrepService.reserve` 的 `RESERVABLE_STATUSES` **刻意包含 `held_by_leaver`**(给要走的同事的机器预留给要来的新人,候选清单里就有这一类)。但领用在锁下的重新断言把库存状态**写成了字面量** `("idle", "available", "held_by_office")`,漏掉了这一个;而且 `held_by_leaver` 的设备 `assigned_to` 指向那位离职同事,又撞上 `assigned_to is not None` 这条拒绝。两道门叠加,这类预留**必然**返回 `None`:台账继续说设备在离职同事手上,它继续在「离职未归还」页面上计天数,当晚的僵尸清理最后把预留释放掉。修:直接用 `RESERVABLE_STATUSES` 本身(一处定义,不再手抄),并把「有持有人就拒绝」收窄成「**除 `held_by_leaver` 外**有持有人就拒绝」—— 在那个状态下有持有人恰恰**就是**回收本身。凭证同时记下 `from_user_id`(离职同事)和 `to_user_id`(新人),`detail.inherited_from_leaver=true`:一条只写目的地的记录会把「这台是从谁那儿回来的」丢掉。**并补了反向测试**:非 `held_by_leaver` 状态下有持有人仍然必须拒绝(别人抢先领用的竞态),免得这个例外扩散成通例。 🔴 **③ 台账健康度自检页混作用域 —— 第五轮只修对了四分之一。** 上一轮发现 Day-1 卡片是平台级、其余三张是区域级,处理办法是对区域管理员**不展示 Day-1 那张**。但复查发现:剩下三张里**只有「长期闲置」真的按区域作用域**(它复用闲置服务),「财务完整度」和「从未盘点」两张一直在数**全平台**,而页面顶上还挂着「仅本人管理的位置」的标签 —— 一个上海管理员把全公司的金额缺口当成自己的待办队列,而且页面亲口向他保证这是他的辖区。修:两张卡片走与闲置卡片同一条区域规则(`get_location_ids_managed_by` + `resolve_asset_location_ids_bulk`,位置解析不出来的资产不属于任何区域)。**`None`(全局层,不过滤)和空集合(区域管理员但一个位置都不管)必须分开** —— 混成一个就是把全平台数字发给一个毫无作用域的人,这条单独有一个测试。 **④ 三个数据导出没有任何审计行。** 资产域自己的 `/assets/export.xlsx` 从上线起就写审计,理由白纸黑字写在代码注释里(资产行带着员工姓名和使用地点)。本系列新增的三个 workbook 一个都没写 —— 其中「离职未归还」那份带着**离职员工的姓名 + 工号 + 他还持有的设备序列号**,是这个 router 里最私密的一份导出,而一次全量下载在事后完全不可见。三处补上 `audit_export`(它会立即 commit:`get_db` 要等下载流完才提交,客户端中途断开会把审计行一起回滚掉)。**写这条测试当场就抓到一个必然 500**:闲置导出把 `_filters()` 返回的 dataclass 直接传给了只接受 Mapping 的 `audit_export`(`AttributeError: 'IdleComputerFilters' object has no attribute 'items'`)。 **其余四处**:对账 apply 在**一行都没写**(全部 stale)时仍然盖 `applied_at`/`applied_by`,让运行列表把它显示成一次完成的对账 —— 改成只有真写了才盖章;`create_run` 建序列号索引时把**整张资产表** ORM 化再在 Python 里过滤,改成 SQL 预过滤(`lower(trim(serial))`,与 `mdm_serial_key` 逐字等价 —— 注释写明两边必须同步改);`MAX_ITEMS_PER_RUN=20000` 是**不可达**的死常量(共享上传阅读器先在 2 000 行处拦截),报错文案因此报了一个用户永远碰不到的上限,改成直接引用 `MAX_BULK_ROWS` 并把「拆成多个 run,结果可累加」写进文案;`ReconcileApplyBody.item_ids` 补上 2 000 上限(与它的 `skip` 兄弟一致)。 **「离职未归还」的金额列现在走 `PurchaseCostValue`**,和详情页 / 详情弹窗 / 财务区一致 —— 三个面标注估算值、第四个面裸显数字,读者学到的是「所有数字都可以信」。这份 workbook 还是核销时要拿去和离职员工对话的依据,「估的」和「发票价」必须看得出区别;导出也加了「金额来源」列。 **验证**:5 个缺陷全部有回归测试,**逐条变异验证**(把修复删掉即红、恢复即绿,原地改代码不用 stash):`test_recompute_promotion_to_live_also_claims_the_earmark`(删掉 reconcile 分支里的领用 → 红)、`test_t0_claim_converts_an_inherited_leaver_device` + `test_autoclaim_still_refuses_a_live_holder_on_stock_status`(恢复字面量状态集 → 红)、`test_financial_section_is_region_scoped` / `test_never_inventoried_section_is_region_scoped` / `test_admin_with_no_locations_sees_an_empty_estate`(让 `_scoped` 忽略过滤 → 全红)、`test_apply_that_writes_nothing_is_not_stamped_as_applied`(无条件盖章 → 红)、`test_every_data_export_writes_an_audit_row`(删掉任一处 `audit_export` → 红)、`test_serial_index_prefilter_matches_the_python_normaliser`(大小写 + 空格的序列号仍然匹配)。`tests/test_asset` + `test_onboarding` + `test_scheduled_jobs` 合计 **1435 绿**;`ruff` / `mypy ratchet`(1279 = baseline)/ `web` 完整 `pnpm lint`(13 guard 全过)/ `pnpm typecheck` 全绿。 > **2026-09-05(同日第五轮)— fix(role-change): 转岗复核 PR1 —— 停掉两条推送、给被打扰的人一个真正打得开的页面、把「没有基线就不要推送」写成不变量(迁移 **610** / +2 端点 / 0 新 cron / 0 MCP)** 用户看到 `/admin/role-changes` 这一页后问了三个问题:这是什么逻辑、开关在哪、**是不是只要岗位有变化就推送,不管权限有没有变化**。查了生产,第三个问题的答案比预期更糟。 **生产实测(TiDB,542 在职)。** `provision_policies` = **0 行**。这是平台唯一的「某个部门 / 岗位应该有什么」基线,所以 `ProvisioningService.preview_role_change` 算出来的 `expected` 恒为空集 —— 它对每个人的结论都是「把你现有的权限全部回收」。而且它的返回值在 [`role_change_coordinator.py`](../server/app/core/coordinators/role_change_coordinator.py) 第 358 行**根本没人接**(那 188 行里没有一次 `db.add` / `flush` / `update`,是个纯读函数,调用方不赋值、不落库、不进队列)。注释写的是「so the diff lands on the admin's desk」,实际上它没落到任何人的桌上。于是复核包裹报的是这个人的**存量**(24 类持有物),不是这次转岗造成的**增量**。 **后果是真的发出去了。** 9/5 09:30 共 9 张卡,全部 `delivered`(飞书 + 邮件):CTO 5 张(63 / 15 / 13 / 13 / 11 项)、另一位负责人 3 张(28 / 16 / 14)、CEO 1 张(28)。这 8 张 `manager_change` 的 `before_dept_code` 与 `after_dept_code` **完全相同** —— 部门没动、岗位没动,只是 9/4 那次 HRIS 同步里一批人的汇报线跟着一次组织调整变了。223 个 item,`decision` **全是 NULL**,上线以来 0 次决断。另有 35 条 grant 在 9/4 被翻成 `pending_review`,满 30 天(10/4)会让 `scope_review_sweep` 一次产生约 175 张卡。 🔴 **而且被打扰的人恰恰是打不开的人。** 卡片 CTA 是 `url=/admin/role-changes?review=`(已投递,改不了),而这条路由挂在 `RoleRoute roles={['global_admin','security_auditor','auditor']}` 下面。4 个收件人里 3 位只有 `employee` 角色,点击被 `RoleRoute` 静默弹回自己首页;只有 CEO 因为多一个 `management` 角色、被 `RoleRoute` 的 admin-tier fold-in 放了进去。后端 [`mover_review_router`](../server/app/hr_lifecycle/mover_review_router.py) **一直**按 `reviewer_person_id` 逐包裹给普通员工放行(读、逐条决断、按类别批量决断三个端点都是),前端从来没有对应地址 —— `MoverReviewPanel` 只在那个 admin 页里被引用过。 **这一轮做四件事,一条新推送都不发。** **① 已投递的死链复活。** `/admin/role-changes` 从 `RoleRoute` 里挪出来,换成 [`RoleChangeEntry`](../web/src/pages/admin/RoleChangeEntry.tsx):console 角色渲染原页面(体验逐字节不变),其他人带 `?review=` 跳 `/me/role-change-review/:id`,不带就回个人待办。**这是导流不是鉴权** —— 真正的边界始终是 API(console 的端点是 `require_admin_read`,非 reviewer 要包裹得到 404),而且非管理员在 console 挂载**之前**就被重定向走,不会代他发出任何 admin 请求。新增员工页 [`MyRoleChangeReviewPage`](../web/src/pages/me/MyRoleChangeReviewPage.tsx) 先回答「你为什么会看到这个」再谈清单:谁、哪天、部门 A→B、**汇报线 X→Y**(这根轴从第一天就存进了 `before_manager_person_id` / `after_manager_person_id`,API 从没返回过 —— 而它正是那 8 张卡的全部解释),然后三句话说清楚「Helix 不会替你动任何权限 / 没有截止时间也不会自动回收 / 可以按类别整批处理」。移动端同样补齐([`MRoleChangeReviewPage`](../web/src/mobile/pages/MRoleChangeReviewPage.tsx),类别级决断;逐条拆分去桌面),`mobileDeepLink` 加映射 —— 触发媒介是飞书卡片,而飞书卡片是在手机上打开的。`contracts/mobile-deep-links.json` 把 `?review=:id` 从 `desktopOnly` 移到 `mapped`:原来的理由写的是「RBAC 授权层,手机上做不了」,那个前提本身就是错的。`/my/todos` 加第 13 个 tab(`mine=true`,一个也是管理员的经理只看自己欠的那几份),侧栏 `生命周期管理` 补上入口 —— 这一页此前**在菜单里根本不存在**,只能靠输 URL 或点卡片进来。 **② 停两条推送,并且固化。** `role_change.review_notify` / `role_change.scope_review_sweep` 的 `enabled` 置 0(先手工改了生产,再由迁移 610 固化 —— 否则新环境 seed 出来又是开的)。另外两条(`dispatch_reconcile` 03:20 / `review_backfill` 03:40)保留:它们只写数据、一条通知都不发。 **③ 给积压盖「withheld」戳。** 新增 `notify_suppressed_at` / `notify_suppressed_reason`,把现存所有 `notified_at IS NULL` 的包裹标成 withheld,notify 的 WHERE 加上这一条。**不复用 `notified_at`** —— 那个字段的语义是「真的发过」,污染它以后就分不清「通知过」和「被拦下」,而事故之后唯一值得问的就是这两者中的哪一个。没有这一步,任何一次重新启用都会在当天把整个积压一次性轰出去。 **④ 「没有基线,就不要推送」成为不变量,不是口头约定。** 新增 [`mover_review_settings.py`](../server/app/hr_lifecycle/mover_review_settings.py) + `platform_settings['role_change.review']`:`employee_push_enabled` 默认 **False**,`require_baseline_for_push` 默认 **True**,`push_baseline_sources` = `['policy','provenance']`(**peer 同侪分布刻意不在里面** —— 一个人人都超配的部门,和一个人人都配得刚好的部门,在统计上长得一模一样)。两个 handler **在发送时重读**这个配置,所以把 `scheduled_jobs.enabled` 打开**本身不足以**触达任何人。同时把 `baseline_source` / `delta_items` 两列**放在这一轮**而不是等差异引擎那一轮:发送路径问的是 `settings.may_push(baseline_source, delta_items)`,既有行全是 `('none', 0)`,于是差异引擎落地之前**任何包裹都推不出去** —— 把这个不变量推迟两个 PR,中间就存在一个「翻一个 bool 就能重演 9/5」的窗口。`validate()` 直接**拒绝** `employee_push_enabled=True` + `require_baseline_for_push=False` 这一组合(那正是产生这 9 张卡的配置),理由写在错误消息里。新增 `GET/PUT /api/v1/role-changes/review-config`,一次返回策略**和基线覆盖率**(policy 行数 / 覆盖的部门数 / 有人的部门数 / 配置入口链接)—— 「推送是关的」单独看像是谁忘了打开,操作者需要第二个数字才知道要改什么。 **顺手记下一个还没修的**:`role_change_review_30d` 卡的 `url` 是 `/admin/role-changes`,而它的收件人包含云 scope owner —— scope owner 未必是管理员,而 `PUT /role-changes/grants/{id}/review` 是 `require_admin`,也就是说那张卡对他们**根本不可操作**。这属于 `scope_review_sweep` 收窄收件人时一起修的事,不在这一轮用一个猜出来的移动端目标盖过去(理由写进了 contract 的 `reason` 字段)。 **验证**:新增 [`test_mover_review_push_gate_2026_09_05.py`](../server/tests/test_hr_lifecycle/test_mover_review_push_gate_2026_09_05.py)(26 条),重点是**每个「什么都没发」的断言都配了正对照** —— 否则一个坏掉的 handler 也能让它们全绿:「打开 cron 行不够」配「打开开关 + 有真 delta 就真的发了」;「被盖戳的不发」配「同一批里没盖戳的发了」;「peer 不解锁」配「policy 解锁」;窗口设置是否真的进了 SQL,靠 30 天 / 60 天两次跑出不同的 `scanned` 来证明,而不是读代码。前端 `pnpm lint`(13 道闸)/ `typecheck` / vitest 1396 条 / `build` 全绿。 > **2026-09-05(同日第五轮)— feat(asset): 离职未归还设备终于有时钟和责任人;备机预留僵尸不再等人打开某个 tab 才被发现(迁移 **608** / 2 端点 / **+1 cron** / +1 MCP → hint **616**)** > **2026-09-05(同日第五轮)— feat(access-lifecycle): 访问对象闭环 PR3 —— 离职 T+1 安全网从「自己记得的那一半」改成注册表驱动;账号终态保障从 2 个系统推广到每一个身份同步目标(迁移 **609** / +0 端点 / +1 cron / +0 MCP(hint 仍 **616**,刻意)/ +0 通知模板 / 0 新角色)** 审计里这一块的原话是「离职 T+1 安全网只网住了它自己记得的那一半」。数出来是这样:`RES_*` 注册表里有 **29** 种资源类型,`hr.post_leaver_verify` 的 `_scan_person` 手写枚举了 **14** 种 —— VPN、AI 工具坐席、GitHub 组织成员、邮件组所有权、软件负责人 / IT 联系人、系统负责人、审批流负责人、身份消费方负责人、软件权限、DAX 授权……**一种都没扫**。更细的一条:它给四种网络资源起了自己的名字(`cloud_domain` / `cloud_dns_record` / `cloud_cdn_domain` / `cloud_load_balancer`),而离职扫描器、转岗复核包、前端标签用的是 `domain` / `dns_record` / `cdn_domain` / `load_balancer` —— 同一条残留在两处是两个名字,合规事件的去重键因此也对不上。 **安全网现在按注册表驱动。** 新模块 [`hr_lifecycle/leaver_residuals.py`](../server/app/hr_lifecycle/leaver_residuals.py):残留 = 注册表里每一种类型 × 一个谓词,谓词**默认就是转岗复核包的那一个**(`mover_holdings._LOADERS`)—— 两边问的确实是同一个问题。`_scan_person` 从 300 行缩成一次调用(文件 529 → 230 行)。差异必须显式:`_T1_OVERRIDES` 里目前只有一条(离职者的 `pending` 坐席、以及 MDM 托管的坐席**都算**残留 —— 前者是真实的活坐席、占配额,后者转岗时不问是因为 enrolment 跟着设备走,而一条指着离职者的分配记录没有别的东西会注意到),`NOT_RESIDUAL` 里只有一条(`software_account`:Jira 全量撤权 blocker 是按**集成存在性**生成的,没有可检测的每人一行;这个系统的厂商真相由账号终态对账回答)。新的 `test_leaver_residual_registry_covers_every_type` 让「加了资源类型却忘了 T+1」直接构建失败 —— 那正是上面 15 种的成因。顺带统一了硬件谓词:`borrowed_by` 现在两边都算(转岗复核包此前会漏掉一台还在人手上的借用机)。 **三种此前离职流程完全看不见的持有。** `RES_OBJECT_STORAGE`(`cmdb_object_storage.owner_person_id`)与 `RES_CERTIFICATE`(`cmdb_certificates.owner_person_id`,**只算 `owner_is_manual`** —— 探测 / 云同步来的证书负责人是从域名链实时解析的,转它等于跟解析器打架)按 LB / CDN 的老路子走「负责人 FK 转交接人」;`RES_EMAIL_GROUP_MEMBER` 是**静态邮件组成员资格**,人绑权限,进 `IMMEDIATE_REVOKE_RESOURCE_TYPES`,T+0 第一个 tick 在 Google 侧 `members.delete`。**成员资格与所有权是两回事**:所有权(`RES_EMAIL_GROUP`)要转让,成员资格要移除,而且成员资格的移除**必须等所有权转让先落地**(Google 要求每个组 ≥1 owner,踢掉唯一 owner 会把组弄坏)—— 扫描器跳过本人拥有的组,`remove_person_from_group` 再兜一道 409。为什么现在补:一个离职者留在 `finance-team@` 里,在账号被停用期间是无害的;而**被保留的账号**(CBG 保留 / 共享服务分类,正是账号终态页盯着的那一批)或被复活的账号,会继续收到组里的每一封内部邮件。 **账号终态从 2 个系统变成 2 + N 个。** Google 和 Atlassian 各因为一次事故拿到了自己的对账面;其余每一个 Helix 会下发离职的身份系统只有一个读者 —— `identity_sync.leaver_assurance`,命中就 raise,IT 收一条失败通知,**页面上什么都没有**。新 cron `offboarding.account_assurance_rosters`(每日 04:10 UTC,排在 03:00 快照刷新与 03:47 只读对账之后)读同一批厂商名册快照,按人 × 目标写进 `offboarding_account_assurance`(system = `isync:`),并给每个目标记一条快照新鲜度心跳。判定沿用既有的四分法,两个最容易被合并的答案继续分开:**快照拍在离职之前 → `unknown`**(那时候人本来就在职,它作证不了撤销这件事 —— 2026-07-17 首跑 48 条里 36 条就是这个误报),**根本没有快照 → `unknown` 而不是 `absent`**(「没看过」不等于「账号没了」)。登记在案的保留分类照旧是 `exempt`,与写路径同一个谓词。页面上的「立即处理」按钮对这些系统复用 `IdentitySyncService.revoke_leavers_on_target`(新增 `person_id` 作用域参数,过滤的是**同一个** Signal-B 人群),不另写第二条回收路径 —— 操作员关掉的正是页面刚才给他看的那一条,绝不是一批。 **一个不做的决定:MCP 工具数保持 616(本 PR +0)。** 读面已经被 `list_leaver_account_assurance` 覆盖(它现在天然多返回每个目标的 `isync:`);唯一新的写动作是那个按人回收的按钮,而给它一个工具意味着一次 LLM 调用就能在厂商侧停掉一个人的账号 —— 那正是应该有人看着页面上的证据再点的动作。同 `answer_security_quiz` / `decide_knowledge_proposal` 的先例。 🔴 **两个既有安全闸被这次重构打红了,都是「闸在旧地址上扑了个空」,两个都修成跟着代码走而不是放宽。** `test_the_identity_system_vocabulary_cannot_drift_apart` 把账号终态的系统词表在四处的拼写钉在一起,靠正则从路由源码里抠 `pattern="^(google|atlassian)$"` 的 alternation —— 词表变成开集之后它再也匹配不上。改成**行为断言**:从路由**签名**(Pydantic v2 的 `metadata`,不是源码文本)读出 pattern,拿真值跑 —— `ASSURANCE_SYSTEMS` 每一个都要过、`isync:aws-ai` 要过、`max_length` 仍须等于列宽 32、`google%` / `GOOGLE` / `'; --` 要被拒;并补上 PR3 新造的那一对「同一件事的两处表示」:Python 与 TS 两侧的 `isync:` 前缀常量必须相等。同一个闸里第二处**已经被这次改动悄悄解除了武装**:`enforce` 默认值的检查是 `r'"([a-z,]+)",\s*\n\s*description='`,而本 PR 在字面量与 `description=` 之间插了一行 `max_length=512`,正则从此不匹配 —— **一个能被「插入一个无关 kwarg」解除的闸不算闸**,也改成读签名。`test_google_orphan_no_owner_person_id_references` 硬编码读两个文件断言 `GoogleOrphanAccount` 只能按 `owner_user_id` 查,而 T+1 的那份查询这次搬进了注册表,于是闸扑空;改成**跟着符号走**(扫 `app/` 下所有提到该模型的模块),并补一条「一个读者都没有了要报错」,免得将来删干净反而静默通过。 🔴 **变异验证发现:让一个漂移的真断言变绿的最短路径,是让它失去分辨力。** 全量跑里 `test_sweep_stamps_missing_clocks_with_a_30_day_floor`(PR2 的测试)红了 —— 断言 `owner_confirmation_due_at ≈ NOW + 182d`,而 `NOW` 是模块导入时的常量、服务账号绑定的 `granted_at` 走 DB 默认值;跑到这条时已过 32 分钟,漂 1911 秒超出 30 秒容差。**代码是对的**(确认周期从**授权**起算,不从补写那天起算),错的是测试假设了 `granted_at == NOW`。第一版修复把 `granted_at` 钉成 `NOW` —— 于是 `granted + 182d` 与 `now + 182d` 落在同一瞬间,**测试再也分辨不出两个候选锚点**。对 7 条承重断言逐条注真缺陷复核时,只有这一条 STILL GREEN。改成 `granted_at = NOW - 10d`(两锚点相差 10 天)并加断言「必须离 `NOW + 182d` 至少 9 天远」,7/7 全红。**规矩:变异验证不只对新写的测试做,更要对「刚修好的测试」做。** **迁移 609 只做两件数据层面的事**:把 open / accepted 的 `leaver_orphan` 事件里那四个私有别名改成注册表名字(否则同一条残留会以新名字再开一条,旧的永远挂着;resolved 是历史,不动),以及播种新 cron。无新表、无新列。 **验证**:新增 [`test_leaver_safety_net_registry_2026_09_05.py`](../server/tests/test_hr_lifecycle/test_leaver_safety_net_registry_2026_09_05.py)(12 条:注册表全覆盖闸 / 三种新类型在四张表都注册 / T+1 现在能看见 VPN 与软件负责人 / 用注册表名字且四个别名消失 / pending 坐席是残留但转岗不问 / 借用机两边都算 / 一个域失败被记下而不是报「干净」并进 run 摘要 / 桶与手动证书扫描+T+0 转让、探测证书不入列 / 成员资格扫描跳过自有与动态组并报告未镜像 / 仍是 owner 时拒绝移除 / 厂商拒绝时 blocker 保持 pending、成功后 revoked_auto)与 [`test_assurance_rosters_2026_09_05.py`](../server/tests/test_offboarding/test_assurance_rosters_2026_09_05.py)(10 条:四种厂商状态判定含两个「像但不是」/ 无快照是 unknown 不是 absent / 过期快照不指控 + 保留分类 exempt / 只扫可回收目标 / slug 放不下时跳过并报错不截断 / 行是替换不是累积 / 与 Google 并排出现在页面与 summary 且心跳在列 / 按人回收只动一个人 / 未知目标如实报告)。 > **2026-09-05(同日第五轮)— feat(asset): 离职未归还设备终于有时钟和责任人;备机预留僵尸不再等人打开某个 tab 才被发现(迁移 **609** / 2 端点 / **+1 cron** / +1 MCP → hint **616**)** 这一轮补的两个洞都由另一个会话的只读代码审计指出(2026-09-05),而其中第二个是**我自己这一系列造成的**。 **① `held_by_leaver` 有状态、有数据(生产 10 台),但没有时钟也没有责任人。** 周报是 `SELECT count(*)` + 5 条样例发给全体资产管理员:没有账龄分桶、没人负责、没有核销出口。一台跟着人走掉的设备要么回来要么被核销,而这两件事都不会因为邮件里的一个数字而发生。 🔴 **时钟取离职同事自己的 HRIS 离职日期,不是 IT 什么时候把资产标记成「离职持有」。** 「公司多久没有这台电脑了」才是该问的问题,「我们多久前才注意到」不是。`identity_persons.termination_date` 是权威字段;没有它才退回到标记时间,再没有才退回到资产行的 `updated_at` —— **每一行都报出自己用了哪个时钟**,因为建在兜底值上的分桶配不上和建在 HRIS 日期上的同等信心,页面上还有一条 Alert 说清有几台是兜底的。 账龄按 **30 / 60 / 90+** 分。不是装饰:出去两周是正常的离职流程延迟,出去 90 天要么是丢了要么是被默认核销了,把两者混成一个计数正是生产那 10 台一直没人查的原因。 **责任人按位置派生,不落库**:每行给出该追这台设备的办公室管理员;**位置解析不出来的行明确算进 `unassignable` 并在界面上写「无人负责」** —— 静默地谁都不怪是这个面最容易犯的错。 **② 备机预留僵尸没有清理,而且这个洞是我这一系列自己扩大的。** `stale_reservations`(「预留给某个新人、但那个新人已经没有在办入职单」)以前**只在有人打开「待备机」tab 时算一次**;`scheduled_jobs` 里没有任何 `asset.reservation*` 任务;`delete_asset` 对被预留的资产既不拒绝也不清理,软删会让预留静默消失。一个被撤销的 offer 因此把一台笔记本无限期扣在库外,唯一的发现路径是有人恰好访问某一个 tab。 🔴 **而 2026-09-05 之后预留还会满足 Day-1 硬件维度(本系列 PR-1)—— 一个僵尸预留现在同时意味着「设备对下一个新人不可用」和「被静默算成某个已撤销候选人的 Day-1 就绪」。** 所以清理和造成它的那个改动放在同一系列里,而不是留给下一轮。 * 新 cron `asset.stale_reservation_sweep`,每日 04:10(在 03:15 资产管理员对账之后、中国工作时间之前 —— 早上到岗看到的库存已经是真的),**迁移 608 seed 且默认启用**(这件事的全部意义就是不靠人记得去看); * 释放走与人工释放**同一条凭证路径**(`reserve_release` operation),带 `detail.via='stale_reservation_sweep'`;`operator_id` 按离职域自动化的既有约定取语义主体(被预留的那个新人,该列 NOT NULL 且 cron 没有操作人); * 🔴 **锁下重新断言要比对「同一个人」,不能只看「还有没有预留」。** 第一版只判 `reserved_for_person_id is not None`,而真正危险的那条竞态是:候选清单判定 X 对 P 是僵尸之后,X 被**重新预留给另一个有在办入职单的新人 Q** —— 只判非空就会把 Q 的合法预留释放掉,正是注释声称要防的那件事。**这条是靠变异验证抓出来的**:第一版回归测试在把人员判断删掉之后**仍然全绿**(它在 `sweep` 内部重算清单之前就改了行,于是清单直接为空,通过的理由是错的)。改成 patch 候选来源、把行按住在「判定为僵尸之后又被重新预留」那一刻,删掉判断即红(`assert 1 == 0`)、恢复即绿; * **`delete_asset` 现在对被预留的资产返回 409 并指出释放入口**。之前它能通过所有检查:被预留的设备处在**库存**状态,`assigned_to`/`borrowed_by` 都是空的。 🔴 **合并前的整体复审又抓到一处混作用域**:台账健康度自检页的四张卡片里,财务/闲置/从未盘点三张按位置作用域,而 **Day-1 硬件缺口那张不是**(缺口按办公室归人,不按资产位置划分,而且它的处理动作是 `require_admin`)。给一个区域 `asset_admin` 看,就是一个平台级数字挨着三个区域级数字,读者无从分辨。**改成只对全局层展示那一张**,并在卡片区加一个「仅本人管理的位置」标签说明这一视角 —— 与其在四张卡里的一张加脚注(必然被略过),不如不展示自己管不了也看不准的那一张。 **新 tab 落在资产清单 hub**(在册资产 / 长期闲置 / **离职未归还** / 回收站)—— 又一份处于问题状态的资产行清单,和长期闲置并列,不新增第十个侧栏项。 **没有给员工加任何推送。** 催办的收件人是 IT / 办公室管理员,和「不给员工加新推送」这条既有红线一致 —— 也和同日第一轮「11 条欠账走 IT 内部消化」的产品决定一致。 **验证**:新增 [`test_leaver_recovery_and_sweep_2026_09_05.py`](../../server/tests/test_asset/test_leaver_recovery_and_sweep_2026_09_05.py)(21 条:时钟优先 HRIS 离职日 / 退回标记时间且报出来 / 最后退回行更新时间 / **最新一次标记胜过第一次** / 分桶精确切在 30-60-90 / 分桶筛选后合计不变 / 责任人按位置派生 / **无位置算 unassignable** / 只列 held_by_leaver / 无持有人的行照样列出 / 区域管理员只看自己位置 / 无位置管理员看不到 / 排序最久在前 / 清理释放僵尸预留并落 via 标记 / **活着的预留不动** / dry-run 零写入 / 幂等 / 每次释放都有审计 / **delete 拒绝被预留资产** / delete 对普通空闲资产照常工作 / 空资产不报错 / **重新预留给别人的设备不被清理**)。`tests/test_asset` + `test_onboarding` + `test_scheduled_jobs` 合计 **1423 绿**;`ruff` / `mypy ratchet`(1279 = baseline)/ `web` 完整 `pnpm lint`(13 guard)/ `pnpm typecheck` 全绿。 **dev 实测**:607→608 往返(降级后 seed 行归零;号在未 push 期间被迫改了两次:606→607(访问对象闭环 PR2 占了 606)→608(安全宣贯机器翻译占了 607));种 4 台离职未归还(199/69/39 天 + 1 台无离职日期走标记时间兜底、1 台无位置)+ 1 个僵尸预留;接口返回的分桶、`clock_sources`(3 权威 + 1 兜底)、`unassignable=1` 全部正确,分桶筛选后 `total` 不变;**真跑 cron handler** 看到 `candidates=1 released=1` → 预留清空 + `reserve_release` 带 `via` 标记,第二次跑 `released=0`;`DELETE /assets/{id}` 对被预留资产返回 **409 `ASSET_RESERVED_FOR_HIRE`**;浏览器实测四个 tab、四个 KPI、离职人员带「已离职」样式与工号、兜底时钟在行内标「(按标记时间)」、无位置的行标「无人负责」、以及那条「其中 1 台起始日不是 HRIS 离职日期」的 Alert。**随后删净全部种子数据。** > **2026-09-05(同日第六轮)— fix(security-awareness): 英文界面右下角的中文气泡 —— 语言链路没坏,缺的是内容;30 条只有中文的素材用 AI 补齐英日文,并且**告诉读者是机器翻的**(迁移 **607** / 4 端点 / +1 cron / +0 MCP)** 员工反馈:**英文系统里,右下角安全学习气泡是中文的。** **排查结论:语言链路一路都对,不要改它。** 前端把 i18next 的当前语言传给 `/security-awareness/bubble`,`service.pick_block` 按 `catalog.LANG_FALLBACK`(en → zh → ja)解析并回报 `is_fallback_lang`。缺的是**内容** —— 生产 46 条已发布素材: | 形状 | 条数 | |---|---| | 漫画,只有 `zh` | **30** | | 文章,`zh + en`(无日文) | 16 | | 文章,三语齐全 | 11 | 回退链于是老老实实地回退到了中文,而气泡上**没有任何东西说明这是回退** —— 读者无从判断这是「只有中文版」还是「坏了」。这就是这条反馈的全部内容。 **AI 补齐([`security_awareness/translation.py`](../server/app/domains/security_awareness/translation.py))。** 用平台共享的 AI/LLM 连接器(`ai_spending.llm.api_key`,和 copilot / 花费摘要同一把钥匙,本域不要自己的凭据)把中文 block 译成缺的语言。**每种目标语言两次调用,刻意拆开**:标题 + 摘要走 `chat_json`(短、结构化,正是气泡和卡片渲染的两个字符串);正文走 `chat_text`(markdown 进、markdown 出)—— 让模型把 1 KB markdown 塞进 JSON 字符串正是 `BAILIAN_LLM_OUTPUT_TRUNCATED` 的标准配方,截断出来的东西长得像一份翻译。正文超过 6000 字(≈8k 输出 token,模型输出上限)直接报错让人手翻,而不是交回半篇;线上最长正文 1243 字,约 5 倍余量。 🔴 **不改中文原文、不改发布状态、不译图片。** 漫画的 `image_keys` / `cover_key` 原样复制 —— 那是同一批 JPEG,这里没有任何东西能重画它们。所以英文读者拿到的是**英文标题 + 中文画面**。这比中文标题 + 中文画面好,但**只有在告诉读者的前提下才诚实**:生成的语言记进新列 `secaw_materials.mt_langs`,库卡片 / 详情页 / 移动端 / 气泡四个读取面都带 `machine_translated`,详情页渲染成提示,而且**对漫画换一条文案**明说「图片本身仍是中文的」。 **`machine_translated` 和 `is_fallback_lang` 是两句不同的话**,不能合并:前者说「这就是你的语言,但机器写的」,后者说「这不是你的语言」。合起来会让英文卡片告诉英文读者它是中文的。两个 flag 互斥,UI 各有各的提示。 **标记为什么是一列而不是 block 里的一个键。** `MaterialWrite.normalized_localized()` 是白名单,塞进 JSON 的 `mt: true` 会被管理员下一次保存**静默丢掉** —— 包括只改 `kind` 的那种保存(它把三种语言整个过一遍同一个校验器)。那样标记会因为跟「有没有人校对」完全无关的原因消失。列上的 `mt_langs` 只被两件事清掉:某语言的 block **真的变了**(`service.update` 逐语言比对,所以改分类不会连坐清空别的语言的标记),或管理员显式点「标为已校对」—— 因为最常见的复审结果是「没问题」,不产生任何编辑,没有这条出口,标记会永远挂在恰恰翻得好的那些译文上。 **四个端点 + 一条 cron。** `GET translation-gaps`(不调模型,给控制台一个「12 条缺英文」的数字,顺带报有没有配 key);`POST materials/translate-missing`(一键补齐,服务端封顶 25 条);`POST materials/{id}/translate`(单条;`persist=false` 是编辑器的路径 —— 跑模型、回填表单、**不落库**,否则作者取消抽屉后译文还留在库里);`POST materials/{id}/translation-reviewed`。cron `security_awareness.translation_backfill` 每小时补 10 条(按天跑会让一条今天发布的中文素材在英文界面上挂一整天),**剩余条数写进 `outstanding`**;没配 key 而确实有缺口时**直接 raise** —— 返回一个体面的 skipped 会让 `runs.status='ok'`,连接器空着多久这个任务就健康多久。 **界面。** 素材库顶部一条按语言分列的缺口横幅 + 「一键补齐缺失语言」;语言 chip 上 AI 译的那几个标黄并带说明,行内多一个翻译按钮和逐语言「标为已校对」;编辑器每个非中文 tab 一个「AI 翻译」按钮(填表单,保存仍是作者的动作);气泡在标题旁多一个极小的角标 —— 回退时是语言名,机翻时是「AI 翻译」,原生 tooltip 说明原因。三语文案齐全。 **验证**:新增 [`test_translation.py`](../server/tests/test_security_awareness/test_translation.py)(14 条:补齐不动原文与状态、漫画图片沿用、幂等且不重复计费、正文走 text 不走 json、preview 不落库、读者看到 `machine_translated` 而 `is_fallback_lang` 为假、改一种语言只清它自己的标记、改分类不清任何标记、标为已校对幂等且不算内容变更、缺口只数读者会遇到的、批量报 `outstanding`、无 key 是带指引的 503、cron 有活没 key 必 raise、员工四个端点全 403)。变异验证:把逐语言比对换成无条件清空,`test_editing_one_language_clears_only_its_own_badge` 立刻转红。`tests/test_security_awareness` 全绿;`ruff` / `mypy` / `pnpm lint` / `pnpm typecheck` 全绿。 > **2026-09-05(同日第五轮)— fix(cmdb/cost): Azure 成本同步不是「偶发被限流」,是每个订阅每次都先撞一次 429 再等出来(0 迁移 / 0 端点 / 0 cron / 0 RBAC / 0 MCP)** 起点是一条 `cmdb.cost_facts_sync` 的 partial_failure:36 个订阅里 1 个失败,`status=429 body='{"error":{"code":"429","message":"Too many requests. Please retry."}}'`。看起来像一次抖动 —— 生产 `scheduled_job_runs` 里 60 天内**这是第一条 429**。 **但那条错误里没有任何证据能判断它是抖动还是常态,所以去翻了 worker 容器日志 —— 常态。** 2026-09-04 23:02 到 00:19 的月结重拉窗口里,83 行连续的 `Azure HTTP 429 list_cost_facts sub=… attempt=1/5 sleeping 26-58s`,**一个订阅一行**: ``` 23:02:41 429 sub=fc0a85ea attempt=1/5 sleeping 45s 23:03:48 429 sub=f0c99419 attempt=1/5 sleeping 38s 23:04:47 429 sub=7bc8ab17 attempt=1/5 sleeping 39s … ``` 即**每个订阅的第一次 Cost Management 查询都会被 429**,睡够服务端说的冷却时间之后第二次才成功。不是月结特有:当天 20:36 的日常 cron 窗口里同样有 12 条,全天 71 条。一个 36 scope 的 chunk 跑 12–25 分钟,其中约八成是限流睡眠。这个驱动**靠撞限流来发现限流**,每个 scope 撞一次,一直如此。 **两个具体缺陷,都在这一版修掉。** **① 没有 Retry-After 头的 429 会白烧重试次数。** Azure 并不总在 CM 的 429 上带 Retry-After。旧的兜底是 `min(2 ** attempt, 60)` 从 1s 起步,于是最终失败的那个订阅(`7f070020`,00:04:34)五次尝试睡的是 **56s → 2s → 57s → 8s**:那两次 2s / 8s 落在一个约 60s 的限流窗口里,**不可能**成功,等于把 5 次预算花掉 2 次在注定失败的请求上。现在头缺席时改用**这一轮里服务端最近说过的冷却值**(`_AzureThrottlePacer.suggested_backoff_s`,下限 20s —— 实测冷却值 26–58s),每一次尝试都花在有机会的请求上。 **② 根本问题:完全没有客户端节流。** `cost_service` 一轮里**复用同一个 driver 实例**跑全部 scope,但没有任何东西把「服务端刚说了等 45s」从订阅 N 带到订阅 N+1 —— 于是 N+1 立刻打向一个我们**已经知道是关着**的限流器,再收一个 429。这就是日志里每个订阅一条 429 的成因。新增 `_AzureThrottlePacer`(driver 实例级、三个 CM 调用点共用):429 时学下服务端冷却值,每次响应后给下一个请求上闸;**每一次「没重试就成功」把间隔减半**(AIMD)从下方逼近真实速率,这样一分钟的坏运气不会把剩下 35 个订阅全部钉在 45s/个上 —— 没有这个衰减,节流会比它替代的「每 scope 撞一次」更慢。 **③ 两条预算,都是为了不让「修限流」变成「把 cron 跑超时」。** 单次睡眠上限 90s 仍在,但旧代码**累计无上限**:4 × 90s + 查询会被 `cost_service` 的 300s 单 scope 超时中途取消,记成一条毫无信息量的 `status='timeout'`。现在单次调用累计睡眠上限 **200s**,超了就停,拿到的是诚实的「429,限流」。另一条是**整轮节流预算 600s**:节流理论上是零成本的(它替换掉的 429 往返本来就在睡同样长的时间,AIMD 又会收敛到真实速率),但「理论上」是对 Azure 限流器的一个模型,模型错了不能把一次 700s 的日常 cron 变成撞上 1800s 默认超时的失败 —— 超过 600s 节流之后驱动退回修复前的被动行为(照样学冷却值、照样重试),并在日志里说一次。 **给不出去的时候也要按住闸。** 一个 scope 因为预算/上限放弃时,限流器**仍然是关着的** —— 此时 `arm_learned()` 给共享 pacer 上闸,下一个订阅不会直接撞上去,把一个 scope 的限流变成整轮的级联。这里用的是被 `_pace_cap_s` 夹过的学习值,所以一个敌意的 `Retry-After: 600` 也不会把下一个 scope 按到它自己的超时之外。 **④ 那条 429 错误现在自带证据。** Azure 的 429 body 是空洞的 "Too many requests. Please retry.",既不说哪一层限流器触发、也不说要等多久 —— 上面那次排查「服务端到底有没有告诉我们等多久」是靠翻容器日志才回答的。现在 `throttle_headers=entity=… ,clienttype=… ,tenant=…`(缺席就是 `none`)跟着错误进 `scheduled_job_runs.errors`,重试日志也标注这次睡眠是 `source=server` 还是 `source=learned/backoff`。 **边界**:节流只作用于 Cost Management。AAD token 端点不传 pacer,保持原来的 1s → 2s 指数退避(有专门测试钉住)。仪表盘的 `list_billing_by_dimension` 用的是每请求新建的 driver 实例,起始间隔为 0,行为不变。 🔴 **发布后的验证跑撞上了 1800s 任务超时,于是当天把主动节流改成默认关(同日追加提交)。** 手动触发一次(04:20 UTC),36 个订阅**只跑到 27 个**就超时,而这个 job 的基线是 587-775s。取证:88 次 CM 查询 / 34 次 429 / 0 次放弃,**`pacing budget spent` 一次都没打**(⇒ 主动等待 < 600s),真正的大头是 34 × ~36s ≈ 1224s 的常规 429 退避;服务端冷却值全程平在 34-38s,限流器并没有在收紧。也就是说在那个(负载很重的)限流器下,节流**没有挡住 429**,只是花掉了余量。那个限流器状态有我自己的锅(同一小时内我先跑了一次 11 分钟的、又试了三次),所以这不构成「节流有害」的证明 —— 但它证明了「节流是零成本的」这个模型**会错**,而这条 cron 不能每晚拿自己去试。 所以**默认只发那部分「不可能变慢」的修复**:头缺席的 429 复用服务端冷却值(`observe_throttle` 与节流开关无关,关着也照样学)、两条预算、限流头诊断。主动节流退到集成配置项 `cost_pacing_enabled`(默认 `false`)后面,要评估请**只在一个 Azure 集成上打开**,拿一整周的 run 时长 + `grep -c 'Azure HTTP 429'` 和基线对比,而不是在一次手动跑之后几分钟内。新增一条测试钉住默认是关的、且关着时头缺席兜底照常工作。 **只对 429 学,不对 5xx 学。** 学到的冷却值只用在 429 的兜底上;5xx 不是限流,把一次瞬时服务端错误按在 45s 冷却后面只会拖慢恢复,那条路径保持原来的指数退避。 **验证**:7 条新测试,**逐条做了变异验证**(把修复分别改回去 → 对应那条转红,其余不动):头缺席的 429 复用服务端冷却值(改回指数 ⇒ `[45, 2]`)、一个 scope 学到的冷却值给下一个 scope 上闸且第二个 scope 只发一次请求(关掉 `pacing_enabled` ⇒ 不等)、干净成功后间隔减半 `[40, 40, 20, 10]`(衰减因子改 1.0 ⇒ 全 40)、单次调用累计预算在 300s 超时前收手(去掉预算 ⇒ 睡 228s)、整轮节流预算耗尽后退回被动行为(去掉预算检查 ⇒ 多出一次 15s 等待)、429 错误带上限流头(去掉 ⇒ 匹配不到)、非成本端点保持原指数退避(给 token 端点接上 pacer ⇒ `[20, 20]`)。既有 43 条 Azure 驱动测试全绿(共 50)。 **写这一条时踩的坑,记下来**:`pace_run_budget_s` 是**默认参数**,Python 在 def 时就绑定了模块常量 —— 测试里 `monkeypatch.setattr(module, "_CM_PACE_RUN_BUDGET_SEC", 70)` **静默无效**,那条测试对着 600s 的真实预算跑,是断言里多出来的那次等待暴露的。测试改成显式传参。 > **2026-09-05(同日第四轮)— feat(access-lifecycle): 访问对象闭环 PR2 —— 数据集授权进入生命周期(个人 180 天可续期 + 服务账号半年度负责人确认),权限目录的审批从死路变成站内一键批(迁移 **606** / +16 端点 / +2 cron / +13 MCP → hint **613** / +10 通知模板 / 0 新角色)** 审计(2026-09-05)里两条「授予之后再没有人管」。**DAX 个人授权没有到期日**:`data_access_bindings` 只有 `granted_at / revoked_at`,一条 BigQuery 数据集的个人 read 授权除了本人主动撤或离职永远活着;服务账号授权连「谁在为它负责」都没人定期确认;`revoke_stale_personal_bindings` 只在下一次 apply 里按 `employment_status` 兜底 —— 那是安全网不是流程,离职流程对 DAX 完全没有概念。**权限目录 `requires_approval=True` 是死路**:2026-07-07 的 fail-closed 把自助申请直接拒掉让员工「联系 IT」,`PERM_EXPIRED` 这个状态没有任何代码会设它。用户拍板(2026-09-05):个人授权默认 **180 天** + 服务账号**半年度负责人确认**;权限审批**不走飞书,软件负责人 / IT 站内批**。 **DAX 授权生命周期([`data_access/lifecycle.py`](../server/app/domains/data_access/lifecycle.py))。** 授予那一刻给个人授权盖 `expires_at`(`data_access.grant_lifecycle.personal_ttl_days`),给服务账号授权盖 `owner_confirmation_due_at`(182 天)。持有人按阶梯 T-14 / 7 / 1 收到续期卡,「续期」写一句理由延 180 天、**最多自助续 2 次**,之后必须重新走飞书申请让数据集负责人再看一眼;管理员可延长(不消耗续期次数)、可回收。到期与逾期**全部走 DAX 自己的 `revoke_data_access_binding`**(新增 `system_context` 参数)→ absent effect → apply-absent reconciler,BigQuery 仍然只有一个写入者。服务账号:到期给技术负责人(`DataAccessServiceAccountProfile.technical_owner_person_id`)发确认卡、每 7 天催,「确认仍需要」把时钟推半年,「不再需要」回收,超过 30 天宽限按策略回收。每一步写进新表 `data_access_lifecycle_events`(管理台时间线抽屉读它)。每日 `data_access.grant_lifecycle`(09:30 上海)先补齐缺到期日的老授权(**至少 30 天缓冲**,迁移回填同样 `GREATEST(granted_at+ttl, now+30d)`,不会让迁移当天一批人失去访问),再做提醒 / 到期 / 确认 / 逾期,最后给 IT 一张日报。 **四个开关,两条闸。** `employee_push_enabled` / `owner_confirmation_push_enabled` 默认**关**(2026-09-05 决定①:先发 IT 汇总,逐类灰度)—— 关着时提醒**不推进阶梯**、只进 IT 日报,开了之后持有人才从 T-14 开始收到卡;`auto_revoke_on_expiry` / `auto_revoke_on_confirmation_lapse` **拒绝在对应推送关着时打开**(服务端校验,`DATA_ACCESS_LIFECYCLE_SETTINGS_INVALID`)—— 一条授权不能在持有人没被提醒过的情况下消失;自动回收关着时,过期授权在管理台标「已过期待处理」、日报里单列。 **权限目录站内审批([`permission/lifecycle.py`](../server/app/domains/permission/lifecycle.py))。** 新状态 `pending_approval`(等审批)与既有 `pending`(已批准、云侧开通中)**分开** —— 后者的语义「已批准」不能被借用,provisioning 成功钩子只见 `pending`。审批人 = 软件的 `owner_person_id` / `it_contact_person_id`;软件没登记负责人时路由给全体 global_admin。批准可给有效期(`valid_days`,或策略默认),行进 `pending` + GRANT 任务;拒绝 / 撤回 / 管理员在待审批上「回收」= 拒绝;`admin_grant` 落在一条 `pending_approval` 上就是决定(保留申请人理由,管理员的理由进 `decision_note`)。每日 `permission.lifecycle_sweep`(09:50 上海):待审批 3 / 7 天催审批人、7 天抄送 IT;`expires_at` 已过的 active 权限发 REVOKE 任务(context `terminal_status=expired`),任务成功钩子把状态落成 **`expired` 而不是 `revoked`**,账本分得清「到期」和「被撤」;持有人是否收到「已到期」由 `notify_holder_on_expiry` 控制,默认关。 **离职 / 转岗 / 自证三处补齐同一个谓词。** `RES_DATA_ACCESS_GRANT` 进 `IMMEDIATE_REVOKE_RESOURCE_TYPES`(T+0 第一个 tick 就撤,与 VPN / 云授权同族)、离职扫描器 / 预览 / 管理员手动回收三条分支、`mover_holdings._LOADERS` + `RESOURCE_DISPOSITIONS`(转岗复核包)、T+1 `post_leaver._scan_person` 残留、半年度自证 `SELF_ATTESTATION_ACCESS_TYPES` 新增 `data_access_grant`(elevated,可自助放弃 → 走 release 路径)—— 全部读同一个 `select_personal_active_bindings`,不再各自写一遍「这个人的 DAX 授权是哪些」。 **界面。** 新页 **数仓 ▸ 授权清单与生命周期**(`/admin/data-warehouse/grants`):六张 KPI(即将到期 / 已过期待处理 / 待负责人确认 / 确认逾期 / 30 天续期 / 30 天生命周期回收,点击即筛选)、按生命周期 / 身份类型 / 状态 / 搜索的清单、每行延长 / 回收 / 时间线抽屉、策略抽屉(四个开关带闸门说明)。员工 **我的数据集权限** 加「有效期」列(到期倒计时 / 续期次数 / 服务账号确认到期)、续期 / 释放 / 「确认仍需要」三个动作和策略说明条,深链 `?renew= / ?release= / ?confirm=` 从提醒卡直达。**我的待办** 新增「软件权限审批」(批准时选有效期 长期 / 90 / 180 / 365)与「数据集服务账号确认」两个 tab。权限管理台授权 tab 新增待审批 / 已到期 / 已撤回状态、有效期 / 决定人列、行内批准 / 拒绝、「审批策略」弹窗;软件目录里权限申请的标签从「飞书审批」改成「需负责人审批」。 **顺手修的一个真 bug:** PR1 的 API Key 闲置月报 dedupe 读 `notification_outbox.related_resource_id`(CHAR(36))时绑的是 `UUID` 对象,永远匹配不到 —— 同一天再跑一次会再发一遍。两处都改成绑字符串;本轮的 DAX 日报 dedupe 有测试钉住。 **验证**:新增 [`test_grant_lifecycle_2026_09_05.py`](../server/tests/test_data_access/test_grant_lifecycle_2026_09_05.py)(31 条:开关闸 / 盖章 / 续期上限与管理员越过 / 延长从「现在与到期取晚者」起算 / 释放幂等 / 30 天缓冲补齐 / 推送关着不推进阶梯 / 阶梯每格只发一次 / 过期不回收只标记一次 / 开着走 revoke 路径 / 服务账号发起、每周催、宽限后回收只在开关开时 / 确认推钟、拒绝回收 / 日报按日去重 / T+0 立撤 / 转岗与 T+1 / 自证快照与自助放弃 / 管理与员工端点权限与形状)与 [`test_in_app_approval_2026_09_05.py`](../server/tests/test_permission/test_in_app_approval_2026_09_05.py)(10 条:落 pending_approval 不开任务 / 无负责人路由 IT / 非审批人 403 / 批准给有效期并在钩子后 active / 拒绝与撤回与重申请复用行 / 待审批上的回收 = 拒绝、admin_grant 转换 / 催办与升级 / 到期发任务落 expired、持有人推送默认关 / 策略端点)。删掉了前提已不存在的 `test_request_requires_approval_guard.py`。前端 `pnpm typecheck` / `pnpm lint`(13 道闸)/ vitest 全绿。 > **2026-09-05(同日第四轮)— feat(asset): 财务固定资产台账对账做成常设功能 —— 补金额只是一半,另一半是「财务在折旧一台台账里没有的设备」(迁移 **605** / 7 端点 / 0 cron / +2 MCP → hint **602**)** ⚠️ **「约 50% / 约 200 件」已于 2026-09-05 生产实跑后更正为 36.6% / 52 件(见同日第十轮条目)—— 那是落笔前的估算,不是量出来的。** 上一轮把完整度从 27.6% 推到约 50% 就到顶了:692 件缺金额且有型号的资产里只有约 200 件能找到同型号参考价(299 台显示器、49 台网络设备、36 块会议屏一件都没有)。剩下的只能来自财务固定资产台账,按序列号匹配。 **做成常设功能而不是一次性脚本(用户拍板)。** 理由不是工作量,是**对账不是一次迁移事件**:台账每个月结都重新导出、Helix 一直在进新设备,而且这个面最有价值的产出**不只是补上来的金额**,是两组分歧 —— 脚本会把它们打印到终端里一次然后丢掉: | 分歧 | 含义 | |---|---| | `conflict` | Helix 已经**录入**了一个不同的金额。两本账对不上,这是要人看的发现,不是要静默覆盖的东西 | | `unmatched` | 台账里有、Helix 里没有任何资产用这个序列号 —— **财务在折旧一台资产台账根本没有的设备**。这是完整度缺口的反面,而且在平台里的**任何其他页面都看不到** | **两张表,预览-再-写入。** `asset_cost_reconcile_runs` 是一次上传,`asset_cost_reconcile_items` 是台账的一行 + 匹配判定 + **预览那一刻的 Helix 侧快照** + 逐行决定。上传**一个字都不写**;item 行是事后审计的凭据 —— 「我们接受它那天台账说的是什么」从资产行上是找不回来的。 🔴 **写入前用快照重新核对,不一致就拒绝并报出来。** 操作者是对着预览时的值做的决定;在写入时重新取当前值等于**把一次并发修正藏起来**而不是暴露它 —— 那正是一次对账悄悄覆盖掉别人订正的方式。dev 实测:预览后有人把冲突那台的金额改成 8888,再点写入返回 `applied=0` + `stale=[{asset_tag: RC-CONFLICT, reason: changed_since_preview}]`,原值一动没动。 **匹配规则一律拒绝猜**:只按序列号,且走全仓同一个 `mdm_serial_key` 归一化(两套归一化会让两边静默停止匹配);一个序列号匹配到多台资产是 `ambiguous`,**永不写入**(选一台等于把一个金额写到随便一行上);缺序列号 / 金额解析不了是 `invalid` 并报出来,不静默跳过;**有金额没币种也算 `invalid`** —— 那正是这一系列要修的那个缺陷,再导进来一批是荒谬的。 **`purchase_date` 只补不改。** 台账的「入账日期」是会计日期,和资产行记的取得日期可以合理地不同;覆盖它会**无声地把整条折旧计划改期**。有一条测试专门钉住这个方向。 **`ambiguous` 这条分支现在走不到,但保留 —— 并且测试改成对着分类器断言而不是造一个约束不允许的库状态。** 查了生产:`asset_items` 上有 `UNIQUE KEY uk_asset_items_serial_number`,而且 collation 是大小写不敏感的 `utf8mb4_unicode_ci`,所以两台在册资产不可能共用序列号(生产实测重复 0 条)。但那个唯一索引**忽略软删**,以后被删掉或改成带条件的,静默选一台就会把钱写到随便一行 —— 所以 fail-closed 的分支留着,代码和测试注释都写明它当前不可达以及为什么留。 **两个 dev 验证抓到的真问题**(都是跑真服务器才看见的): 1. **行序声称「最严重在前」,实际是字母序** —— 按 `match_status` 列排序恰好把 `conflict` 排前面,但把 `unmatched` 排到了最后,而那是这个面存在的两个理由之一。改成显式的 CASE 排序(conflict → ambiguous → unmatched → matched → invalid),注释写明为什么不能按列排。 2. **`match_note` 是后端生成的英文散文,直接渲染到了表格里** —— zh-CN / ja-JP 的操作者面前一段英文;而且对 `conflict` 来说它只是把旁边两列已经显示的两个金额又说了一遍。改成可见文案按 `match_status` 走 `t()`,后端原文留在 tooltip 里;`ambiguous` 那一条的 note 带着撞号的资产编号(是别处没有的信息)所以额外附上。 另外两处:`uploaded_at` 是秒级 server default,两次同秒上传会让**列表顺序未定义**,而页面拿 `items[0]` 当「最新一次」—— 加了 `id` 做确定性 tiebreaker;`AssetCostReconcileRun` 少了 `eager_defaults`,序列化紧接 flush 读 `uploaded_at` 会 MissingGreenlet(和 `AssetLocation` 同一个原因)。 **落在 `硬件财务` 页而不是资产清单**:这是一个**财务工作流**(上传台账、审分歧、写金额),而硬件财务就是面向财务的那一页。两个 tab,不新增第十个侧栏项。 **MCP 只给两个只读工具**(`list_asset_cost_reconcile_runs` / `get_asset_cost_reconcile_run`),**刻意不给 upload / apply / skip / discard**:upload 本身无法镜像(MCP 传不了文件);而 apply 是「把一份 LLM 没上传、也看不到原件的台账里的金额写到资产行上」—— 那正是必须一个人看过预览再点头的动作,给它一个工具调用等于把「两本账不一致要人来判」这条设计从流程里拿掉。理由写进了 tools.py 的 hint 注释块。 **验证**:新增 [`test_cost_reconcile_2026_09_05.py`](../../server/tests/test_asset/test_cost_reconcile_2026_09_05.py)(29 条:预览不写任何东西 / 序列号大小写空格归一 / 录入值不一致是 conflict 而非覆盖 / 一致不算 conflict / 只差币种也是 conflict / 估算值被台账取代 / unmatched 被报出 / **ambiguous 走分类器** / disposed+软删不参与匹配 / 有金额没币种 invalid / 缺序列号与解析失败 invalid / 不支持的币种 invalid / **中文表头+千分位+¥+斜杠日期都能解析** / 空文件拒绝 / 写入打 finance_register 标记 / **购入日期只补不改** / 冲突需显式开关 / unmatched+invalid 永不写入 / **快照不一致时拒绝并报出** / 逐 item 幂等 / 只写选中行 / skip 是有审计的决定 / 已写入的 run 不能废弃 / 废弃后不能写入 / **filter 下 breakdown 仍覆盖全 run** / 计数去规范化正确 / 审计记 before+after / 列表最新在前 / **端到端断言完整度真的上升且不被算成估算**)。`tests/test_asset` + `tests/test_onboarding` **1085 绿**;`ruff` / `mypy ratchet`(1279 = baseline)/ `web` 完整 `pnpm lint`(13 guard)/ `pnpm typecheck` 全绿。 **dev 实测**:604→605 往返;上传一份带中文表头的真 CSV(6 行:2 行无金额、1 行冲突、1 行估算、1 行 ghost、1 行没币种),预览判定 3/1/1/1 全部正确且**资产行零改动**;不带冲突写入 → 3 行落库并标 `finance_register`、冲突那台原值保留、**购入日期没被改**、run 保持 `previewing`(还有待处理);制造并发修改后带冲突写入 → 拒绝并报 stale;浏览器实测两个 tab、行序、三语文案、估算标签。**随后删净全部种子数据与 6 条审计行。** > **2026-09-05(同日第三轮)— feat(asset): 资产财务完整度 27.6% 的缺口不是「四个字段都缺」;顺带把三个低分的根因做成常设自检页(迁移 **604** / 1 端点 / 0 cron / +0 MCP)** **先说这轮最有价值的一个发现:缺口的形状和「四项都缺」完全不一样。** 生产 1050 件在册资产里 760 件不完整,但按字段拆开看: | 字段 | 缺失行数 | |---|---| | `purchase_date` | **0** | | `purchase_entity` | 3 | | `purchase_cost` | **718** | | `currency` | **718** | 其中 673 件两者都缺、42 件有金额没币种、42 件有币种没金额;758 件是 2026-04 易盘点历史导入;5 月以后 Helix 自建的资产 19 完整 vs 2 不完整 —— **入库表单没问题,问题是历史存量**。一个笼统的「不完整 760 件」会把运维引向「去检查入库表单」,而真正要做的是两件完全不同的事。所以自检页按字段拆开报,不报一个总数。 🔴 **42 件「有金额没币种」不能按采购主体推币种 —— 这条本来是我要写的规则,生产数据把它否掉了。** 那 42 个金额全是中国区人民币标价(8499 / 10999 / 12999 / 14999),连挂在 `PINGCAP (US), INC.` 名下的 13 件也是;而已完整的行里 US 主体是 21 件 CNY 对 7 件 USD。所以回填脚本对这 42 件**统一写 CNY**,并把「不要按主体推」和理由写进模块文档,避免下一个人重新发明这条错规则。 **迁移 604:`asset_items.purchase_cost_source`(`recorded` / `estimated_model` / `finance_register`)。** 这一列不是为了好看:折旧、BvA、成本归属全都读 `purchase_cost`,而补上来的金额有三种权威度完全不同的来源。**一个单独的金额列说不出它是哪一种**,估算值一落库就和发票金额无法区分 —— 那正是一次便利的回填变成财务无法辩护的数字的方式。刻意用 varchar + 应用层词表而不是 MySQL ENUM:TiDB 拒绝对 enum 做 `MODIFY COLUMN`,以后加第四种来源会要一整轮 expand-contract。 ⚠️ **迁移号从 603 改到 604**:另一个会话(访问对象闭环)的 PR #3440 并发占了 603,在两边都还没 push 时同步了一句,于是我这边上移。两个分支都取同一个号会变成 2 heads、把每个后端 shard 和镜像构建都打红 —— 文件头写清了这件事。 ⚠️ **「约 50% / 约 200 件」已于 2026-09-05 生产实跑后更正为 36.6% / 52 件(见同日第十轮条目)—— 那是落笔前的估算,不是量出来的。** 🔴 **回填脚本默认 dry-run,而且把自己的天花板写在文档第一段。** 692 件缺金额且有型号的资产里只有约 200 件能找到同型号参考价,几乎全是 laptop(299 台显示器、49 台网络设备、36 块会议屏一件参考都没有)。两个 pass 跑完完整度只能从 27.6% 到约 **50%**,**仍然是 30 分档**。要过 90% 只能靠财务固定资产台账 —— 脚本明说这一点,不假装自己解决了问题。同型号中位数只在样本 ≥3 且样本自身价差在 1.5 倍内时才写,超出的型号逐个列出来等人定价:一个跨配置的中位数是没人能辩护的数字。 **新增 `GET /assets/ledger-health` + 资产工作台「资产健康」tab 顶部的台账健康度自检面板。** 四张卡片(资产财务完整度 / 长期闲置电脑 / Day-1 硬件缺口 / 从未盘点的电脑),每张给原因、数量、以及**一个能真正去处理的入口**。刻意不新增 tab 也不新增菜单项:那个 tab 原本答的是「机器健不健康」(保修/维修/故障/报废),自检答的是「台账说的是不是真话」,同一个页面标题下的两种读法,自检放在上面因为它才是看到低分之后来这一页的原因。 **每一节都复用拥有该指标的服务,不重算**:闲置读 `IdleComputerService`,Day-1 读 `OnboardingHardwareGapService`,财务的四字段谓词与 `AssetFactProvider` 逐字一致 —— 并且有一条测试**直接对着 provider 断言**(而不是对着一份抄下来的字段清单),任何一侧改了另一侧没改就会红。 **「其中 N 件金额为估算」在自检页和健康分 facts 里都单独报。** 回填之后「完整度 90%」如果不说清其中多少是同型号中位数,那这个数字就在骗人。`financial_estimated_count` 进了 `aggregate_facts`,页面上是一个带 tooltip 的标签。 🔴 **一个 dev 验证抓到的真 bug(光看代码看不出来)**:`purchase_cost_source` 加到了 model 和 schema 上,但 `enrich_with_users` 是按**显式字段清单**拼 dict 的,漏了这一个字段 —— 而 `AssetResponse` 给它的默认值正好是 `recorded`。结果是**每一件估算资产在详情页都自称是「录入值」**:不报错、不抛异常,数字只是错的。这是这类 bug 最恶劣的形状。已修 + 补了一条回归测试,测试注释里写明为什么「加了列、加了 schema」不等于「传到了前端」。 **验证**:新增 [`test_ledger_health_2026_09_05.py`](../../server/tests/test_asset/test_ledger_health_2026_09_05.py)(15 条:默认 recorded / 词表封闭 / 估算算完整但单独报 / finance_register 单独报 / **按字段拆开的缺失统计** / 两种便宜形状分别计数 / **与 provider 直接对账** / 按类别排序 / disposed+软删出分母 / 闲置节复用闲置服务 / Day-1 节复用缺口服务且不编造 0% / 从未盘点只算电脑 / 每节都有可动作路由 / 合计等于各节之和 / 空资产不报错 / **序列化携带 provenance 的回归**)。`tests/test_asset` + `test_onboarding` + `test_intelligence` 合计 **1295 绿**;`ruff` 通过;`web/` 完整 `pnpm lint`(13 个 guard 全过)+ `pnpm typecheck` 绿。 **dev 实测**:手工应用 604 的 DDL(alembic 链要等 603 合并才能本地解析)、种 8 行(4 行同型号有价 / 2 行同型号无价 / 2 行有金额无币种),dry-run 输出 2+2 且**一个字都没写**,`--apply` 后完整度 50%→100%、估算行 `purchase_cost_source='estimated_model'`、有金额补币种的行**保持 `recorded`**(金额本来就是录入的,只有币种是推断的)、4 条审计行带 `sample_size`;浏览器实测自检面板四张卡片、最严重的排在最前、「其中 2 件金额为估算」显示正确;随后删掉全部种子数据**并回滚了手工 DDL**,dev 库回到 main 的 602。 ⚠️ **还修了 #3438 留下的 mypy ratchet 红灯**:`hardware_gap_service.py` 有 14 个 `call-arg` —— 本仓 mypy **没有装 pydantic 插件**,所以用关键字构造一个可选字段写成 `Field(None, …)` 的模型时,每个省略的字段都算一个错误。改成 `AssetIntakeRequest.model_validate({...})` / `AssetClaimRequest.model_validate({...})`:验证一点没少,而且这里本来就是「一个请求模型映射到另一个」,dict 投影把跨边界的字段写得更清楚。ratchet 回到 1279 = baseline。 ⚠️ 顺手修了两处我在 #3439 里弄红 main 的 guard(ja-JP 未翻译 / status-color 白名单死条目)—— 另一个会话在 #3440 里也修了同样两处,我采用了他们的翻译写法以便干净合并。根因是我那次只 grep 了 `✖|error `,而这套 guard 的失败行不含这两个词。**判据改成:`pnpm lint` 必须整段跑完、13 个 guard 全过才算过。** > **2026-09-05(同日第三轮)— feat(access-lifecycle): 访问对象闭环 PR1 —— 撤销要落地:SSO 撤了要在 IdP 侧真的没了,API Key 转手要轮换、闲置要有人问(迁移 **603** / +7 端点 / +2 cron / +6 MCP → hint **600** / +7 通知模板 / 0 新角色)** 审计(2026-09-05,五路代码只读)里最重的一条:`SsoGrantService.revoke` 把 `status` 翻成 `revoked` 之后,只给系统负责人和 IT 发一张正文写着「**没有**自动移除,请去 IdP 手动停」的卡 —— 没有任务、没有到期、没有复核。撤销之后这条残留反而从半年度自证的快照里消失,比撤销前更不可见。同一条链上,离职者的 API Key 被强制转给经理时 `apply_transfer` **明写 `do NOT touch status`**(转出去的人仍然知道明文),而三条 apikey cron 里没有一条问过「这把 Key 还有人用吗」—— 隔壁 `cmdb.zero_spend_alert` 对云订阅早就做了同一件事。 **SSO 撤销拆成两半:「决定撤」和「真的没了」。** `sso_grants` 上新增一组 `removal_*` 列(`removal_status` ∈ `pending / confirmed / verified / contradicted / unverified_legacy`)。撤销那一刻给系统负责人(无活跃负责人则 IT)开一条 `manual_notify` provisioning 任务(新 `target_type='sso_grant'`),**完成必须带凭证**(工单号 / 控制台链接 / 一句说明)—— 一键页现在渲染一个必填的 evidence 输入框,`complete_manual_task` 对这类任务拒绝裸提交,**管理员也一样**(要的是留痕不是权限)。每日 `sso.removal_reconcile`(08:40 上海):没任务就补开;按阶梯 3 / 7 / 14 天催办、第二次起抄送 IT、只能拉长不能收紧;14 天开 `sso_removal_overdue` 合规事件,确认后自动 resolve;对 Google 提供方拉 **Admin Reports 的 SAML 登录审计**(新驱动方法 `list_saml_login_events`,scope `admin.reports.audit.readonly`)—— 撤销之后仍有登录 → `contradicted`,作废之前的人工确认、重开任务、通知负责人+IT;已确认满 7 天无登录 → `verified`;IdP 账号已不存在 → `verified`。**「核实」是证据不是推断**:我们台账里的应用名和 Google 里的 `application_name` 对不上时,记 `app_name_unmatched`、状态不动 —— 一个改过名的应用「没有登录」和一个真的停了的应用长得一样,只有历史上出现过同名登录的应用才允许拿「无登录」当证据。缺 Reports 权限记 `google_reports_scope_missing`,不判失败。 ⚠️ **历史行标成 `unverified_legacy`,不回填成 `pending`。** 603 之前撤销的授权从没有人核实过;把它们统统开成任务是推测性回填,标成一个看得见的状态、由管理员在台账上勾选批量「开移除任务」才诚实。**离职 T+0 批量路径保持 R59F-C 的约束**:没有活跃负责人时任务直接落 `notified`、不发 DM(IT 已经收到那张按人合并的汇总卡),有负责人时按系统一张 DM 是期望的路由。 **半年度自证的两个死路修掉。** `enqueue_self_service_removal_for_cert_item` 里 `sso_grant` / `api_key` 此前落终态 `manual_required`(「无自动路径,交 IT」= 没人管)。现在 SSO 走上面这条撤销落地链,任务完成 / 登录审计核实 / 矛盾三种结局都镜像回自证项(`sync_cert_items_for_sso_grant`);API Key 走**持有人自己的释放流**(`submit_release_for_attestation`,主管审批 —— 一把 $0 的 Key 可能还挂在某个忘掉的生产任务上),批准 → `completed`,驳回 / 转移期间自动驳回 → `failed`,**从不写成 completed 之外的「已处理」**。 **API Key 转手即轮换。** `apply_transfer`(员工转交和离职强制转移共用)末尾入队一次轮换:Bedrock / Bailian / Azure OpenAI 走既有 `rotation.py` 状态机,旧凭证按 `apikey.transfer_rotation_grace_days`(默认 7)退役;不可轮换的提供方(手工填的 Key、SaaS)记 `manual_required` 并给**新持有人 + IT** 发「需手动轮换」卡;mint 失败(AWS 两把 Key 上限、云侧 5xx)记 `failed` 带错误码、同样发卡,**永不阻断转移本身**。`apikey.rotate_on_transfer` 默认开,可关。 **闲置 API Key 终于有人问。** 新 cron `apikey.idle_check`(每月 3 日 09:30 上海,等账单入库):`status='active'` 且发放满 45 天的 Key,上自然月 `compute_assignment_spend` 为 $0 且数据可用 → 闲置;Bailian 等拿不到按 Key 花费的记 `skipped_no_data`,不猜。新表 `apikey_idle_alerts_dedup`(`assignment × billing_month` 唯一)是台账也是「这个月问过了」;`detail.idle` 带连续月数与持有人的回复。**IT 每月一张汇总(始终)**;员工那张「保留(写理由,6 个月免打扰)/ 释放(走主管审批)/ 找 IT」卡由 `apikey.idle_alert.enabled_for_employees` 控制,**默认关** —— 2026-09-05 用户拍板「新增员工触达先发 IT 汇总,逐类灰度」,开关在管理台「闲置」tab 上。持有人或共享成员可 `POST /apikeys/assignments/{id}/idle/keep`;管理台 `GET /apikeys/idle`、`GET/PUT /apikeys/idle/config`(改开关落审计)。 **界面。** `/admin/sso-apps?tab=grants` 顶部一条六格状态带(待落地 / 逾期 / 撤销后仍登录 / 历史未核实 / 已核实 / 无法核实,点击即筛),新列「IdP 侧移除」带状态、确认人、最近登录 / 检查时间和无法核实的原因,行内「开移除任务 / 立即核实 / 详情」,详情抽屉是撤销 → 任务 → 确认 → IdP 审计的时间线;历史行可勾选批量开任务;`?removal=open` 深链来自催办卡。`/admin/assets/api-keys` 新增「闲置」tab(KPI + 触达开关 + 台账,`?idle=1` 深链来自 IT 月报);`/me/api-keys/:id` 在闲置时顶部横幅给保留 / 释放 / 找 IT,`?idle=keep|release` 一键落到对应动作;列表页闲置行带标签,`?release=` 直接打开释放弹窗。`/me` IT 宇宙新增「SSO 授权」tab —— 此前 SSO 授权是唯一没有任何员工可见面的访问对象;正在撤销中的行保留在列表里直到 IdP 侧落地,员工看到的是「正在被收回」而不是「凭空消失」。 **顺手修了一条 main 上的 mypy 红**:`github_org.py:738` 把 `resp.json()` 赋给了一个已经是 `str` 的变量名(#3387 引入),Backend Lint 的 ratchet 在 main 上是红的;改名 + 标注,baseline 随之缩 1。 **验证**:5 个新测试文件 / 30 条(SSO 撤销开任务与两种通知语义、凭证要求含管理员、取消即脱钩、reconcile 的阶梯 / 20h 地板 / 事件开与 resolve、登录审计五种结局、legacy 批量、路由与 `/me`;转手轮换四种结局 + 自证释放批准 / 驳回镜像;闲置评估阶梯与 streak、员工灰度门 + IT 月报 + 不重复打扰、keep 的授权与理由、HTTP 面含审计;一键页的凭证输入与拒绝;Google Reports 解析与错误映射);受影响域既有测试 1157 条全绿;`alembic upgrade head` 空库全链 + `downgrade 602` + 再 upgrade 幂等;`check_alembic_chain` 单头 603、`check_tidb_parity` OK;`pnpm typecheck` / `pnpm lint` 全绿;mypy ratchet 1279(基线 1280)。**未在生产核过**:DwD 服务账号是否已授 `admin.reports.audit.readonly`(缺的话台账「无法核实」列会告诉你,不会假绿)。 > **2026-09-05(同日第二轮)— feat(asset): 长期闲置电脑盈余率 20 分终于有清单可看;顺手把资产菜单从 11 项并到 9 项(0 迁移 / 2 端点 / 0 cron / +1 MCP → hint **594**)** 「长期闲置电脑盈余率 21.9%(20 分,失败率最低档)」这个数以前只能在健康分页看到 50 个裸资产 id ——没有位置、没有年份、没有任何可以点的动作。用户的要求是「在平台里能有列表看到 直观显示的暴露问题 我让孟凡生去处理」,所以这轮做的是**能交给人去干活的那张表**。 **生产事实**:617 台在册电脑,**146 台长期闲置**,其中 **136 台在 Helix 里从来没有过任何一次流转记录**(2026-04 易盘点历史导入进来就一直躺着);76 台在北京、34 台在美国;采购年份 2021×59 / 2022×29 / 2023×31 / 2024×11 / 2025×15;**84 台从未被任何一轮盘点覆盖过**。 **新页面把口径写在数字旁边。** 这一条不是文案洁癖:看不见「闲置」怎么量的人会去和数字吵架,而这个指标刻意拒绝的两种读法(拿 `updated_at` 当闲置时钟 / 把外设算进分母)恰好就是最容易误读的两种。所以 Alert 里直接写清:只算电脑、闲置按最后一次真实流转算、回复盘点不清零、近期入职需求先扣掉。 🔴 **被扣掉的那些机器要显示出来,不能藏。** 近期还缺电脑的入职需求从闲置队列里扣掉之后,剩下的才是盈余;被扣掉的那几台标成「留给待入职」(`is_surplus=false`)照样列在表里。藏起来会让总数解释不通,标成盈余会让人去处置下一个新人的笔记本 —— 两种做法都是在对操作者说谎。MCP 工具描述里也把这一条写死了。 **服务端复刻指标口径,不是重写一遍。** `IDLE_DAYS=90`、库存状态集合、`asset_operations` 读时钟、+30 天需求视野,全部与 `app/intelligence/providers/assets.py` 逐条对齐,并在注释里写明「这张表解释那个分数,阈值不一致就会让页面和分数互相矛盾」。测试里有一条专门钉住 `surplus_rate_pct` 等于分数用的同一个分式。 **筛选项从未筛选的行集派生。** 选了「北京」之后位置下拉里仍然有「美国」—— 本仓踩过的坑:从被筛结果派生选项会让选中的那个变成唯一选项、把人关在里面。同理 `summary` 里除 `filtered_count` 之外的合计**不跟着筛选变**,否则一加筛选页面就显得和健康分对不上。 **区域作用域按写闸的规则来**:全局层看全部,区域 `asset_admin` 只看自己管的位置,**位置解析不出来的资产属于任何区域都不属于**(只有全局层能看)—— 和 `person_can_manage_asset` 完全一致。导出走同一个作用域和同一批筛选,否则会给区域管理员一份 UI 上看不到的表格。 --- **顺带做完了菜单合并(用户同一轮提的:「资产相关的前端的菜单是不是太多了 有没有可以合的」)。** 资产管理原本 **11 项**,本仓约定是**扁平 ≤10 项、相关页面用页内 Tabs 合并**(2026-06-28 用户明确说过 antd 的分组菜单样式不要再用)。新增闲置电脑如果直接加一项会变成 12 项,所以合并必须和这个功能同一个 PR 做,而不是另开一轮。 | 动作 | 结果 | |---|---| | 操作记录折进资产工作台的「操作记录」tab | 那个 tab 本来就是同一份数据的 5 行预览 + 一个「查看全部」跳出去的按钮 —— 同一份数据两个入口。现在 tab 直接挂完整页面(筛选/分页/确认动作全在) | | 回收站折进新的资产清单 hub | 228 行、和在册资产同一数据形状 | | 长期闲置电脑 | 作为资产清单的第二个 tab,**不新增菜单项** | 11 → **9 项**:资产工作台、资产清单、资产入库、资产盘点、MDM 设备台账、员工申请、团队资产、硬件财务、资产设置。 **刻意保留在顶层的两项,理由写进了代码注释**:资产入库是高频**表单**(不是列表),工作台的主按钮就指向它,折进去反而变慢;硬件财务折进工作台会让那个页面变成 8 个 tab,只是把拥挤从侧栏搬到页内。 **折页面时清掉的真实死代码**:工作台的操作记录预览连带 `operations` state、`operationColumns`、两张颜色映射表、以及**每次进工作台都会发一次的 `listOperations` 请求**(渲染 5 行用的)全部删除 —— tab 现在自己取数。`AssetListPage` 在 embedded 模式下把 PageHeader 里的动作(导出/模板/批量更新/新增资产)搬成右对齐工具条,**没有一个动作消失**(直接丢掉会把「新增资产」从它唯一存在的地方删掉)。 **两条老路由保留成 redirect**:`/admin/assets/operations` → `/admin/assets?tab=operations`,`/admin/assets/recycle-bin` → `/admin/assets/list?tab=recycle`。同步改了 5 处指向:资产清单页的按钮、工作台的快捷入口、MainLayout 的菜单高亮映射表(不改会让进了 tab 之后高亮掉回「资产清单」)。`App.tsx` 里三个不再直接挂路由的 lazy import 一并删掉,并留注释说明为什么消失,免得下一个人「修复」回来。 **验证**:新增 [`test_idle_computers_2026_09_05.py`](../../server/tests/test_asset/test_idle_computers_2026_09_05.py)(19 条:显示器永不入列 / 近期流转过的不算闲置 / **回复盘点不清零闲置时钟** / 流转事件优先于建档日 / 已领用与已预留出库存 / disposed+软删排除 / held_by_office 算库存 / 需求扣减且被扣的仍列出且 `is_surplus=false` / 已预留的新人不算需求 / 远期入职不算近期需求 / **facets 来自未筛选集** / 年份与盘点筛选 / `min_idle_days` / 合计不跟着筛选变 / 区域管理员只看自己的位置 / 无位置资产仅全局可见 / 无位置管理员看不到任何东西 / 盈余率等于分数的同一个分式)。`tests/test_asset` + `tests/test_onboarding` 合计 **1041 绿**;`ruff` / `pnpm lint` / `pnpm typecheck` 全绿。 > **2026-09-05 — feat(onboarding): Day-1 就绪率 22.5% 的病因是「机器有、台账动作晚了」—— 预留即就绪 + T+0 自动领用 + IT 侧待核实队列(0 迁移 / 2 端点 / 0 cron / +2 MCP → hint **593**)** 用户看着领域健康页问「我没懂这个 30 分是什么意思」。30 分不是算错,是覆盖率分档的最低档(<80% ⇒ 30)。**先把生产事实数清楚再动手**:近 6 个月 40 条入职单,Day-1 就绪 9 条,31 条失败里 **29 条只差硬件这一维**;其中 20 条是入职后 1–7 天(两条 21/22 天)才在 Helix 里点了领用,另外 11 条至今 `live` 且**台账里一台电脑都没有**(SF / San Jose / São Paulo / Niterói / London / Taipei / HK / Stockholm 加武汉、北京、杭州各一 —— 海外自购/直邮从没补录)。 **根因是激励错位,不是纪律问题。** 备机闭环(`reserve_asset_for_hire`,2026-06-12)早就让 IT 能提前把机器留给某个新人,但**预留满足不了任何维度** —— 唯一能得分的路径是有人在新人第一天早上记得点「领用」。生产实测:`reserved_for_person_id` 全表 **0 行**,`hardware_allocation` 预案历史上只设过 **1 次**。两个工具都在,没人用,因为用了不算。 | 改动 | 为什么 | |---|---| | 硬件维度接受 `assigned` **或** `reserved` | 提前备机变成同时也得分的那条路 | | T+0 转 `live` 时把预留自动转成领用 | 台账说的话和世界一致;三条入口(cron / `advance_now` / 「直接就位」)都接 | | 预留在入职日**之前**被释放 ⇒ 清空 `hard_ready_at` | 「留一小时再放掉」不能白拿 Day-1 | | 入职日**之后**的变动**不改** `hard_ready_at` | 它是历史达成记录,换机/退库不该回写已经结账的月份 | 🔴 **`hard_ready_at` 那条闸的边界是这轮最容易写错的一行。** 无条件清空会让三个月后换电脑把当月的 Day-1 和 SLA 都改写掉(两个指标都读这个时间戳);永不清空则让预留-释放白拿分。判据只能是 `hire_passed`,两个方向各有一条测试钉住。 **11 条欠账走 IT 内部,不给员工发消息(产品决策,已确认)。** 新 tab **入职管理 ▸ 硬件待核实**:窗口是「入职日已过 + 硬件 blocker 仍 pending」,**含 `completed` 入职单** —— 驾驶舱只看 open,那 20 条已完成的缺口在任何看板上都不出现。每行给逾期天数、工作地点、预留设备、**MDM 线索**(Jamf/Intune 按 `assigned_person_id` 或 `mdm_assigned_email` 匹配到的序列号+机型,就是该往表单里填的那个序列号;查不到显式写「MDM 无记录」并在 tooltip 里说清这**只是没有线索,不代表这个人没有电脑**)。两个动作原地关闭:`POST .../register-device` 一次完成「建资产 + 领用 + 关闭缺口」(走 `AssetService.intake_asset` + `claim_asset`,不裸写 ORM,所以资产编号生成 / 品牌型号 upsert / 法人实体解析 / 位置归一全都在),或复用既有的 skip 并写原因。 **领用日期默认取入职日,不是今天** —— 机器从那天起就在本人手上,填今天会把台账历史写错。**采购主体在表单里是必填**:`intake_asset` 用它 + 类别生成资产编号,少了它会在事务中途抛一个 400、错误信息还指向一个这个表单不显示的参数;body 模型里补了 `model_validator` 把它变成字段级 422。 **驾驶舱区分「已预留」和「已领用」**:两者都算 Day-1 就绪,所以区别不能来自就绪字段 —— 加了独立的 `hardware_state` 行字段(批量解析,两条查询封顶,不按人 N+1),电脑那个 chip 保持绿色但加虚线边框 + tooltip 写清「机器已留给本人,入职当天自动转为领用」。刻意**没有**复用 `dimension_states` 的 `reserved`(那个值的语义是「未就绪」,重载会让就绪计数和状态机对不上)。 **跨域走 coordinator**([`onboarding_hardware_coordinator.py`](../../server/app/core/coordinators/onboarding_hardware_coordinator.py)):onboarding 不写资产表。自动领用前对资产行 `FOR UPDATE` + `populate_existing` 并**在锁下重新断言每一个前置条件**(预留还在 / 还是电脑 / 还没被指派 / 状态还在库存集合),否则一次人工领用插在中间会被无声覆盖;`operator_id` 按离职域自动化的既有约定取「语义主体」(新人本人,`AssetOperation.operator_id` 是 NOT NULL),真正区分自动化的是 `detail.via = onboarding_t0_autoclaim` + 审计行。自动领用放在 T+0 的**同一个 SAVEPOINT 里**,claim 失败连 flip 一起回滚,下一 tick 一起重试 —— 不会出现「人已就位、设备还挂在 reserved」。 **验证**:新增 [`test_hardware_reserved_readiness_2026_09_05.py`](../../server/tests/test_onboarding/test_hardware_reserved_readiness_2026_09_05.py)(27 条:预留满足维度 / 预留显示器不满足 / assigned 优先于陈旧预留 / 批量解析覆盖每个入参 id / T+0 转领用并落 `via` 标记 / 幂等 / 锁下拒绝抢别人刚领的机器 / 入职前释放清空 stamp / 入职后变动保留 stamp / 终态进程不回写 / 驾驶舱 `hardware_state` / 队列只列已入职未解决 / 跳过与离职者不入列 / `completed` 入列 / backfilled 不入列 / lookback 窗口 / 预留但未领用被单独标记 / register-device 一次关闭 / 已有设备 409 / 非电脑类别与缺采购主体各一条 422 / 端到端对 `day1_readiness` 断言)。`tests/test_onboarding` 全量 **178 绿**,`tests/test_asset` 全量 **844 绿**;`ruff` 通过;前端 `pnpm lint` + `pnpm typecheck` 全绿。 ⚠️ **一条测试维护上的坑记在这**:`test_hardware_gap_queue_drops_skipped_and_departed` 里把 `employment_status` 用 ORM 属性赋值改成 `left` 会踩 LeaverBlocked 的 `before_flush` 闸(单跑绿、混跑红的典型)。改成 Core UPDATE + `expire`,这也正是生产的写法(HRIS sync 拥有这一列)。 > **2026-09-04(同日第七轮)— feat(ai-labs): 管理端能下钻了 —— 「谁在用」是一个缺失的 GROUP BY,「哪里失败」是一张缺失的表(迁移 **602** / 3 端点 / 0 cron / 0 新 MCP)** 用户原话:「管理员这里无法下钻 不知道谁使用了 哪里失败了呀」。看板上写着「使用人数 2 / 调用 8 / 失败 2」,再往下问就没有答案。 **两个问题的性质完全不同,分开说才说得清:** | 问题 | 之前为什么答不了 | 这轮怎么补 | |---|---|---| | 谁在用 | **不是隐私边界。`person_id` 一直在 `ai_labs_usage_daily` 上** —— 缺的只是一个 `GROUP BY person_id` 和一次目录 join | `/usage/people` + `/usage/people/{id}`,同一批计数行,一列没多读 | | 哪里失败 | **真的记不下来。** `failures` 是裸计数;错误码只写在 `ai_labs_messages.error_code` / `ai_labs_generations.error_code` —— 内容表,管理面按设计不许查,而且员工可以硬删 | 新表 `ai_labs_failures_daily`(`person × 日 × 能力 × 模型 × error_code → 计数 + last_seen_at`),`/usage/failures` 读它 | **新表刻意不是给 `ai_labs_usage_daily` 的唯一键加第六列**:那张表同时是**额度闸的读模型**,加宽键会让每次额度检查多 SUM 出一批行。 🔴 **这轮最要紧的一行代码是 `usage.normalize_error_code`。** 厂商的 `error_code` 是任意字符串,而异步媒体那一族在内容策略拒绝时**会把被拒的提示词原样引回来**(`executor._run_async` 的 `TASK_FAILED` 分支早就有原文注释记着这个行为,当时的处理是「厂商 prose 不入库」)。错误码现在要进的是**整域唯一一张管理员能读的表** —— 所以写入前必须过形状白名单(`^[A-Za-z0-9._:-]{1,64}$`),不是码的形状就记成 `AI_LABS_VENDOR_UNCLASSIFIED`,原文只进日志。**不做截断、不做脱敏**:提示词的一个片段经过脱敏之后仍然是提示词的一个片段。端到端测试用一个窄 needle 钉住(短 needle 会撞 UUID 片段)。 **口径:`counted_failures` ≠ `classified_failures`,差额显式命名。** 新表从零开始,602 之前那些失败的原因写在员工内容行上、按设计读不到、**补不回来**。所以接口同时返回权威计数(旧表)、已分类计数(新表)和 `unclassified_failures`,前端有一条 warning Alert 说清楚。把覆盖 2/8 的拆分当成全部展示,比没有拆分更糟 —— 会把运维引向错误的方向。 **顺带补了两处「失败了但没人记」的洞**,都是这轮做失败面时才暴露出来的 —— 不补的话新卡片会对这两类失败**说谎**: - `_run_claimed` 里 `AI_LABS_CAPABILITY_REMOVED`(任务排队时能力从目录下架)那条早退**一个计数都不记**; - **翻译的失败从来没被计过任何数** —— chat 走 `_persist_failure`、生成走 `_note_outcome`,只有翻译是 `client.chat()` 直接 raise 穿过记录器。「翻译对全公司都坏了」在看板上是零痕迹。现在 `except AppException` 记一次 `requests=1, failures=1, error_code=exc.code` 后原样 re-raise(只带 `code`,厂商 prose 不带)。 **审计的边界**:只有 `/usage/people/{person_id}` 记 `ai_labs.admin.view_person_usage`。查一个**具名**员工用了多少是正当操作,也正是应该留痕的那种操作 —— 这个域的全部立论就是员工可以信任这个面,「谁查过我」是其中一部分;聚合列表不记,否则每次翻页一行审计会把真正要看的那些查询埋掉。 **目录 join 的两个坑,都在实现里绕开了**:① 计数表上的 `person_id` **没有 FK**(计数活过人是花费统计的正确行为),所以目录 join 用 LEFT 语义、查不到的行**照样渲染**成 id,不然离职者的用量会静默从合计里蒸发(生产验证时特意塞了一个 ghost person_id);② 部门标签**不 join 进聚合**,而是分页之后单独一次查询 + `GROUP BY person_id` —— 一个人可能持有多条主组织成员关系(多实例 HRIS),join 进 `GROUP BY person_id` 会把他的计数翻倍。 **验证**:新增 [`test_admin_drilldown_2026_09_04.py`](../../server/tests/test_ai_labs/test_admin_drilldown_2026_09_04.py)(23 条:按人聚合 / 排序 / 搜索 / 未知 sort 回落到白名单 / 离职者不掉行 / 单人四维拆分 / 审计落一行 / employee 403 / auditor 200 / 原因累加而非覆写 / 成功不写原因行 / 8 个 normalize 参数化 / 厂商 prose 端到端不落库 / 口径对账 / 窗口含今天 / 三个下钻端点都不回显真实对话的 needle)。**四轮变异验证**:短接形状白名单 ⇒ 4 条红;窗口 off-by-one ⇒ 1 条红;去掉目录缺失兜底 ⇒ 4 条红;**去掉空搜索短路 ⇒ 全绿**,所以把那条测试的注释改成了它实际钉住的东西(SQLAlchemy 把空 `IN` 渲染成恒假,短路只是省两次聚合查询,不是安全网)—— 变异验证的价值就在这:它拦下了一条本来会写进注释里的假话。`tests/test_ai_labs` 全量 171 绿;`ruff check` 通过;前端 `pnpm lint / typecheck / test(1389) / build` 全绿。 **生产化验证**:本地 dev 起 backend+frontend,种 6 行用量 + 3 行原因(含一个 ghost person_id),浏览器实测两张卡片、可展开的「能力 × 原因」明细、单人抽屉,并核对 `audit_logs` 真落了一行 `ai_labs.admin.view_person_usage`,**随后按 id 逐条删除了种的数据**(dev 库回到原来的 1 行真实用量)。 > **2026-09-04(同日第六轮)— fix(provisioning): 兼岗第三次差点开出邮箱之后 —— 把「这是不是别人的第二段雇佣」这一问搬到**开号那一刻**(0 迁移 / 0 端点 / 0 cron / 0 新 MCP)** 用户原话:「以后不要再有这样的问题了 已经有两次了」。 **两次事故的止点是同一个:开出了一个真邮箱。** 8/25 品川的兼岗变成 `hiroki.shinagawa01@pingcap.com`;9/4 战捷的德国兼岗压在一个已 purge 的离职员工行上,按**死者的地址**开了号、还把这个地址回写成战捷在 SF 的主企业邮箱。两次的根因都是真的、两次的修复也都是对的 —— **但两次都修在入库侧**。入库侧有五条路(webhook / 全量 / 增量 / 手工导入 / 单人刷新),闸只覆盖它被接进去的那几条;而**开号那一刻,从来没有任何东西问过一句「这个人是不是我们已经认识的某个人的第二段雇佣」**。 **这一轮把那一问搬到了不可逆的那两步**:新模块 [`app/identity/sf_assignment.py`](../../server/app/identity/sf_assignment.py),挂在**两个**不可逆入口上 —— `create_account_for`(开邮箱)**和** `reserve_work_email_for`(预占地址 + **回写 SF PerEmail**)。后者单独也必须挡:它按 `personIdExternal` 解析写入目标,所以对一个兼岗它会把地址盖到**规范那个人**的 HR 档案上 —— 那正是 #3434 里战捷的企业邮箱被换成死者地址的那一步。只挡邮箱不挡这条,洞还开着。三个**互相独立**的信号,由便宜到贵: | 信号 | 代价 | 说明 | |---|---|---| | `registered_alias` | 纯 DB | 这个 userId 已被登记成别人的重复雇佣。(入库侧在行是墓碑时记的别名 + 后来某条路把行复活了 = 真会出现的状态) | | `person_id_external` | 1 次 SF | **权威**。SF 自己的「人」键指向另一个在册的人 ⇒ 这段雇佣是那个人的。不依赖 HR 勾没勾 | | `not_primary_assignment` | 1 次 SF | `EmpJob.customString15` = `2061`,即 HR 的【是否主岗】= 否(#3435 刚定位到这个字段) | **三条设计判据,都写进测试**: ① **第三个信号单向**:picklist 可为空(生产实测有兼岗行的同族字段是 `None`),所以**空值只能读成「没有证据」,绝不能读成「这是主岗」** —— 反过来读就等于把这次的洞原样留着; ② **失败一律 fail-OPEN**:SF 挂了 / 集成没配 ⇒ 无裁决、照常开号。**在这个位置聪明过头是有前科的** —— #191 就是靠「多拦一点」静默吃掉两个真新人; ③ **这个模块不写库**。它拒绝开号,不顺手整理身份 —— 尤其**不记别名**:被它拒的那一行正握着这个 userId 当自己的主键、而且是活的,那正是 `record_hris_user_aliases` 明确拒绝的形状(给活人的主键记别名会让那个人彻底停止同步)。整理身份是入库侧的活(那时行是墓碑或不存在)。下次重新裁决一次 SF 调用,答案永远一样。**这一条是被测试逼出来的**:第一版真去记别名了,两条测试直接红在 `HRIS_USER_ALIAS_REFUSED` 上。 顺带:`person_id_external_is_usable` 从 HR service 挪到这个模块,HR service 改为**委托** —— 这个谓词现在被入库闸和开号闸同时依赖,两份拷贝就是净负债。`EmpJob` 的两处 `$select`(`list_current_jobs` / `get_jobs_for_users`)都加上 `customString15`,注释里互相点名「keep in sync」。 **与入库侧那道闸的一个刻意差异**:入库侧只认**在职 active** 的持有者(离职持有者 + 新 userId 是**再入职**,给它记别名会把再入职的行冻在离职态);开号侧不要求在职 —— 这里的问题只是「这段雇佣是不是别人的」,而给一个离职者的第二段雇佣开邮箱**任何情况下都不对**。两侧的口径差异各自有测试钉着。 **验证**:新增 [`test_duplicate_employment_mint_gate_2026_09_04.py`](../../server/tests/test_google_workspace/test_duplicate_employment_mint_gate_2026_09_04.py)(12 条:三个信号各一条 + 单向性 + 「别的 userId 的旗子不算」+ 真新人不被拦 + pid 指回自己不算重复 + SF 报错 fail-open + 集成没配 fail-open + 非 SF 来源直接跳过 + **回写路径也被挡且 work_email 一个字符没动**);**两轮变异验证**:把裁决短接成恒 `None` ⇒ 4 条转红;只把【是否主岗】信号短接 ⇒ 恰好 2 条转红(证明第三个信号是被独立钉住的,不是搭前两个的便车)。另跑 `tests/test_google_workspace` + `tests/test_hr` + `tests/test_identity` 全量。`ruff check .` 通过;mypy ratchet 1280/1280 未新增;savepoint / alembic / TiDB parity guard 全绿。 > **2026-09-04(同日第五轮)— docs(hris): 【是否主岗】在 OData 上找到了 —— `EmpJob.customString15`,生产双租户 22/22 完美分离(纯文档 / 0 代码 / 0 迁移)** 8/25 兼岗那轮我在 PLATFORM 和测试注释里留了同一句待办:「HR 界面上的【是否主岗】不在 OData 里,**待德国那单兼岗真勾「否」后再探**」。今天 HR 在战捷这单兼岗上补了一句「【是否主岗】也标识为否了的」—— 真样本到手,探完了。 **结论**:该字段是 **`EmpJob.customString15`**,picklist option id **`2059`=Yes(主岗) / `2061`=No(兼岗)**,`$expand=customString15Nav` 取 `externalCode` 可读成 `Yes`/`No`。此前验伪的 `isPrimaryAssignment` / `isPrimary` / `EmpJob.assignmentClass` 确实不存在(400 `COE_PROPERTY_NOT_FOUND`)——**找错的是字段名,不是这个概念不存在**。 **生产双租户全量核过,22/22 无一例外**: | | 行数 | `customString15` | |---|---|---| | 兼岗 | 10(CN `100113`/`80100057`/`58`/`61`/`62`/`63`/`64` + EU `100074`/`100075`/`80100057`) | 全部 `2061` / `No` | | 主岗 | 12(`P0050`/`P01008`/`P01115`/`P01134`/`P01412`/`P0809` × 两租户) | 全部 `2059` / `Yes` | 🔴 **顺带纠一个一直含混的点**:**`customString15`(是否主岗)和 `customString24`(是否推送下游)是两个不同的字段,共用同一个 Yes/No picklist** —— 所以 `2059`/`2061` 这对 id 在两处都会出现。以前笔记里「`customString24=2061` 不推送」讲的是后者;**看到 `2061` 必须先问「哪个字段的 2061」**,否则会把「不是主岗」读成「不推送」。 **没有接进任何闸,这是故意的**:该 picklist 可为空(实测确有兼岗行 `customString24` 为 `None`),所以**空值只能算「没有证据」,不能反推「是主岗」**;判据的权威仍是 `personIdExternal`(它不依赖 HR 有没有勾)。这个字段的价值是一条**不依赖 pid 解析**的独立佐证 —— 接不接、怎么接是下一个决定,不在本轮。 **探法记录下来**(下次找 SF 上「HR 说有、OData 上不知道叫什么」的字段可以照抄):不带 `$select` 地 GET 一行主岗 + 一行兼岗,**逐属性 diff**(EmpJob 有 169 个属性),差异里挑 picklist 形状的候选,再 `$expand=<候选>Nav` 把 option id 翻成 `externalCode`。`$metadata` 那条路走不通 —— 直接 GET `EmpJob/$metadata` 拿到 401(它不吃 client 的鉴权装配)。 **验证**:read-only OData,双租户逐条比对;`docs/architecture/PLATFORM.md` 的 2026-08-25 条目原地更正(原文那句「不在 OData 里」现在是**错的**,已替换),`test_concurrent_employment_no_account_2026_08_25.py` 的「其余全部验伪」清单同步补注。 > **2026-09-04(同日第四轮)— fix(hr): 兼岗第三次开出邮箱 —— 闸没坏,是被一块墓碑挡在了上游(0 迁移 / 0 端点 / 0 cron / 0 新 MCP)** HR 反馈:「我们应该是给战捷换了个新岗位,但是收到了这样一条信息」,附一张「**新员工公司邮箱已创建:jac.ye@pingcap.com**」的卡片。战捷叫 Jie Zhan,`jac.ye` 不是他 —— 那是**另一个人**的地址。 **这是 8/25 品川兼岗那件事的第三集,而上一次我跟 HR 说过「以后不会再触发开号」。** 必须先讲清为什么又有:**上次那道闸今天还真拦住了一次。** SF 双租户镜像同一套组织,所以 HR 加的**一个**兼岗生成了**两个 userId**: | 租户 | 新雇佣 userId | 结果 | |---|---|---| | CN api30 | `80100064` | ✅ 闸正常识别 → 记别名 → 09:40:55,零动作 | | EU api55 | `100075` | ❌ 当成新人:开号 / 发信 / 回写 SF | 差别只有一位数字。`100075` **早就是另一个人的 `hris_person_id`** —— 「jac ye」(`jac.ye@pingcap.com`,巴西联络处),2026-04-30 已 purge;而那条 2026-03-10 bootstrap 行的 `hris_instance_id` **仍是 NULL**。**SF 的 userId 跨 CN/EU 租户不唯一**,按 userId 查人的语句又为兼容遗留行故意放行 `hris_instance_id IS NULL` —— 于是 **EU 的同步认领了这块墓碑**。一旦 `person is not None`,兼岗闸就**整段不可达**:它写在 `_upsert_person` 的 `if person is None:` 里面,只在「这个 userId 从没见过」时才去问一句「这段雇佣是谁的」。今天这个号「见过」,见过的是一个死人。 逃脱有多窄:**品川的 EU 兼岗号是 `100074`,闸 2026-08-25 正常识别并记了别名(生产别名行 13:38:00);战捷的是下一个号。** **后果**(onboard 分支清 `deleted_at` → `revived_soft_deleted_on_onboard_reappearance` → 复活的行**还带着死者的 `work_email`** → Day-1 建号照着这个地址走完了全程):真 Google 邮箱 `jac.ye@pingcap.com` + 一个付费坐席;首登密码信发到**战捷的个人邮箱**;该地址作为 **P01412 的主企业邮箱回写进 SF EU 租户**(`PerEmail` 1046 / isPrimary,个人邮箱被降级);「新员工公司邮箱已创建」卡片发给 HRBP / HR Ops / IT。飞书通讯录本来要建**第二个**账号,被 `residence_country` 缺失那道闸挡住了;其余 9 个下游目标全 no-op。**上次给 HR 的三条结论里有两条这次不成立**:SF 被写脏了,而且我们确实回写了。 **判据一直都对,只是位置错了。**「这个 userId 以前是谁的」永远不是「它现在是谁的」的证据;只有 `personIdExternal` 是,而它当时就写在事件携带的 `EmpEmployment` 行上(`EmpEmployment(personIdExternal='P01412', userId='100075')`)。 **修法**:新原语 `_tombstone_belongs_to_live_person(user_id, employment, *, matched)` + `_claim_tombstoned_user_id(...)`,在 **`_stage_event`(预览)与 `_upsert_person`(应用)双侧**、**按 userId 查到行之后立刻**判一次 —— 命中行是墓碑/非在职 **且** `personIdExternal` 指向**另一个在职 active** 的人 ⇒ 记别名(`concurrent_employment`)+ 跳过事件。双侧都挂,因为 staged 行可能几小时后才被手工确认,而 webhook 路径根本不 stage。**别名是让修复站得住的那一半**:别名短路排在 userId 查人**之前**,以后每一 tick 都直接解析到规范人,不再重新审判墓碑。 **口径刻意收窄,四条零回归**:① 命中行是**健康 active** ⇒ 立即返回、**零 SF 往返**(否则一次 confirm 批就是几百次串行 `EmpEmployment` 调用 —— 这正是 8/25 那轮 `force` 参数存在的理由);② `personIdExternal` **自指** ⇒ 不构成证据、不判(只有全量同步那种「我自己编的」值才带 `force` 去回查);③ 真**再入职** ⇒ `personIdExternal` 指回同一条非 active 行,判定 `None`,复活照旧发生 —— **这条路径闸必须不能吃掉**(#191 当年就是靠「多拦一点」吃掉了两个真新人);④ **只有真墓碑才付得起那次 SF 回查** —— 全量同步刷新的**每一条离职行**都是非 active、都会落进这个谓词,给它们全都回查一次 = 给夜间同步加上约 130 次串行 `EmpEmployment` 调用,而这个形状**一次都没撞过**;live-but-departed 的行只按事件已经免费带来的证据判。新增两个 safe-logging 事件 `HRIS_TOMBSTONE_USERID_CLAIMED` / `HRIS_TOMBSTONE_USERID_UNALIASABLE` —— **两个 code 而不是一个布尔字段**,因为 safe-logging 会把每个字段值哈希掉,「别名到底记上了没有」必须能从 code 本身读出来(`record_hris_user_alias` 会拒绝活人的主键)。 **生产处置**(trace `5bd69afc-f096-4907-ad05-ad0addf57d32`,改动前的完整 pre-image 已存档): | 项 | 处置 | |---|---| | SF EU `PerEmail(P01412,1046)` | 改回 `zhan.jie@pingcap.com` / isPrimary,**读回确认**(CN 租户一直是对的,没被写脏) | | Google `jac.ye@pingcap.com` | **已删除** —— 删前四重断言:地址、`lastLoginTime=1970` 从未登录、已停用、今日创建;删后 `users.get` 404 + 目录搜索为空 | | Google Workspace 坐席 | revoked(`active_unique_key` 是生成列,`set NULL` 会被 TiDB 3105 拒 —— 交给 `status` 驱动) | | 墓碑行 | 复原为 jac ye 并重新 tombstone,战捷的 20+ 个字段全部清出 | | `100075` | 记成 P01412 的 `concurrent_employment` 别名 | | 今日新建的 google external identity / 部门归属 / 入职流程 / 岗变复核包 | 删除 / tombstone / 删除 / `superseded` | | **blocked 的飞书 sync state** | 删除 —— 它会**重试建号**,是这批里唯一还在往前跑的东西 | **残留地雷已排**:同形状(`hris_instance_id IS NULL` + 数字号段 + 已 tombstone)的行全库共 3 条 —— `100059`(ye Kris)、`100084`(磊 张)和 `100075` 自己 —— 全部钉到 CN 主实例,任一租户的 userId 都再也认领不到它们。剩下 4 条 NULL 行是 gaiaworks 的 `ECadmin*` 系统账号,SF 不可能发出这种 userId,不构成风险。 **HR 侧无需任何改动**:HR 确认本意就是「多一个岗位」(兼岗),SF 里的数据本来就是对的 —— 一人一行的既有边界下,Helix 只跟规范那段雇佣,新岗位的头衔/部门不进黄金记录(这是 2026-08-18 记录在案的已知边界,非本轮范围)。 **验证**:新增 [`test_tombstone_userid_collision_2026_09_04.py`](../../server/tests/test_hr/test_tombstone_userid_collision_2026_09_04.py)(9 条,含照抄生产 `EmpEmployment` / `User` 的复现,以及「墓碑保持深埋、名字不被改写、`employee_no` 不被占用、NULL 租户不被认领」四条分别断言);**变异验证**:把 `_claim_tombstoned_user_id` 短接成 `return False` ⇒ 3 条行为断言转红,恢复后 9 条全绿。另跑 `tests/test_hr` + `tests/test_identity` 全量(942 条)确认无回归 —— 首轮混跑时本文件里有 1 条转红,是**这条测试自己的 fixture 太脆**(把一个已 flush 的 active 行改成 `left`,把整条 leaver 监听链拖进一个只测谓词的用例),改成直接 seed 成 `left` 后消失;不是被测代码的问题。 > **2026-09-04(同日第三轮)— feat(cloud): 待审批申请等页面补上「哪个云 / 状态」筛选;`finance` 拿到整个云域的只读权限(0 迁移 / 0 新端点 / 0 cron / 0 新 MCP)** 两件事,同一片页面。 **一、少筛选的几个页面** 「云子账号 / 订阅」的 **待审批申请** tab 只有一个「状态」下拉 —— 想问「哪些 AWS 的申请还没批」只能一页页翻,而**紧挨着的「订阅列表」tab 一直有云厂商筛选**。现在这个 tab 补上 **搜索(名字 / 说明)+ 云厂商(多选)+ 状态 + 清空筛选**;后端 `GET /cmdb/scope-requests` 新增 `provider`(重复键 = OR)与 `search`(name/description 的 ilike)两个参数。顺着同一个页面往下看,**已下线** tab 也只有一个搜索框,每行都渲染着云厂商标签却没法按它筛 —— 同样补上云厂商多选。 三处云厂商选项此前是三份各自内联的数组(订阅列表有 7 个厂商,另两个 tab 一个都没有),抽成 [`providerFilterOptions.ts`](../../web/src/pages/cloud/providerFilterOptions.ts) 一处导出。 另外两处**列里有、筛选里没有**的:**负载均衡**页(后端 `owner_person_id` 参数早就在,前端从没接)和**对象存储**页(migration 366 给 bucket 加了 owner,列表和抽屉都在用,但端点从来不收 owner 筛选)。负载均衡加「按负责人筛选」;对象存储加「按负责人筛选」+「无负责人」(后者才是真正要问的那个问题 —— 一个 public-read 的桶没人负责),后端 `GET /cmdb/object-storage` 相应新增 `owner_person_id` / `unowned`。两个筛选在 UI 上互斥(选一个清掉另一个),因为后端是 AND,同时成立不可能。 **二、`finance` 的云域只读权限** 用户原话:「让财务的角色也有云这个里面所有的只读的权限 都给财务」。财务视角侧栏里云这块此前只有一个「云资产总览」,而总览回答不了「这笔账挂在什么资源上」。 **先查后改的结论是:后端读闸早就放行 finance** —— `can_read_cloud` 与 `can_view_cloud_resources` 的名单里都写着 `FINANCE_ROLE`。挡住财务的是 `App.tsx` 里那条 `RoleRoute roles={['global_admin','cloud_admin']}`,**403 发生在前端路由,不在 API**。所以改动几乎全在前端:路由把只读面整体放开(云服务器 / 域名 / 证书 / DNS / CDN / 负载均衡 / 对象存储 / IAM 用户含离职残留 tab / 子账号·订阅含待审批+已下线 / 网络总览 / 专线),侧栏**直接复用 admin 菜单的同一个 group 对象**(新的 `withoutChildKeys` 辅助),所以以后往云资产加页面财务自动跟上,两份菜单不会漂。 **三个页面明确不给**:回收站 / 角色目录 / 阿里云百炼(另加 API Key 管理)。判据不是「感觉敏感」,而是**它们的 READ 端点本身就是 `can_manage_cloud`** —— 放个菜单入口只会得到一个首屏就 403 的页面。放宽那三个后端闸是另一个决定,本轮没被要求。 **写操作一处没放**,并且顺手补上了四处**此前只看页面/模式、不看角色**就渲染写按钮的地方:`CloudScopesPage` 的 立即同步 / 下线、`CloudScopeRequestsPage` 的 审批 / 驳回 / 手动开通(原条件是 `mode === 'admin'` —— mode 只说「这是谁的队列」,不说「你能不能批」)、`CloudIamUsersPage` 的 改绑负责人 / 清理、`LeaverResiduePanel` 的 忽略 / 重新扫描。IAM 的「人/机」分类控件保留可见但置灰:当前分类是财务想看的信息,而一个没有选中值的 Segmented 会读成「未分类」—— 那是个错答案,不是隐藏。 **验证**:① 新增 [`test_finance_cloud_read_parity_2026_09_04.py`](../../server/tests/test_cmdb/test_finance_cloud_read_parity_2026_09_04.py) —— 带 `X-View-Role: finance`(**必须带**:不带的话 fixture 用户还挂着 `employee`,好几个读会因为错误的原因通过)逐个打 **13 个读端点断言 200**、对 **2 个 admin-only 读断言 403**、并断言**一次写被拒**;16 条全绿,也就是说「后端早就放行」这句话是量出来的不是读出来的。② 新增 [`test_scope_request_list_filters_2026_09_04.py`](../../server/tests/test_cmdb/test_scope_request_list_filters_2026_09_04.py)(5 条)与 [`test_object_storage_owner_filter_2026_09_04.py`](../../server/tests/test_cmdb/test_object_storage_owner_filter_2026_09_04.py)(3 条),**都做过变异验证**:把 provider/search 的 where 摘掉 → 3 条红;把 OSS 的 owner/unowned 摘掉 → 2 条红。③ `CloudScopeRequestsPage.test.tsx` 补 3 条(财务视角看得见行、看不见任何决策按钮 / 搜索词进到 listing / 没选时不发空串),**变异验证**:把闸改回 `mode === 'admin'` → 财务那条红。④ 前端 `pnpm typecheck` + `pnpm lint` + `pnpm test`(105 files / 1389 tests)全绿。⑤ **浏览器实测**(本地 dev 临时给账号加 `finance` 角色、验完已删除):财务视角侧栏出现「云资产 / 网络资产」两组,云资产下正好是 云资产总览 / 云资源目录 / IAM 用户 / 子账号·权限 四项(回收站、角色目录、百炼、API Key 已被过滤掉);待审批申请与已下线两个 tab 的新筛选栏、对象存储与负载均衡的负责人筛选均渲染正常。 **顺带**:`cloud.common.filterByOwner` 的日文是「按担当者フィルター」(混了个简体「按」),改成「担当者で絞り込み」。 > **2026-09-04(同日第二轮)— fix(identity-sync): 汇联易 Budget Owner 改为「所属一级 BG 的负责人」;顺带修好部门负责人推导的一个结构性盲区(0 迁移 / 0 端点 / 0 cron / 0 新 MCP)** 早上那轮把 6102 从 SF 2447(调薪负责人)改成「部门自身负责人」后,财务复看第二个部门仍不对:`Product` 推成 **P0001 刘奇**,应是 **P01120 Liya Du**。 **根因是一条护栏,不是回落链**:负责人推导要求「上级在部门外 **+ 至少管着本部门 1 个成员**」。**Product 节点上只有 Liya Du 一个人,她的 8 个直属下属全在子部门**(Core Components / AI Lab / TiDB X Core Product / …),于是她在本节点内计数为 0 → 该部门被判「扁平无负责人」→ 6103 从来没推过 → Budget Owner 一路回落到她的上级 CEO。**同一形状还有 HR**(唐小丽独占 HR 节点,8 个下属分布在 HR Operations / HRBP / C&B / Talent Acquisition)**、APAC Business Group、Central Enabling Group、EMEA Business Group** —— 这也顺带解释了为什么汇联易上这几个 BG 的「部门负责人」是空的:Helix 从没推过,北森时代也没填。BG 节点几乎都是这个形状。 **两处改动**: 1. **`_leader_emp_no` 的下属计数改按子树统计**(候选人仍限本部门直属成员)。**叶子部门子树==自身,构造上不受影响**;生产灰度:能推出负责人的部门 **61 → 66**(96 个中),**没有任何一个既有结论发生变化**。副作用是正面的 —— 6103 从此会推给 HR / APAC BG / Central Enabling Group(原本空白),并把 EMEA BG 从 Ben Yang 纠正为 Lijia Xu(HR 确认后者对)。 2. **`_budget_owner_emp_no` = 该部门所属一级 BG 的负责人**(`_bg_code` 上溯到 parent 为空那个节点);BG 内部完全没有管理关系时回落到「BG 子树成员的部门外经理众数」(`AI Innovation` 8 人里 7 人挂刘奇、`Strategic Consultant` 2 人全挂刘奇 → 刘奇 P0001,HR 确认)。 **这条规则推翻了今早那轮**:`Intelligent Support Enablement` 会从部门负责人 **朱明 P0809** 变成 Engineering Group 的 **Mark Xu P0346** —— 朱明是三级部门负责人,不是 BG 负责人。财务明确接受。 **验证**:① 生产只读灰度(pymysql 直连 TiDB + 进后端容器只读调汇联易 `GET /api/open/department/{custDeptNumber}` 拿 `departmentPositionDTOList`,**注意要经 `huilianyi_dept_code_map` 把 SF 码翻成厂商码,直接用 SF 码一律 120103 部门不存在**):14 个 BG 的派生负责人与 HR 逐个确认的名单 **6/6 命中**,91 个有在职成员的部门 **全部解析出 Budget Owner(0 无解)**,取值收敛到 **12 个人**(Mark Xu×30、唐刘×14、Ben Yang×8、Liya Du×7 …);预测 **74 个部门 6102 变更、4 个部门 6103 变更**。② 测试文件按新语义重写并改名为 [`test_huilianyi_budget_owner_is_bg_head_2026_09_04.py`](../server/tests/test_identity_sync/test_huilianyi_budget_owner_is_bg_head_2026_09_04.py)(5 条:整条分支共享 BG 负责人 / 不等于部门自身负责人 / 永不取 2447 持有人 / **下属全在子部门时 BG 负责人仍能解出** / BG 无内部管理关系时回落到外部经理)。**做过变异验证**:子树计数改回本部门计数 → 3 条红;`_bg_code` 改成用部门自身 → 3 条红。③ `pytest tests/test_identity_sync tests/test_identity` 全绿,ruff clean,mypy 改动区间 0 error。 > **2026-09-04 — fix(identity-sync): 汇联易 Budget Owner 推的是 SF「调薪负责人」—— 一个 BU 级薪酬审批人被当成了部门预算负责人(0 迁移 / 0 端点 / 0 cron / 0 新 MCP)** 财务报:`Intelligent Support Enablement` 的 Budget Owner 显示 **P0619 Yu Dong**,应是部门负责人 **P0809 朱明**。 **代码没坏,是字段语义映射错了。** 链路三跳:SF `EmpJobRelationships` relationshipType **2447(调薪负责人)** → `identity_persons.hris_budget_owner_person_id` → `_huilianyi_dept_attributes` 取部门**直属在职成员**的众数 → 作为 `departmentPositionList` 的 **positionCode 6102** 推给汇联易。生产只读查证:该部门 5 名在职成员**含朱明本人在内全部**指向 Yu Dong(5:0),所以众数**永远**到不了部门负责人。 **2447 根本不是部门维度的字段**:它是按 BU 挂的**薪酬调整审批人**。全司 91 个有在职成员的部门只解析出 **23 个不同的人**(Mark Xu 盖 15 个部门、Yu Dong 13 个、唐刘 8 个);**49/91** 推的 Budget Owner 不是该部门自己的负责人(连 IT Services & Security 也是:负责人=冯帅 P0989,推的是倪捷 P0843)。2026-06 建这条链路时把 2447 的中文标签直译作 "Budget Owner" 就把两个概念等同了 —— 2026-07-14 那次复审只审了取数**范围**(直属 vs 子树),没审取数**字段**。 **修复**:`_budget_owner_emp_no` 改为派生自**部门自身的组织负责人**(与 6103 同一套派生),取不到时依次回落 ① 成员的**部门外经理**(众数 + 工号确定性 tie-break,且必须是本目标会推的在职 P 号人)② **最近有负责人的祖先部门**。两级回落不是可选项:推送对未解析角色是**省略**而非置空(汇联易保留原值),而生产 91 个部门里 **30 个是扁平队**算不出自己的负责人 —— 解析成 None 就是把它们**永久冻结在现在的错值上**。只上溯祖先能覆盖 16 个、剩 14 个仍 None;加上外部经理这级后 **91/91 全部解析出人**。两级都能解析的 16 个里 13 个一致,3 个不一致时经理更精确(Accounting → 其 controller Eric Chen 而非 CFO)。 `hris_budget_owner_person_id` 列**不动** —— SF 同步照写、用户详情页「HR 关系」卡片照读,只是不再喂这个厂商角色。 **验证**:生产只读灰度(pymysql 同步引擎直连 TiDB,不写任何一行)—— 91 个部门 **65 变更 / 26 不变 / 0 无解**,上报部门变为 **P0809 朱明**。新增 [`test_huilianyi_budget_owner_is_dept_head_2026_09_04.py`](../server/tests/test_identity_sync/test_huilianyi_budget_owner_is_dept_head_2026_09_04.py) 四条(叶子部门取自己的负责人而非 2447 持有人 / 6102 与 6103 同号 / 扁平队回落 / **经理优先于祖先负责人**),并把 `test_huilianyi_hrbp_subtree.py` 里那条**把旧 bug 编码成期望**的 `test_budget_owner_stays_direct_member_based` 改写成反向闸。**做过变异验证**:把派生换回 2447 众数 → 4 条断言全红;把经理回落那级摘掉 → 优先级那条单红。`pytest tests/test_identity_sync` 872 passed,ruff clean,mypy 在改动区间 0 error。 > **2026-09-04 — fix(assistant): 飞书 IT Agent —— 点一下「转人工」，刚读到的回答就没了（0 迁移 / 0 端点 / 0 cron / 0 新 MCP）** 员工问「请问我的电脑设备用了多久了」，拿到一张有依据的回答卡，点了卡上的 **转人工** —— 回答消失了。往回滚，聊天里只剩 「⏳ 正在提交」、一张 「新求助工单」、一张 「已转人工处理」，**那条回答和它的「参考文档」链接一个字都不在**。 **机制**：飞书把卡片回调返回的内容**当成新卡片渲染**，也就是说每一个终态分支返回什么，员工原来读的那张卡就变成什么。评分那两个按钮从第一天起就是对的（`answer_card.rated_card` 会把回答连同 sources 一起重画，migration 518 那条注释写的就是这件事）；**转人工分支返回的是一张全新的两行卡**，于是把回答顶掉了。而且它慢——建单要向每一个 IT 管理员做飞书 + SMTP 扇出——所以 2.2 秒的预算基本必然超时，超时那条路返回的**通用 `_working_card` 也是一张全新卡**，先把回答顶掉一次。**两条路径，同一个缺陷。** **修复**（`answer_card.py` / `card_actions.py`）： - 新增 `answer_card.settled_card(reply, note=…)` —— 回答 + 参考文档原样保留、按钮花掉、底部加一行「发生了什么」。转人工的**成功 / 建单中 / 撞上去重锁 / 失败**四条路全部走它，回答再也不会被顶掉；失败那条尤其重要——原来一次瞬时故障同时拿走了转人工**和**员工正在读的回答。 - `_Handoff` 多带一个 `in_flight`：分支在**开始慢活之前**把「此刻该留在卡位上的那张卡」交给请求侧，于是超时那条路返回的也是**带回答的卡**，而不是通用的正在处理卡。 - 工单号这种「值得回头翻」的回执，在超时路径上**单独发一条消息**（新增内部 `FOLLOWUP_KEY`）。原来 `_deliver_followup` 直接把分支的卡当消息发——现在那张卡就是整条回答，照发会把回答再贴一遍。 - 顺带三条：① 通用 `_working_card` 的文案写的是「已收到你的**确认**，正在提交」，但这张卡是**每一个**慢按钮都会撞上的（转人工、评分），对一次转人工点击说「你的确认」是在描述员工没做过的事，改成「已收到你的点击，正在处理」；② 飞书会**重投**它判为慢的回调，第二次撞上工单去重锁抛 `SUPPORT_TICKET_IN_FLIGHT`，原来被兜底 handler 报成 「没能提交」——**给一张正在建的单**，员工于是再点一次或干脆手工提；现在按 code 单独识别，说「正在建单，请勿重复点击」；③ 确认提交那张回执原来只有「✅ 已提交」，把**「将要提交的内容」那几行参数顶掉了**——聊天里于是留下「提交过」但没有「提交了什么」，现在回执（和超时的正在处理卡）都把参数行带上。 **另一条同一张截图里的问题**（`support/service.py`）：`_notify_it` 一直支持 `exclude_id`，唯独 `create` 没传。于是**身兼 global_admin 的员工自己提的单，会在自己的会话里收到一张「孟凡生 提交了一条求助」+「处理工单」按钮的卡** —— 平台把他刚提交、正在等回执的活儿原样甩回给他。其余管理员照收，只去掉自指的那一份。 **验证**：新增 `tests/test_assistant/test_card_history_2026_09_04.py`（8 条：快/慢两条路径都断言回答与 sources 仍在、follow-up 是回执不是回答副本、撞锁不算失败、失败仍留回答且它的 follow-up 也不是回答副本、确认回执带参数行）与 `tests/test_support/test_self_filed_ticket_fanout_2026_09_04.py`（2 条：自己不收到 + 第二个管理员照收，后者是对照组，防止「排除了所有人」也能过）。**做过 5 处变异验证**（把回执改回旧的 `_closing_card` / 删掉 `handoff.in_flight` / follow-up 不读 `FOLLOWUP_KEY` / 失败分支不带 `FOLLOWUP_KEY` / 拿掉 `exclude_id`），每一处都精确打红对应的那条。写这批测试时抓到修复自身的一个缺陷：新的 `except AppException` 分支先 `rollback` 再 `logger.info(person.id)` —— 回滚让实例过期，日志调用自己抛 `MissingGreenlet`，把一个已处理的失败变成未处理的。`tests/test_assistant` 567 passed / 4 skipped，`tests/test_support` 74 passed。 > **2026-09-04 — fix(tests): 两条「单跑绿、混跑红」的路由清单闸 —— 一个探针路由挂上去就没下来过(0 迁移 / 0 端点 / 0 cron / 0 新 MCP)** `test_knowledge_loop` 和 `test_partner_directory` 的 `test_the_endpoint_list_matches_the_router` 单跑全绿、全量必红。**症状不是断言不相等,是 `app.openapi()` 直接抛 `PydanticUserError`。** **根因是两件事叠在一起,单独任何一件都不会出事。** ① `tests/test_identity_consumers/test_consumer_auth.py::test_scope_denied_403` 往进程全局的 `app.main:app` 上挂了一个探针路由,`finally` 里按 `.path` 过滤 `app.router.routes` 拆它。**这个拆法在 FastAPI 0.141 上是空转**:`include_router` 不再把子路由拷到父级,而是 append 一个**没有 `.path`** 的延迟包装 `_IncludedRouter` —— 过滤器把它原样留下,探针从此挂到会话结束。(同一个仓里 `open_meta_router._curated_spec` 的注释早就记下了这个行为的另一面:「按 `.path` 过滤 `app.routes` 会静默产出空 spec」;`tests/test_bounty/test_admin_route_gate_sweep.py` 里那份同款拆法**也一直在漏**,只是它的探针无害。) ② 那个探针的签名是 `request: Request`,而 `Request` 是在**测试函数体内**导入的。测试模块一律 `from __future__ import annotations`,注解按**模块** globals 解析 —— 于是 `"Request"` 是一个解不开的 forward ref,FastAPI 把它当成请求体字段,`app.openapi()` 从此对**任何**调用者抛异常。 于是全量跑里:`test_assistant_eval` 的同款闸排在 `test_identity_consumers` **之前**,所以它一直是绿的;`knowledge_loop` / `partner_directory` 排在之后,双红。三条闸里只有两条红,这个「为什么不是全红」正是定位它的线索。 **修复**:新增 [`tests/support/router_probe.py`](../server/tests/support/router_probe.py) 的 `mounted_router` 上下文管理器 —— **恢复列表本身**(`app.router.routes[:] = saved`)而不是去匹配列表内容,并在**进出两侧**都清 `app.openapi_schema`(`app.openapi()` 只在 `app.router._get_routes_version()` 变化时重建,而那个版本号是个**和**,挂上再摘下会回到原值,靠它自动失效是巧合不是保证)。两个挂探针的测试都改用它;`test_scope_denied_403` 顺手删掉那个用不到的 `request` 形参、把 `ConsumerContext` / `require_consumer` 提到模块级导入。 **回归闸两道**:`tests/conftest.py` 加一条 autouse fixture,任何测试改了共享 app 的路由表而没放回去就直接报错(比对的是 id 列表,~150 次 `id()`,并在报错文案里点名正确的挂法);外加 [`tests/test_core/test_probe_router_teardown_2026_09_04.py`](../server/tests/test_core/test_probe_router_teardown_2026_09_04.py) 三条,分别钉住「`.path` 过滤确实拆不掉」(将来 FastAPI 改回去了这条会红,提示这段告警已过时)、「`mounted_router` 恢复得了路由表」、「带坏注解的探针摘掉后 `app.openapi()` 能恢复」。 **验证**:先在 24 秒内把 80 分钟的全量失败复现成 5 个文件的最小组合,再逐文件二分到唯一元凶 `test_scope_denied_403`。**做过变异验证**:把 `mounted_router` 的 teardown 换回按 `.path` 过滤 —— autouse 闸对元凶本身报错、三条回归里两条红、原症状(`test_knowledge_loop` 那条)同时复现;改回后 30 passed。全量后端复跑通过。 > **2026-09-04 — fix(security-awareness): 安全宣贯的深链在手机上一直落回首页 —— 以及那道**本该拦住它、也确实红了**的闸(0 迁移 / 0 cron / 0 新 MCP)** 第一张活动卡片发出去,在手机上点开,落到的是**首页**,不是素材页。 **直接原因**:活动卡片和催办阶梯都发 `/me/security-learning/`,而 `mobileDeepLink.ts` 里**没有这条规则**。`FeishuMobileGuard` 的行为是明确的:映射不到就 `stashPostLoginRedirect` + `` —— 也就是首页。用户猜是「登录方式的问题」,很接近但不是:SSO 那一跳是**没有映射之后走的那条路径**,不是原因。 🔴 **真正该记住的是第二件事:仓库里那道闸本来就是为这个而存在的,而且它在 main 上是红的。** `server/tests/test_mobile/test_deep_link_contract.py` 会扫描后端所有对外发出的路径字面量,没有登记进 `contracts/mobile-deep-links.json` 的一律失败。它当时就报了 `/me/security-learning/:id`。**没拦住的原因是:后端测试不在 CI 里跑(go-ci 只跑前端),而我在那五个 PR 的验证里只跑了目标子集 —— `test_security_awareness` / `test_auditor` / `test_arcade` / `test_alembic` / `test_notifications` / `test_mcp` —— 从没跑过 `tests/test_mobile`。** 一道没人运行的闸等于没有闸。**教训:在一个后端不进 CI 的仓库里,「跑相关的那几个目录」不是验证,合并前至少要跑一次全量后端。** 🔴 **而且那道闸只看见了一半。** 它报的是 `reminders.py`(f-string 形态),**完全没看见活动卡片** —— 也就是用户真正点的那一条。`campaign_service.py` 里写的是 `MATERIAL_ROUTE.format(material_id=...)` 赋给局部变量再传 `url=`,而 `_literal_paths` 只认字面量、f-string、三元、和模块级常量名,**不认 `.format()` 调用**。补上这一形态之后,立刻又浮出**三条别的域一直在发、从来没被分类过**的深链:`/admin/approval-flows?q=:id`(approval_registry)、`/admin/systems?q=:id`(system_registry)、`/bounty?report=:id`(bounty)。三条都按各自兄弟路径已有的判断登记为 `desktopOnly`。**一个扫描器漏掉的形态,漏掉的从来不止你正在查的那一条。** **修复**:`mobileDeepLink.ts` 加映射规则(带 `safeIdSegment` 防护,坏 id 落到资料库而不是拼出一个越界路径),契约登记 `/me/security-learning` 与 `/me/security-learning/:id` 两条,扫描器补 `.format()` 形态,并给这条链路补了 4 条单测(含绝对 URL 与坏 id 两种形态)——**做过变异验证**:把映射规则改成永不匹配,4 条全红。 **验证**:`tests/test_mobile` 53 passed;前端 `typecheck` / `lint`(13 道闸)/ `test`(1334)/ `build` 全过。 > **2026-09-04 — fix(ai-labs): 复审第三、四轮 —— 每一轮都在上一轮的修复里找出缺陷,最狠的一条是「替换错了一行」(0 迁移 / 0 新端点 / 0 新 MCP → hint 仍 591)** 接着 09-03 那轮往下做的两轮。**这两轮找到的全部缺陷都在前一轮的修复里**,没有一条在原始功能里 —— 这正是这个循环存在的理由,也是它开始收敛的信号。 **第三轮:上一轮那条「不再转达厂商正文」的修复,自己替换错了一行。** 三个调用点里的第三个,把 `f"Bailian LLM HTTP {status}: "` 当成待替换的那行删了,`resp.text[:400]` 留在原地 —— 于是**泄漏照旧在,反而把运维要的状态码删了**。这是 `_call`,`chat_json`/`chat_text` 背后那条路,**23 个模块**在用。现场实测两条路都不再含提示词片段、都含状态码。embeddings 那条同形态的也修了。 同轮其余:`visibleMessages` 的阈值反方向错一格(`>= baseCount+2` 把问题渲染了两遍,而 `baseCount` 还会过期);keeper 在心跳**报错**时判租约已丢,导致一次 DB 抖动删掉已付费作品;同步重复付费的孪生路径还开着;「已取消但已计费」上轮**只写在 commit message 里没有代码**;`_discard_artifacts` 会删掉赢家的对象;上传凭证 10 分钟过期而 AI 实验室是选文件时上传、发送时认领。 **第四轮:第三轮那条「记下已取消的花费」在它为之而写的那条路上崩溃。** `_run_async` 会返回 `None`(「还在跑,但已不是我的了」),而 `keeper.lost` 和这个 `None` 由**同一个条件**触发、被两个观察者分别发现、彼此没有顺序。于是新加的 `payload.get(...)` 在 keeper 赢下这场竞态时抛 `AttributeError` —— 被外层吞掉,那条它为之而写的用量行一次都没写成,付过钱的作品也泄漏了。**mypy 早就报了这个类型洞,而 mypy 不在任何 CI workflow 里**(本轮顺手跑了 `check_mypy_baseline.py`,发现本分支引入 5 条新错,已全部按仓内既有写法修掉,ratchet 回到基线 1280)。 同轮还发现同一个改动**同时立了两条互相矛盾的规矩**:`keeper.lost` 那条记用量,`_finish` 落不了地那条不记 —— 同一个真实事件按「哪个观察者先发现」得出两种结果,而一次比心跳间隔更短的同步渲染(绝大多数图片)恰好总由 `_finish` 发现,所以**那个缺陷改完之后依然存在**。现在判据只有一句:**这一次跑有没有产生厂商费用**。同步每跑一次必然花钱;异步只在提交那次花钱,接手方重轮询不花钱、也就不记。两条测试原来断言相反的事,现在一条断言收费必记、一条断言重轮询不记。 其余:孤儿清理只看 `created_at` 不看 `expires_at`(在 4 小时凭证 + 1 小时保留期下会把员工还能用的附件删掉);聊天页在「凭证再也认领不了」时把附件还给员工(工坊在同一个 commit 里是清掉 + 提示,两个面朝相反方向);`onLoadedData` 在 `preload="metadata"` 下永不触发,于是重签预算再也不归零;作品库那个「改成纯 updater」的修复引入了丢失更新;展示名清洗器按枚举去控制符,漏了 U+00AD / U+2060 / U+FFF9-FFFB,改成按 Unicode `Cf` 类别去;`visibleMessages` 的 pre-meta 兜底只看末行,而失败的轮次末行是 assistant 行 —— 失败路径上照旧画两遍。 **DECISIONS.md 里那条 09-03 的决定②已订正**:它写下的两句(心跳失败即判丢、终态写入失败一律 `_release_for_retry`)被这两轮各推翻一句,而 CLAUDE.md 让下一个 agent 拿 DECISIONS 当已批准的授权 —— 不订正就等于给下一个人一张改回来的许可。 **第五轮:第四轮那条判据换出了一个更大的漏账。**「记不记用量看这一次跑有没有花钱」这个判据是对的,但它被实现成**在函数入口算出的布尔量,而记账发生在终态** —— 两者不是同一时刻,提前离开的路径压根到不了那一行。异步 runner 提交(已付费)后丢掉租约,是从 `payload is None` 返回的;接手的 reaper 看到已有 task id 判定「不是我付的」也不记。于是**每一个换过手的异步生成 —— 包括任何一次重启打断渲染后由 reaper 恢复的,而这正是 reaper 存在的用途 —— 都是员工拿到了片子而用量表一行都没有**:管理台看不到花费、成本归不到人、视频配额一秒没扣。第四轮自己新加的测试断言 `counters == []`,把它钉成了期望。现在改成**钱在哪一刻花掉就在那一刻记**(`_note_charge` 由接受工作的那个调用原地触发),终态只补产出、永不再加第二个 `requests`;测试改成把两次 `run_job` 串起来跑 —— **只跑单次 `run_job` 的测试永远看不见这条**。 同轮另外两条前端阻塞:作品库那个 `setPage` 仍从闭包读 `total`(注释却写着两个更新互不越界)—— 同一帧内两次删除会让分页控件卸载而页码停在越界值,员工看到空画面、没有任何控件回到还剩的作品;`visibleMessages` 的 pre-meta 兜底改成回扫两行后,会匹配到**上一轮**的问题 —— 员工重发一句相同的话(「再来一张」、或重试刚失败的提示词)就整轮不渲染:没有气泡、没有 spinner、没有报错。两条都改掉了:分页改成**派生**而不是存一份。而 pre-meta 兜底那条,第五轮先改回「只看末行」并在注释里断言「失败轮次到不了这里」—— **这句话是错的**,第六轮自己抓出来了:流在 `meta` 帧那一刻被关掉会持久化一条 `AI_LABS_INTERRUPTED` 的 assistant 行,而客户端从没拿到 id,于是末行是错误行、问题被画两遍。而这个状态和「员工重发一句相同的话」在文本上**无法区分**,却需要相反的渲染 —— 所以第六轮不再猜:改成按**客户端自己生成的 `client_token`** 匹配(它本来就发给了服务端、服务端本来就存了),从发送那一刻起就是确定的身份,文本启发式整条删掉。 283 passed(deploy + storage ACL + ai_labs);前端 27 条 `visibleMessages` + 全量 vitest 全绿;六个后端守卫脚本全过(含此前一直没跑过的 mypy ratchet)。变异验证累计 23 处。迁移链在**全新数据库**上从零跑通 591 条到 head=601,`client_token` 与两个唯一键都在,`deleted_at` 一列都没有(硬删承诺是结构性的),601 的降级/重建来回两次幂等。厂商侧实测:两轮真流式对话 + 一次真图片生成经重构后的逐跳下载路径取回 1 MB PNG。 > **2026-09-03 — fix(ai-labs): 整功能复审 33 处 —— 三处会重复付钱给厂商,一处把员工的文件名写进全公司可读的审计行(0 迁移 / 0 新端点 / 0 新 MCP → hint 仍 591)** AI 实验室四个 PR 合完之后按要求做的**整体复审**:四个独立视角(平台规矩、后端 正确性、安全、前端逻辑与诚实性)各自读了一遍全部新增代码,共 33 处。都修了, 每一类都带回归测试,最狠的三条做了变异验证。 **会重复付钱的三条**(都只在慢路径或竞态里出现,平时看不见) ① **同步生成没有心跳。** `_run_sync` 就是一个长 await;超过 180s 租约后行变成 可抢,reaper 抢走并**再提交一次**。新增 `_LeaseKeeper`(自己的 session, LEASE/3 一跳),顺带盖住了异步任务成功后下载几十 MB 视频的那一段。 ② **`usage.record` 无视 `_finish` 的返回值。** 租约已易主时终态写入落不了地, 但计数照记 —— 一次厂商调用被计两次、员工配额扣两次。 ③ **一次 `/turns` 重试就是第二个 turn。** `uq_alm_conv_seq` 只挡并发;顺序重试 读到新的 `message_count`、算出下一个 seq、被接受。`client_token` 的列和唯一键 在迁移里**本来就有**,ORM 和 wire 两侧都没接上 —— 一个只存在于迁移文件里的 幂等保护。接上后重放返回 409 `AI_LABS_TURN_ALREADY_SENT`。 **会丢内容 / 泄露内容的** - **断流丢答案。** 按停止 / 关标签页 / 断网时生成器在 yield 处被取消,成功和 失败两条路都走不到:已经读到的回答没了、厂商已计费的 token 没记、`seq` 留一个 永久空洞(问题在调厂商之前就 commit 了)。`finally` + 分离任务补齐,并把 `meta` 帧也挪进 guard —— 「厂商还没回话就关掉」恰恰是最常见的断点,第一版 修复漏掉了它,是新写的那条空产出测试逼出来的。 - 🔴 **员工的文件名进了全公司可读的审计行。** 对象键格式是 `{purpose}/{date}/{person}/{rand}-{文件名}`,而键被抄进 `storage_upload_grants` 和 `storage.upload.authorize` 审计行(`/audit/logs` + CSV 导出都读得到), 还能活过员工自己的硬删。`离职谈话录音.m4a` 是内容,不是元数据。三个 `ai_labs_*` purpose 的键改成**不透明名**(只留扩展名);展示名随请求走、只存在 员工自己的消息行上。这是根因修法 —— 按角色过滤读者改不了「键已经被抄进三个 地方」。 - **提示词留在 `core_idempotency_records` 里过完 24h TTL**(那张表在本域之外, 硬删碰不到):`/generations` 和新加幂等的 `/translate` 都声明了 `redact_cached`。 - **厂商错误正文原样转达给员工。** 厂商拒绝时常把出问题的输入引回来 —— 逐字转达等于把提示词片段写进 `error_message` 再渲染出来,正好是承诺没人看的 那个界面;而且是三语界面里的英文开发文案。短码保留,正文进日志。 - **`fetch_result` 的 https 校验只覆盖第一跳**(`follow_redirects=True`): 302 到 `http://` 或内网地址就由服务端无检查地取。改成手动逐跳校验、跳数有界。 - **移动端用手册渲染器渲染模型回答**,而它会实例化 ```live-```(真的 Helix 数据组件)和 ```mermaid```(2.3 MB 分片)。模型输出是不可信文本, 而一个 fence 可以由员工附上的文档诱导出来。改成和桌面端同一个纯渲染器。 **说了假话的** - **桌面端从第二轮起每一轮都渲染两遍。** 轮次结束后父组件重读会话,同一问答 作为真实行回来,而 live 副本没清 —— 两份并排。第一轮看不出来只因为服务端 只设置一次标题,恰好触发了那个清理 effect。规则抽成纯函数 `visibleMessages` 并按数据派生(不是在 effect 里清),顺带修掉另一个:那个 reset effect 依赖 标题,所以一次普通重读会执行整套 reset —— 包含 `abort()`,把正在流的新消息 杀掉且不报错。 - **审计。** PLATFORM.md 说审计记「谁 / 何时 / 哪个模型」,而对话轮次一行都没记。 补了 `ai_labs.chat.turn` / `ai_labs.translate` / `ai_labs.generation.cancel`, 并有测试断言提示词不在 detail 里。 - **UI 说的上限不是被执行的上限。** 目录发布一个 `attachment_bytes`(20 MB, 文档的那个)给三个 presign 分别按 10 / 20 / 15 MB 收的 purpose:附一张 12 MB 照片,客户端放行、presign 413、员工上一句刚被告知 20 MB 没问题。改成按 purpose 发布,加契约测试锁住两侧一致;生成工坊那边**根本没有尺寸检查**,也补上。 - **转写页那个提示词框什么都不做。** `transcribe` 继承了 4000 字的默认预算, 于是渲染出一个带字数统计的输入框,而厂商请求只由音频构成 —— 打 「输出繁体中文」的人被静默丢弃。目录改成 `prompt_max_chars=0`(前端据此不渲染), 服务端明确拒绝而不是留着不用。 - **「下载」按钮不下载。** `presign_get` 没签 disposition、对象带真实 content-type,于是 `window.open` 把图片渲染在新标签页里;移动端 Feishu webview 里那个标签页经常压根不开,按钮看起来是坏的。加了 `download` 参数签 `attachment`(名字用能力 + 短 id,不用提示词 —— 那是员工的内容,不该进一个 会走到 S3 再进人家下载文件夹的 header)。内联播放器照旧不带,否则播不了。 - **成功的卡片会永远转圈。** presign 失败时 `setUrl(null)` 和「还在生成」渲染成 同一个东西:一个没有文字、没有重试的裸 spinner。改成独立的失败态 + 重试; 同时给 `