docs(权限): 订正 re-review 4 处陈旧注释口径,marker 断言改成只认可执行行

- getUserColumnIds 那段「调用方残留风险」把因果链说过头了:回填集走 sortDirectIds
  (按目录 containsKey 过滤),V143 回滚删掉菜单行时这里根本不会漏出认不出的 id,
  剩下的可达面只有陈旧载荷/直连 API。照实改写,并把跨文件的裸行号换成方法名。
- 扫描注释里的常量出现次数:实跑 8 次 = 1 定义 + 3 出口代码 + 4 javadoc 链接
  (原写 7/4/3 是本笔之前那处 javadoc 还没加时数的)。
- marker 串的运维合同改成可执行行口径,与本类另两条扫描对齐:
  「删掉那行日志、把 marker 留在注释里」不该算守住合同。
  R0 绿、R11 仍红(run=7 fail=1 红: grantIsStrippedInsteadOfRejected)。
This commit is contained in:
2026-10-04 23:42:41 +08:00
parent fd1c9582e9
commit 63c12bf708
2 changed files with 16 additions and 13 deletions
@@ -303,10 +303,12 @@ public class PermissionMenuService {
* 想在这里再剪一刀=未经批准的行为变化,得自带一记变异,别顺手加(review Q8 裁决)。</p>
*
* <p>调用方那一侧的残留风险(详见 task-4 报告「遗留」):{@code AdminUserService.replaceDirectPermissions}
* (:336/:349)先按 {@link #resolveMenuTypes} 给 id 归类,归不出类型的 id 会直接抛
* 「存在无效或不属于当前类型的菜单权限项」,位置在本方法之后、出口 3 的剥离之前。今天碰不到
* (菜单行在、生产 0 条授权),但 V143 的回滚脚本会删 {@code admin_companies} 那一行——真要执行它,
* 得先确认授权也已清干净,否则建号/改号整单失败(09-16 的形状)。</p>
* 先按 {@link #resolveMenuTypes} 给提交的 id 归类,归不出类型的 id 会直接抛
* 「存在无效或不属于当前类型的菜单权限项」,位置在本方法之后、出口 3 的剥离之前。
* 但「菜单行被删 ⇒ 这里把 id 漏出去」那条链由本方法自己掐断:回填集走
* {@code sortDirectIds},它按目录 {@code containsKey} 过滤,目录里已经不存在的 id 根本不会返回——
* 所以 V143 的回滚脚本删掉 {@code admin_companies} 那一行时,这里直接少一项,不会送出一个认不出的 id。
* 今天剩下的可达面只有「陈旧前端载荷 / 直连 API 送进来的未知 id」。</p>
*/
public UserColumnIdsVo getUserColumnIds(AdminUserEntity operator, Long userId, String menuType) {
AdminUserEntity user = getUserById(userId);
@@ -106,10 +106,10 @@ class PermissionCompanyMenuHiddenTest {
/**
* 只留**可执行行**:空行、行注释、块注释与 javadoc 续行(以星号开头的那几行)全部剔除,
* 但**保留原始缩进**({@link #methodBody} 要靠 4 空格收尾括号截方法体)。
* 同款过滤见 {@code CompanyReadPathMenuGateTest.java:69-75}。
* 同款过滤见 {@code modules/company/service/CompanyReadPathMenuGateTest.java} 的 executableLines。
*
* <p>为什么必须过滤:{@code SUPER_ADMIN_ONLY_KEYS} 在 {@code PermissionMenuService.java} 里出现 7 次,
* 其中 4 次是定义 + 三处 javadoc 链接、只有 3 次是代码。旧的"整份文本出现 ≥4 次"于是
* <p>为什么必须过滤:{@code SUPER_ADMIN_ONLY_KEYS} 在 {@code PermissionMenuService.java} 里出现 8 次,
* 4 次是代码(1 处定义 + 3 处出口)、4 次是 javadoc 链接。旧的"整份文本出现 ≥4 次"于是
* 把三处过滤器全删掉也照样绿(Important 1)。</p>
*/
private static List<String> executableCodeLines(String text) {
@@ -148,14 +148,14 @@ class PermissionCompanyMenuHiddenTest {
List<String> code = executableCodeLines(text);
// 取样集非空自检(全局约束 #15):过滤一旦把整份文件滤空、或根本没在滤注释,下面几条都会假绿。
assertThat(code).as("扫描取样集非空自检: 可执行行一条都没滤出来就等于没扫").isNotEmpty();
// 注释必须真被滤掉了:javadoc 里那三处 SUPER_ADMIN_ONLY_KEYS 链接一旦混进取样集,上面的计数就又回到"数得出但没数代码"。
// 注释必须真被滤掉了:javadoc 里那四处 SUPER_ADMIN_ONLY_KEYS 链接一旦混进取样集,上面的计数就又回到"数得出但没数代码"。
assertThat(code).as("扫描取样集自检: 注释行必须已被剔除")
.noneMatch(line -> line.contains("{@link") || line.trim().startsWith("*"));
assertThat(code).as("扫描取样集自检: 三处出口都落在 toItemVos/落库这条链上,扫描必须扫得到它")
.filteredOn(line -> line.contains("toItemVos(")).isNotEmpty();
// 三个出口各自都要引用它,而且只数代码:漏一个就留一条旁路(授权树能看见 / 当前用户菜单能带出 / 提交能写回)。
// 旧写法是"SUPER_ADMIN_ONLY_KEYS 在整份文本里出现 ≥4 次",可 1 处定义 + 3 处 javadoc 就凑得满,
// 旧写法是"SUPER_ADMIN_ONLY_KEYS 在整份文本里出现 ≥4 次",可 1 处定义 + 4 处 javadoc 就凑得满(三处过滤器全删仍剩 5 次),
// 三处过滤器全删(或移进注释 / if (false) / 死分支)它照样绿 —— 变异 R10 就是这一记。
// 现在逐口钉:负向("不是受控项才留下")= 出口 1 的 list(operator, menuType, grantableOnly)
// 与出口 2 的 getUserColumnPermissions(...) 各一条;正向("是受控项才进剥离集")
@@ -183,8 +183,8 @@ class PermissionCompanyMenuHiddenTest {
// 整树提交里带一个历史 admin_companies 绝不能 403:那会让"改密码/建号"这条链整体回滚(09-16 的形状)。
// 注 1:本仓库 AssertJ 无 doesNotContainMatch,这里用等价的 doesNotContainPattern(同为正则不匹配)。
// 注 2(Minor 5,**字面量依赖**、单独看是惰的):这条要 "admin_companies" 这个**字符串**出现在
// ensureGrantable 之后才可能命中;而它在权限模块里只落在常量定义行(SUPER_ADMIN_ONLY_KEYS
// 的 Set.of("admin_companies")),永远排在 ensureGrantable 前面 → find() 恒不命中。
// ensureGrantable 之后才可能命中;而它在权限模块里只落在常量定义行和 getUserColumnIds
// 那段「回填集有意不过滤」的 javadoc 里,两处都排在 ensureGrantable 前面 → find() 恒不命中。
// 留着只当"有人把字面量抄进校验里"的次级绊线,真正咬得住的是下面那条按形状钉的。
assertThat(text).doesNotContainPattern("(?s)ensureGrantable[\\s\\S]{0,600}admin_companies[\\s\\S]{0,200}BusinessException");
@@ -200,8 +200,9 @@ class PermissionCompanyMenuHiddenTest {
// 运维合同是那条 **marker 串**(批次 0 上线验收按它 grep,见 brief Step 6 注脚),不是 log.warn 这个 API 名:
// 改成 log.info、换成别的措辞、或把整行日志挪走,旧断言都还是绿的,而线上就再也 grep 不到这次剥离了。
assertThat(text)
.as("剥离日志的运维合同: marker 串必须逐字留在 PermissionMenuService 里")
// 口径与本类另两条扫描对齐:只认可执行行——「删掉那行日志、把 marker 留在注释里」不算守住合同。
assertThat(String.join("\n", executableCodeLines(text)))
.as("剥离日志的运维合同: marker 串必须逐字落在 PermissionMenuService 的可执行行上")
.contains(STRIP_LOG_MARKER);
}