Files
crawler-plugin/docs/ops/menu-company-tree-design-2026-10-06.md
T
huangzd1997 18e25ee8b5 docs(菜单权限): 上线复验记录,并改掉两处与实现不符的注释
§11 记下 17:3x 的实跑读数(jar 08b79b33… / Flyway 到 151 / 库侧三条残留为 0 /
两台逐行一致的行为侧 E2E / admin-vue 聚合摘要对平 / 巡检 3 条告警的归因)。

两处注释是复验当场证伪的:menu-manage-api.ts 与 company-scope.ts 都写着
"超管不带 company_id 拿到的是全部公司的行(两排同名菜单)",实测拿到的是本公司那 26 行
—— resolveScopeCompanyId 在参数为空时对超管也返回操作者本公司。留着这句话,
下一个人会以为不传参也能看到别家,从而把 tab 的显式传参当成多余的。

不改行为:后端这道门本就该默认锁本公司。
2026-10-06 17:46:32 +08:00

362 lines
32 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 菜单权限按公司一套树 · 设计(2026-10-06)
控制方要求:「菜单权限也加字段来区分,现在的默认归到 admin 下」,并在两个档位里选了重的那一档——
**每家公司一套菜单树**(不是"只给字典行打个归属标记")。
关联:`company-multi-tenant-design-2026-10-04.md`(账号归属,已上线)、
`brand-dedupe-company-isolation-design-2026-10-04.md`(规则库每公司一套,同一形状)。
## 1. 线上家底(2026-10-06 主机A 业务库只读实查,不是估的)
| 事实 | 读数 |
| --- | --- |
| `columns` 行数 | 52 = admin 26(id 4…109)+ app 24(id 1…96)+ internal 2(id 69、95) |
| `columns` 列 | id/parent_id/name/column_key/menu_type/route_path/sort_order/created_at/updated_at,**无 company_id** |
| 唯一键 | **两条**:`uk_column_key(column_key)`、`uk_menu_type_route_path(menu_type, route_path)` |
| 其他索引/约束 | `PRIMARY(id)`、`idx_columns_parent_sort_id`、`idx_menu_type_sort_id`、`fk_columns_parent_id`→`columns(id)` |
| `user_column_permission` | 784 笔 / 133 只账号 / 34 个被授权 column_id |
| 授权按公司分布 | 公司 1(厦门米椿花)131 人 768 笔;公司 2(德阳)2 人 **16 笔** |
| 同 key 重复行 | 0 行 ⇒ 原地换复合键不会因重复失败 |
| `admin_companies`(id 109)授权 | 0 笔(10-04 事故后的既定状态) |
`PermissionMenuSchemaInitializer` 生产是关的(`application.yml:259` 默认 `false`),但它是 JdbcTemplate
旁路,十几条种子 SQL 的幂等守卫全是裸 `NOT EXISTS(column_key)`——换键后它不改就会一声不响地不再插行。
本批已把这条通道的 31 段种子语句逐条钉上 `company_id = 1`(落法与理由见 §5 末条,护栏见 §8)。
## 2. 三档定案(控制方「直接开干」,按推荐档落)
- **D1 存量授权**:V149 同笔把公司 2 那 16 笔授权按 `column_key` 重指向本公司副本。
不留成人工动作,否则德阳那 2 只账号一上线就掉光菜单(隐藏=静默删除)。
- **D2 谁能编辑别家的树**:站点超管可带 `company_id` 读写任意公司的树;非超管恒锁本公司,
传了别人的 `company_id` 一律 403。今天就是超管在给 133 只账号配权限,锁死本公司等于把这件活关掉。
- **D3 复制范围**:admin + app + internal 三种 `menu_type` 全复制(客户端账号同样分属两家公司,
只复制 admin 会留半棵共享树);**`admin_companies` 那一行不复制**——它是角色内在闸门
(`SUPER_ADMIN_ONLY_KEYS`),公司 2 的树里根本没有这行,比"有一行但看不见"更干净。
- **D4 之后新建的公司**:V149 只补当时已存在的公司,「公司管理 → 新增公司」必须同批建树,
否则新租户是一个零菜单行的公司(账号登录侧边栏全空、授权树一个勾都没有,全程不报错)。
落法见 §5 的 `copyTreeFromTemplate`,与建号同一次写入、不留"上线后手工再跑一遍复制段"。
## 3. 数据模型(V149)
1. `ADD COLUMN company_id bigint NULL`(末位)→ `UPDATE ... SET company_id = 1 WHERE company_id IS NULL`
→ `MODIFY COLUMN company_id bigint NOT NULL DEFAULT 1`。第三句同时是回填自检闸门:漏一行就抛 1048
(V143 同形)。`DEFAULT 1` 只为混合版本窗口的旧 jar 存在(旧 jar 的实体没这字段,严格模式建菜单会 1364),
摘除动作是下一版的一条纯元数据操作 `ALTER TABLE columns ALTER COLUMN company_id DROP DEFAULT`(**禁 MODIFY**,
重建会按当时的列默认值物化历史行),取号见 `backend-java/docs/migration-inventory.md`(当前 V152 起)。
哨兵 `CompanyDefaultGuard.WATCHED_TABLES` 已把 `columns` 探进清单——摘之前巡检每天多喊一条
`COMPANY_DEFAULT_STILL_PRESENT`,那是哨兵在干活,不是新故障。
2. 两条唯一键**先 ADD 后 DROP**(中间任一步失败都至少还有一个键在守并发):
`uk_company_column_key(company_id, column_key)`、
`uk_company_menu_type_route_path(company_id, menu_type, route_path)`。
新键是旧键的严格放宽 ⇒ 不会因重复失败。索引字节预算(utf8mb4):8+256=264、8+80+1020=1108,都远低于 3072。
3. 不加 `company_id` 的单列索引:新唯一键的最左前缀就是它,52 行的表再开索引就是 V139 那轮清理掉的冗余形状。
4. 复制:按「`company` 全表 × 公司 1 的字典行」插副本(不是硬编码公司 2,第三家开通时不用再改迁移),
`parent_id` **先留 NULL**,再由下一条 UPDATE 沿 `(company_id, column_key)` 把父指向重映射到同公司副本——
与插入顺序无关,两级三层都成立。带源值插入是错的:那是全局 id,副本会跨公司挂到厦门米椿花的分组上,
而 FK 只保证父行存在、挡不住挂在别家。
5. 授权重指向:`user_column_permission` 按「账号公司 = 行公司」重算 `column_id`。
重跑是 no-op(驱动条件要求行还挂在公司 1 上且账号不属于公司 1);重指前先摘掉"源行 + 副本"并存的重复授权,
否则重指会撞 PK `(user_id, column_id)` 报 1062。
6. 四道自检闸门(临时表 `must_be_zero INT NOT NULL`,V143 那个"约束替我喊"的家族):
① 每家公司的树与公司 1 一样齐(专防复制段被 `NOT EXISTS` 守卫一声不响挡掉一整家);
② 跨公司父指向残留 = 0;③ 跨公司授权残留 = 0;④ `company_id` 不为 NULL/不为 0。
不为 0 就让迁移失败,而不是留下一个静默分叉的树。
外键 `fk_columns_parent_id` 只保证父行存在,**挡不住跨公司挂父**,所以同公司判定必须在应用层(§4)。
## 4. 后端读侧:出口一起收窄
判据只有一个来源:`loadRawMenus(companyId, menuType)`。它是 `hasAnyAdminMenu`、`expandDescendantIds`、
`superAdminOnlyMenuIds`、授权树、有效菜单、`resolveGrantableMenuIds` 的共同上游,剪这一处等于剪一片。
| 出口 | 现在的形状 | 改成 |
| --- | --- | --- |
| `list()` 目录(菜单管理页) | 全量 52 行 | 按**操作者**公司;超管可用 `?company_id=` 指定 |
| `list(operator, type, true)` 授权树 | 操作者范围 | 范围集按操作者公司算,跨公司项永不下发 |
| `getUserColumnPermissions()` 有效菜单(登录/侧边栏) | `loadMenus(type)` 全表 | 按**被授权账号**公司 |
| `getUserColumnIds()` 回填集 | 同上 | 按目标账号公司 |
| `findDataPermission()`(`selectOne + LIMIT 1`) | 全局按 key 点查 | **必须带公司**:换键后同 key 有 N 行,`LIMIT 1` 会跨公司借位拿到别家的数据权限行——本次最危险的一处静默失效 |
| `hasEffectiveColumnPermission()` | 查得到就展开判定 | 行公司与账号公司不同 ⇒ 直接 false |
| `ensureUniqueColumnKey()` / `ensureUniqueRoutePath()` | 全局查重 | 本公司内查重;不改的话德阳在公司 1 建过的 key 上**根本建不出来** |
| `resolveSortOrder()` / `reorder()` | 同类型全局 MAX+1 / 兄弟集 | 同公司内 |
| `resolveMenuTypes()`(建号/编辑拆分 admin+app) | 按 id 归类 | **归类本身不带公司**(它按 id 批量取行,跨公司照样归得出类型);真正挡下别家 id 的是它下游的出口 3——`updateUserColumnPermissions` 的有效计数与 `loadMenus` 都按**目标账号公司**取,别家 id 在那里被抛 400「存在无效或不属于当前类型的菜单权限项」。这条要写准,否则下一个人会到 `resolveMenuTypes` 里找一道并不存在的公司闸门 |
| 两个数据范围授权端点 | 只挡超管,用户列表全量 | 数据权限行按公司解析,用户列表按公司筛 |
`hasEffectiveColumnPermission` 那处保守方向要说清:跨公司拿不到行时判"无权限",是拒绝而不是放行。
**"请求里的 `company_id` 到底在哪一步被收窄"要说准**:不在 controller 里写 `if`,也不在各页 service 里各写一遍,
而是收参数的当场交给 `PermissionMenuService.resolveScopeCompanyId(operator, companyId)`(公开方法,
把返回值**往下传**而不是丢掉),六个带这参数的 handler 全部同形——目录 GET/POST、两个数据范围授权的 GET 与 PUT:
```java
AdminUserEntity operator = requireAdmin(request);
Long scopeCompanyId = permissionMenuService.resolveScopeCompanyId(operator, companyId);
return ApiResponse.success(permissionMenuService.list(operator, menuType, grantableOnly, scopeCompanyId));
```
这条出口注册进了 `CompanyIdParamGoesThroughReadScopeTest` 的 `SCOPE_DOORS`(现在是**三道门**:
`readScope(`、`readCompanyIdOrOwn(`、`resolveScopeCompanyId(`),A/B/C/D 四条判据共用:
handler 收了 `company_id` 就必须走门、取到的绑定名必须真的出现在下游实参里。
所以"控制器多写一个带 `company_id` 的口却没过归属判定"是编译后跑一条用例就红,不靠人记着。
`PUT /permission-users/{userId}/columns` 与 `update`/`delete`/`reorder` 故意不带这个参数:
它们按行 id 或按被授权账号定位,归属在 service 里判(§5),前端再猜一个公司参数只会多出一个可伪造的入口。
## 5. 后端写侧
- `ensureAdminOperatorIfPresent` 只判 `isAdmin`,这是写侧唯一的洞——非超管今天能改整张目录。
补两条:目标行公司 = 操作者公司(超管除外,`ensureMenuWritable`);`ensureParentValid` 对**整条祖先链**
判同公司(一个同公司的父、上面挂着别家的分组,落库后这行在两棵树里都渲染不出)。
- `delete` 与 `reorder` 都先过 `ensureMenuWritable`;`reorder` 原来不带操作者(控制器那一层),已补。
- 新增菜单的归属:由**端点的 `company_id` 参数(缺省=操作者公司)**决定,前端不靠猜;超管传别家=给别家建。
读侧与写侧共用同一个判据 `resolveScopeCompanyId`——分成两个迟早漂移成「读能看别家、写挡不住」。
- `copyTreeFromTemplate(companyId, templateCompanyId)`(D4):`CompanyService.create` 在建号那笔事务里
调它,模板公司是**操作者本公司**(参数由调用方给,方法内部不编默认值;缺归属直接拒)。
两趟写与 V149 第 6/7 段同形:第一趟只管插、父先留空,第二趟按 `column_key` 认父;
`SUPER_ADMIN_ONLY_KEYS` 那行不进副本;目标公司已有的 key 原样保留 ⇒ 重跑只补差集。
- **旁路种子(`PermissionMenuSchemaInitializer`)只种公司 1**:七条 `INSERT INTO columns` 的列清单显式写
`company_id`、投影写真常量 `1`;判存守卫、认父 JOIN、按 key 的 UPDATE、三条下划线→连字符改名,
全部带 `company_id = 1`。理由是换键之后 `column_key` 只在单家公司内唯一——一条裸
`WHERE column_key = ...` 在这张表上的语义是"把每一家的同名行都改一遍"(别家副本的 parent 被拍平、
初始授权发给别家的行 id),而 `executeQuietly` 把 1048/1062 吞成一行 debug 日志,表现是"某一家
一声不响少一套菜单"。`grantInitialShopDataCrawlDataPermissions` 那条 JOIN 另加
`data_col.company_id = old_col.company_id`。显式写公司还有一层作用:这条通道不再依赖列上那条
`DEFAULT 1`,于是 §3 待办里那句 `DROP DEFAULT` 落地时不会让建号变成 1364。
别家公司的树不由这里插行——存量归 V149 的复制段,新建归 `copyTreeFromTemplate`。
## 6. 前端
每个响应只含一家公司的行 ⇒ `column_key` 在单响应内仍唯一,侧边栏、路由守卫、`hasMenuKey`、
`menu-route-map`、`parseMenuTree` 全不用改。这条不变量的看守是"查询条件必须带公司"本身
(§8 的 `everyMenuQueryCarriesTheOperatorsCompany` + `onlyTheSiteSuperAdminMayCrossCompanies`:
不传 `company_id` 时锁操作者本公司,超管显式指定才换家),不是"响应里数一遍 key 有没有重复"——
后者在假数据上永远为真,杀不掉任何变异。
- 「菜单管理」(`admin_columns`) 把 10-06 摘掉的公司 tab 装回来:`COMPANY_SCOPED_PAGES` 加一行
(正向清单 `companyTabAppliesTo` 自动放行,不需要新代码),`MenusPage.vue` watch `tab.activeId`
清掉本页那两个客户端筛选项(菜单名称/类型不进请求)并重取数。
- **「菜单管理」这一页带 `company_id` 的只有两个口**:`fetchMenuManageNodes`(GET 目录)与 `createMenu`(POST 新建)。
`updateMenu`/`deleteMenu`/`reorderMenus` 故意不带——它们按行 id 定位,归属判定在后端
(`ensureMenuWritable` 比较行公司与操作者公司,跨公司 403);前端再从树里猜一个公司参数只会多出一个可被伪造的入口。
- **用户管理里的授权弹窗必须带 `company_id`**(本条推翻初稿写的"不加参数:树按被授权账号的公司出,
载荷里的 id 天然同公司"——那句在 V149 之后是错的):一棵树一套 id,
授权树若按**操作者**公司下发,而目标账号在另一家(超管切了 tab 或在给自己以外公司的账号配权限),
则该账号已有的 `column_id` 全都不在这棵树里 ⇒ 已授权一项勾不上,点保存又被
`ensureGrantable` 判「无效的菜单权限项」,整页授权直接不可用。所以读侧(`fetchGrantableMenus`)
与写侧(按范围整树替换)必须同时收窄,只窄一侧等于把授权藏掉。
取值来源分两处、各对应后端真正会用的那一家:编辑弹窗用 `companyTab.requestCompanyId`
(列表本来就由它筛 ⇒ 行公司 = tab 公司),新建弹窗用 `form.companyId`(建号弹窗里选的那家,
与 `user-create-model` 下发给后端的 `payload.companyId` 同一个值;未选则为 null,后端落操作者本公司)。
- **两处没做界面暴露(本批只到后端)**:图片视频任务、店铺数据任务那两个「数据范围授权」弹窗
(`fetchImageVideoPermissionUsers` / `fetchShopDataTaskPermissionUsers` 及其 PUT 孪生)仍然一个公司参数都不发。
后端那两个端点本批已经收下 `company_id`(缺省=操作者本公司 ⇒ 与改动前同义,不是回归),
但站点超管在那两页切 tab 时弹窗候选不会跟着换家。这属于"新维度的界面暴露",按口径要单独批准,不在本批顺手做。
## 7. 发布顺序与混合版本窗口
路线甲(选定):V149 与 jar 同批发,双台同窗口(A 金丝雀过了立刻补 B),迁移在首台启动期执行。
V149 不是单独一支 jar:按 `backend-java/docs/migration-inventory.md`,下一版要连着跑 `V150__shop_key_company_scope`
与 `V151__rule_tables_shared_across_companies`(同批待发的另外两路),三条按序、一次启动跑完;
取号只认"当前最大值 + 1",V148 已随它被推翻的口径退役,不许回填。
窗口内旧 jar 的后果逐条列清:
- 目录/授权树会短时出现两排同名菜单(难看,不伤人);
- `findDataPermission` 的 `LIMIT 1` 借到公司 1 的行时,判的是"本公司授权集合里没有这个 id" ⇒ **拒绝而不是放行**;
- 建菜单会误报"菜单标识已存在"(旧 jar 的全局查重撞副本)。
都是分钟级、方向保守。路线乙(新 jar 带"本公司无行就回落公司 1"的临时分支)否决:那条回落正是
`ProductCategoryService` 这一轮刚拆掉的"哨兵 0 可见集"形状,而且公司 2 在两批之间看不到自己的树。
## 8. 自证(落码后按实物补,不写"补一些用例"这种没法核对的话)
| 面 | 看守 | 数量 |
| --- | --- | --- |
| 迁移形状 | `MenuTreeCompanyMigrationV149Test`:列存在且 NOT NULL、两条新复合键在、两条旧键已摘、`company_id` 无 NULL/无 0、复制段与重指段的驱动条件逐条在场、四道 `_v149_gate` 自检各就各位、回滚脚本不在 Flyway 扫描路径、**旁路种子逐条钉公司**(`schemaInitializerSeedsEveryRowIntoTheTemplateCompany`:31 段种子/14 段按 key 认菜单,取样集有下限,且喂一条已知违规必须被抓到) | 20 例 |
| 读侧收窄 | `PermissionMenuServiceCompanyScopeTest`:`loadRawMenus`/`findDataPermission`(`LIMIT 1` 借位那一形)/`hasEffectiveColumnPermission`/祖先链/重名查重/授权有效性计数/`resolveScopeCompanyId` 各按公司取;反向钉"不许出现回落公司 1 的临时分支" | 16 例 |
| 控制器 | `PermissionMenuControllerTest`:`company_id` **先过 `resolveScopeCompanyId` 再往下传**(六个 handler 各验一次,桩返回 `99L` 与原始 `7L` 不同值 ⇒ "传了原值"和"传了判定值"不可能双双通过),缺省 `null` 那两例同样进门而不是编一个默认公司 | 10 例 |
| 归属正门 | `CompanyIdParamGoesThroughReadScopeTest`:`SCOPE_DOORS` 从两道门加到三道(`readScope(` / `readCompanyIdOrOwn(` / `resolveScopeCompanyId(`),A/B/C/D 四条判据共用;新增三条 `menuScopeDoor*` 探针,其中"取到范围却丢掉"和"门参数列表里没有那个绑定名"两条必须红 | 3 例(含全部页面的取样) |
| 哨兵 | `CompanyDefaultGuardTest`:`columns` 同时进 `WATCHED_TABLES` 与探测 SQL 的 IN 清单(双向钉同源) | 14 例 |
| 闸门行不旁路 | `PermissionCompanyMenuHiddenTest`:本批给建树加了**第四处**出口,`SUPER_ADMIN_ONLY_KEYS` 的引用从"两处负向 + 一处反解"改成三处负向(`list` / `getUserColumnPermissions` / `copyTreeFromTemplate`)+ 一处正向反解,且只数剥掉注释后的可执行行——旧写法"整份文本里出现 ≥4 次"被 1 处定义 + 4 处 javadoc 就凑得满,三处过滤器全删照样绿 | 7 例 |
| 前端接线 | `company-tab-wiring.test.ts`:`admin_columns` 进 `COMPANY_SCOPED_PAGES` + `SEND_POINTS` 登记三处新发送口(全表 21 处 / 按 (文件,整行) 聚成 17 组,与真文件条数逐处对平)、`WATCH_BODY_PINS` 加 `MenusPage.vue` 一对(共 10 对) | `node --test` 1731 例全绿 |
| 前端文案 | `align-operation-guide.test.ts`:`admin_columns` 的引导文案补上公司 tab 那句(句子本体与分母规则见 `company-tab-design-2026-10-04.md`,不在本文件里):带 tab 那句的页面集合 = 注册表 16 页减去唯一豁免 = 15 页,多一页少一页都红 | 同一批 1731 例内 |
| 建司种子 | `CompanyServiceDirectoryTest`:`create` 在插公司行之后同一次写入里调 `copyTreeFromTemplate(新公司, 操作者本公司)`(`InOrder` 钉顺序);重名被拒那一笔反向钉"不许留下一套挂在不存在公司上的菜单" | 19 例(本批新增 2 例) |
| 类型 | `vue-tsc --noEmit` | 0 错误 |
| 全量(主树 2026-10-06 16:59 / 17:0x 实跑) | 后端 `mvn -o test`(无 skipTests)`Tests run: 3891, Failures: 0, Errors: 0, Skipped: 7` / BUILD SUCCESS,460 支测试类(逐类相加同为 3891);前端 `node --test tests/*.test.ts` 1731 例 / 0 红 | 本轮跑出的三条红见下节末「补记」 |
变异自证(已实跑,2026-10-06,在 `tmp/v149-wt` 独立 worktree 里,主树 `PermissionMenuService.java`
全程 md5 `2f29aa0bb39447dcab6f68878bd546b3` 未动):对 `PermissionMenuService` 逐点注入
"把 `.eq(…companyId…)` 改成 `.eq(false, …companyId…)`"(这一形就是"列名还在、值被丢"的静默失效原型)
以及三条建树/归属语义的反向改写,12 个点各开一次 mvn,分母恒为 `PermissionMenuServiceCompanyScopeTest` 的 16 例:
```
PRISTINE bytes=86315 lines=1615
BASELINE tests=16 failures=0 errors=0 rc=0 (401s)
KILLED loadRawMenus drops company red=4/16 (286s)
KILLED reorder siblings drop company red=1/16 (354s)
KILLED grant validity count drops target company red=1/16 (317s)
KILLED findDataPermission drops company (LIMIT 1 borrow) red=1/16 (211s)
KILLED ensureUniqueColumnKey drops company red=1/16 (193s)
KILLED grantableUserQuery drops company red=1/16 (216s)
KILLED resolveScopeCompanyId lets anyone cross companies red=1/16 (182s)
KILLED ensureMenuWritable stops guarding red=1/16 (135s)
KILLED hasEffectiveColumnPermission stops denying foreign id red=1/16 (163s)
KILLED ensureParentValid stops checking ancestor chain red=2/16 (208s)
KILLED copyTree clones the role-intrinsic gate row red=1/16 (193s)
KILLED copyTree no longer short-circuits self-copy red=1/16 (137s)
RESTORE-CHECK ok
SUMMARY injected=12 killed=12 survived=0 void=0
```
`red=4/16` 那一处(`loadRawMenus`)是唯一的公共读口,四条用例同时红;其余各点各红 1 条,
`ensureParentValid` 红 2 条。两条 `copyTree` 变异分别被「建树:三种 menu_type 全复制、闸门行不复制」
和「建树不许靠默认值兜」这两条打死——D3(不复制 `admin_companies`)与"不自拷"都由这套用例独立看守,
不是靠读侧顺带压住的;本轮选中的类只有 `PermissionMenuServiceCompanyScopeTest`(分母恒 16),
所以这 12 条红全部出在它内部。`CompanyService.create` 那一笔种树调用另由
`CompanyServiceDirectoryTest` 的「插行之后同一次写入里复制菜单树」与「建公司被拒时不建树」两条钉住
(验的是调用点与顺序,不在变异分母里)。
**补记(那 12 轮之后全量跑出的三条红,加一处顺带收口)**:上面那份日志的 md5 只覆盖到扫描时点,
之后的改动不在那 12 个点里,各自另加了尺子——
1. **后端红**:控制器六个 handler 收了 `company_id` 却没走任何归属出口
(`CompanyIdParamGoesThroughReadScopeTest` 断言 A 红)。修法不是往 `READ_SCOPE_ALLOWLIST` 里添六条豁免,
而是把 `resolveScopeCompanyId` 注册成**第三道正门**,并给它配三条自己的探针(能过 / 取了丢掉 / 传 null),
让"下一个新页面忘了收口"这件事仍然是编译后跑一条用例就红。
2. **后端红**:`copyTreeFromTemplate` 是 `SUPER_ADMIN_ONLY_KEYS` 的第四处引用点
(`PermissionCompanyMenuHiddenTest` 红)。这条 SDD 台账里预先写过(要求加变异 + 把期望从
"恰 2 负 + 恰 1 正 + ≥4"往前挪),本批按它挪成 **恰 3 负 + 恰 1 正 + 定义与出口共 ≥5 行**;
对应变异就是那份日志里的第 11 轮 `copyTree clones the role-intrinsic gate row`(已被打死,`red=1/16`)。
3. **前端红**:`align-user-menu-grantable.test.ts:105` 原本把控制器的调用形状钉成
`list(requireAdmin(request), menuType, grantableOnly, companyId)`(原值透传),本批改过门之后它红。
这条不是"测试写错了",而是**前端侧唯一读 Java 控制器源的那把尺子**——挪成新形状时补了一条
`doesNotMatch(/menuType, grantableOnly, companyId\s*\)/)` 反向钉:不许有人图省事把 tab 原文再透传回去。
4. **顺带收口**:旁路种子(`PermissionMenuSchemaInitializer`)的 31 段种子逐条钉上 `company_id`,
并加 `schemaInitializerSeedsEveryRowIntoTheTemplateCompany` 反向钉住——这条通道的失效形状是
`executeQuietly` 把 SQL 错误吞成 debug 日志,"某一家少一套菜单"不会喊。
这些都不在变异分母 16 例里(护栏形状与文件形状,不是运行时行为),靠的是各自用例里的取样下限 +
已知违规探针;验收读数是本轮主树实跑:后端 `mvn -o test` **3891 例 / 0 红 / 7 skip**(460 支类,逐类相加同为 3891),
前端 `node --test tests/*.test.ts` **1731 例 / 0 红**。
线上复验探针(发版后只读跑):`scripts/_probe_menu_company_shape.py` 在原有 8 条之后加了 5 条——
各家 × `menu_type` 的行数(每家必须与公司 1 一样齐)、跨公司挂父 = 0、跨公司授权残留 = 0、
`admin_companies` 那一行不在公司 1 之外、`columns.company_id` 的 `COLUMN_DEFAULT`(摘 DEFAULT 那条待办的复验口)。
发版前跑这五条会各回一条 `Unknown column 'company_id'`——那是列还没有,不是探针坏,五条各有 `@@` 标记互不牵连。
生产写操作一律先取证 → 备份 → `--apply`,由控制方执行或明确授权后代跑。
## 9. 回滚
`backend-java/docs/rollback-V149-permission-menu-company.sql`(Flyway 扫描路径之外):
授权重指回公司 1 的行 → 删副本 → 换回两条旧唯一键 → `DROP COLUMN company_id` →
删 `flyway_schema_history` 的 version=149 行 → 回滚 jar → 起应用。
副本 `column_id` 一旦有新增授权,回滚脚本先报数再停手,不做静默删除。
## 10. 发版命令包(本批 0 手工 SQL:迁移在 jar 启动期由 Flyway 跑)
前提:两支待发的后端批次(V149 本批 + V150/V151 店铺密钥与规则库)都要先进同一个提交,
出包树才能同时带上三条迁移;前端要带本批的 `admin_columns` 接线与 10-06 那三个公司 tab 文件。
提交与推送由控制方决定,代跑生产写操作需要明确授权。
**下面每一行都在同一个目录下跑:工作区根 `D:\todesk\副业\数富AI`**(`scripts/` 在这一层,
`crawler-plugin/` 也在这一层)。前面那条 `cd` 会把后面几行带到别的目录里去,所以每条需要换目录的
都用子 shell 括号包住,不留状态。
**发版前取证(只读,我可以自己跑)**
```
python scripts/_probe_jar_md5.py # 两台现网 jar 的 md5 与体积(回滚点)
python scripts/_probe_menu_company_shape.py # 基线:前 8 条有数,后 5 条回 Unknown column 'company_id' 才是对的
```
**出包(本地,从干净 worktree;入口与输入件路径 10-06 逐条 `-e` 验过存在)**
```
git -C crawler-plugin worktree add crawler-plugin/tmp/v149-build <含本批的提交>
# 三处文档输入未入库,读者是 ExplainIndexAuditDocTest / ArchitecturePlanSection6DocTest / IndexMigrationV101Test:
cp -r crawler-plugin/backend-java/docs/specs crawler-plugin/tmp/v149-build/backend-java/docs/
cp crawler-plugin/backend-java/docs/explain-index-audit.md \
crawler-plugin/backend-java/docs/java-architecture-optimization-plan.md \
crawler-plugin/tmp/v149-build/backend-java/docs/
(cd crawler-plugin/tmp/v149-build/backend-java && mvn -o clean package) # 上线不许 skipTests;clean 只在出包树,主树禁
ls -l crawler-plugin/tmp/v149-build/backend-java/target/*.jar
```
**发布(写生产,两台同窗,逐台健康门禁按主机给端口:A 18080 / B 19080)**
```
python scripts/_deploy_verified_jar.py <jar路径> <期望md5> --check # 只读:记录线上 md5 + 两台健康
python scripts/_deploy_verified_jar.py <jar路径> <期望md5> # 上传 → 校验 → 重启 → 健康 → 复核
(cd crawler-plugin/admin-frontend-vue && npm run build)
python scripts/_deploy_admin_vue.py # dist 只在主机B /var/www,软链原子切
```
**发版后复验(只读)**
```
python scripts/_probe_menu_company_shape.py # cols_by_company 各家行数须等于公司 1;三条残留须为 0;
# admin_companies_outside_company1 须为 0(D3)
python scripts/_prod_watch.py --window 30m # ALERTS 只认 † 那几条;本批预期多一条 COMPANY_DEFAULT_STILL_PRESENT
# (columns 进了哨兵清单,摘 DEFAULT 之前它每天都在喊,那是哨兵在干活)
```
前端两件事各自单独核:**线上树 == 本地构建**用整树聚合摘要(本地在 `dist` 上跑、远端在
`/var/www/admin-vue-<ts>` 上跑同一条管道,两个值必须相等):
```
(cd crawler-plugin/admin-frontend-vue/dist && find . -type f | sort | xargs md5sum | cut -d' ' -f1 | sort | md5sum)
```
**这版到底带没带本批的接线**用扛得住 minify 的字面量数:`dist/assets/MenusPage-*.js` 里 `company_id` 应为 2
(目录 + 新建),带 `grantableOnly` 的那个 UsersPage chunk 里应为 1(授权树)。
本地 10-06 17:05 那版构建(`vue-tsc --noEmit` 0 错误、`npm run build` RC=0)实测就是这两个数:
`MenusPage-Cui-Lsn1.js` `company_id`=2、`UsersPage-DeJ6Wy_U.js` `company_id`=1(同文件 `grantableOnly`=2)。
## 11. 上线后复验(2026-10-06 17:3x–17:4x 实跑读数,不是计划)
**发版**:提交 `1d27806a`(本批 + 并行的 V150/V151 合在一笔,理由见提交说明)→ 出包树
`crawler-plugin/tmp/v149-build`(`mvn -o clean package` 不 skipTests)→ `Tests run: 3891, Failures: 0,
Errors: 0, Skipped: 7` / BUILD SUCCESS → jar `08b79b334091a80e2493d9de1bc9392a` / 137,499,094 B。
两台上传后远端 md5 复核一致、health=200;回滚点 `.bak-20261006173005`(A) / `.bak-20261006173210`(B),
上一版是 `39f6640745b985f5be32cb384eb8e220`。Flyway 到 **151**:rank 59/60/61 = 149/150/151,
`success=1`,时间 17:32:29–30(只在先起的那台跑一次)。
**库侧形状**(`_probe_menu_company_shape.py`):`columns` 52→154 行,每家 admin 26/25/25、app 24、internal 2;
`cross_company_parent` = 0、`cross_company_grant` = 0、`admin_companies_outside_company1` = 0(D3 成立);
旧键 `uk_column_key`/`uk_menu_type_route_path` 已被 `uk_company_column_key`/`uk_company_menu_type_route_path`
替换;`dup_keys` 从发版前 0 变成 51 = 每家一份同名 key 的必然结果(不是回归)。
`grant_shape` 的 788 笔没变、而 `COUNT(DISTINCT column_id)` 从 34 涨到 50 = 恰好 +16,
对上 D1「公司 2 的 16 笔重指向到自己副本」这个数。
`company_id` 仍是 `NOT NULL DEFAULT 1` ⇒ 摘 DEFAULT 那条元数据操作仍欠着(下一版做)。
V150:`biz_shop_key.company_id` 已加、16 行全归公司 1。V151:`biz_invalid_asin_data` 唯一键回到
`uk_data_value_brand(data_value,brand)`、`biz_product_category` 回到 `uk_product_category_key(category_key)`
(412 行 / 412 个不同 key ⇒ 全局唯一 satisfiable)。
**行为侧(内部令牌 + `operatorId`,两台各打一遍,逐行一致)**:
只打 `GET /api/admin/permission-menus?menuType=admin`。**注意判据**:越界时 HTTP 仍是 200,
拒绝在响应体的 `"code":403`(86 B)里 ⇒ 只看 `%{http_code}` 会把 403 读成放行。
行数锚 `"column_key"`(VO 上是 `@JsonProperty("column_key")`,锚 `columnKey` 恒 0)。
| 操作者 | 参数 | 读数 |
|---|---|---|
| 超管 1 | 不带 | 26 行、含 `admin_companies` |
| 超管 1 | `company_id=1/2/3` | 26 / 25 / 25 行,别两家不含 `admin_companies` |
| 公司 2 管理员 1193 | 不带 / `company_id=1` | 25 行 / `"code":403` |
| 公司 1 管理员 3(非超管) | 不带 / `company_id=2` | 26 行 / `"code":403` |
| 公司 3 `company_super_admin` 1201 | 不带 / `company_id=1` | 25 行 / `"code":403` |
两点要记:① **超管不带 `company_id` 拿的是本公司那 26 行,不是三家混合**(`resolveScopeCompanyId`
在 `requestedCompanyId == null` 时直接返回操作者公司,对超管也不例外)—— 前端 `menu-manage-api.ts`
与 `company-scope.ts` 原先写的"超管拿到全部公司的行/两排同名菜单"与实现不符,已随本次复验改口。
② `company_super_admin` 不算站点超管(跨家读被 403 挡住),这与 D2 只放开 `super_admin` 一致。
**前端**:`admin-vue-20261006-173552`(回滚点 `20261006-110820`),远端整树聚合摘要
`eda9c8af236ae46e067e8ddcc0f62a3f` == 本地构建;`MenusPage-Cui-Lsn1.js` `company_id`=2、
`UsersPage-DeJ6Wy_U.js` `company_id`=1。改那两处注释后重建,摘要逐字未变 ⇒ minify 剥注释,
现网 dist 就是改注释之后的构建,不必重发。前端全量 **1731 例 / 0 红**。
**巡检 `--window 30m`**:ALERTS=3 = `公司DEFAULT未摘` 两台各 1(哨兵在干活,本批新增 `columns` 进清单)
+ 主机B `类加载=121`。后者已归因:121 条全部落在重启那一分钟 `09:32Z`(=17:32 本地),之后 12 分钟
12,611 行日志里 0 条,而 A 同版同窗口 0 条 —— 与 10-05 记下的"启动窗口惰性类加载被首批请求抢跑"同形,
不是本批引入。缺的类是 `StandardMultipartHttpServletRequest`、`PropertyMetaData$1`、
`SimilarAsinTaskDetailVo` 这类首次使用才加载的东西,与本批改动无交集。
**未做**:真人浏览器打开「菜单权限」页看两排 tab 与切换后的树,仍欠。