附录 H — 代码质量与可用性启发式规则

状态：已批准并已在生产中。 没有任何决定悬而未决：形态（D-043 和 D-044）、开关（D-045 和 D-046）、看板（D-047），以及带无障碍权重的初始严重级别（D-048，第 10 节）都已确定。本文件以本方法的全部八种语言发布，其两段提示词已属于提示词 API：自该处起，build/prompts.mjs 要求八种语言中的英文正文逐字节相同，否则构建失败。日期：2026-10-22。

本附录的决策登记：docs/DECISIONES.md，D-043 至 D-048。合规看板（第 12 节）已在 D-047 中以两个数字定案。实现工作活在 PND-002 里。

1. 今天缺什么，以及为什么

台阶 9 已经在测量代码，而且是用一道不放行的闸门在测：单一格式化器、尺寸上限（每个文件三百行、每个函数四十行）、每个函数的复杂度、重复代码、死代码、已声明且被使用的依赖、带棘轮的覆盖率，以及在存在真实用户之处做变异测试。这个数字会写进 docs/CODE_QUALITY.md。那一半已经解决。

没有解决的是产品的另一半。我核对了台阶语料：其中没有一处提到可用性，也没有一处提到人／角色或功能分组。今天界面靠两样东西支撑：所有者看上十秒的截图，以及手工测试用例。两者都很好，但两者都靠人、都昂贵、都会遗忘。一个系统可以带着荣誉通过质量闸门，却完全不可用：一片全绿，而人找不到在哪里收款。

还有一层第二层的问题，它确实是技术问题，但在界面上看得出来：当同一个产品被多个角色使用（管理、运营、查询、客户）时，功能在三处不同的地方被启用——数据库、菜单和路由守卫——而这三处写在不同的时刻，并且会自己走偏。症状总是同一个：有人看到一个不属于他的按钮，或者更糟，一个明明有权限的人找不到那个页面。

下面这两套启发式规则用同一种形态对付这两件事：一份简短的可验证陈述目录、少数几个自行测量的工具，以及一条为项目需要越界时准备的、被声明出来的例外通道。

2. 模型：三层，规则只有一种形态

诱惑是列一份规则清单，然后把它绑到第一个项目的技术栈上。那种做法老得很快：React 的规则不适用于 Angular，Angular 的规则不适用于带模板的服务端，两年之后清单有一半是死的。这个提案把三层分开。

第 1 层 — 与技术栈无关的内核（不可谈判）。 陈述的是结果，不是工具。“只有一个格式化器，而且没有人跟它争”在 TypeScript、PHP 或 Go 里同样成立。内核用稳定的标识符逐条枚举，不随项目而变。

第 2 层 — 按技术栈的适配器（可配置）。 对内核的每条规则，每个前端家族声明*用什么*测量、*用哪个阈值*。一个用 Vite 的 React 项目、一个 Next 项目、一个 Angular 项目、一个带模板的服务端、一个移动端和一个命令行，是同一个内核的六个不同适配器。用户所要求的“按前端可配置”，全部住在这里。

第 3 层 — 项目的决定（声明出来的）。 具体阈值与豁免。它们不是凭空编的：向所有者索取，并写下来，就像架构台阶的规模测算一样。如果某个阈值没有被声明，就运行适配器的那个，并如实登记为该状态。

每条规则永远用同一张六字段记录来写：

例外必须被声明，绝不省略。 一条规则被关掉，要有一份四字段记录：标识符、一行理由、谁批准（所有者，不是代理）以及复查日期。一条被关掉却没有记录的规则，是闸门的故障，不是一项决定。这和方法已经在用的判据一样：不接受为了“通过”而被抬高的上限。

3. 四个工具

任何启发式规则，如果它的验证是一种意见，就没有用。工具是四个，每条规则要声明自己属于哪一个。

1. 自动闸门。 每次 push 和每个块关闭时运行。返回绿或红。它便宜、可重复，而且不争辩。凡是能数的东西它都测。
2. 查询矩阵。 按角色的功能矩阵（见 B2）是一个声明式产物；菜单、路由和权限都由它派生。检查矩阵就是检查界面。这就是把一部分可用性变成机器可验证的那个零件。
3. 按角色的端到端测试。 对每个声明的角色，一个以该角色进入的脚本，把可到达的功能集合与矩阵中那一行做比较：*不多不少*。这是抓住两种典型走偏的测试（多出来的按钮和缺失的页面）。
4. 人工用例。 机器无法判断的东西：分组是否讲得通、任务能否不求人地完成、文本是否在用户的语言里。它由人来执行并被记录，正如台阶 10 已经要求的那样。

4. A 部分 — 代码质量

内核延展台阶 9：它不替换、也不与它矛盾，而是给每一件已经在测的事加上名字、严重级别和适配器，并补上今天缺的东西，也就是被当作代码来看的界面。

CQ-12 到 CQ-18 这些规则，正是让“代码质量”在前端有意义的东西。没有它们，项目可以拥有百分之九十的变异得分，却有一个组件用自己的算术在算总价：两个世界中最坏的那一个，因为重复的计算通过了后端的全部测试。

初始严重级别（D-048）。 从第一天起就阻断的，是十四条有验证器、且不依赖需要讨论的阈值的规则：CQ-01 至 CQ-06、CQ-08 以及 CQ-11 至 CQ-17。CQ-09 在有真实用户之处阻断，因为那才是被测量之处。警告的有三条，而且只有三条：CQ-07（类型）、CQ-10（依赖）和 CQ-18（无障碍），因为它们需要项目先做校准。格式化器、linter、尺寸和复杂度不放宽：台阶 9 今天就已经阻断它们，这里是延展它，不是替换它；遗留债务用一条声明出来的例外、或用棘轮的基线来解决，绝不靠降低规则的严重级别。而 CQ-12 和 CQ-14 是本表中仅有的两条以人工红、而不是机器红来阻断的规则：它们在待办项关闭时验证，把人工用例摆在面前，判据与 UX-22 和 UX-27 相同，而不是在每次提交时。如果项目撑不住这种关闭，规则降为 AVISA，那是因为有登记的决定，不是因为遗忘。

按前端家族的适配器。 第 2 层如何被实例化的一个例子（名称只是示意；项目自己选择并写下来）：

列与列之间变的是工具和阈值。不变的是陈述。这正是让启发式规则保持与技术栈无关、又不让它沦为装饰的原因。

5. B 部分 — 可用性

五个家族。第一个和第二个是所有者明确要求的；另外三个之所以存在，是因为没有它们，分组和角色会以同样的方式退化，只是更慢。

B1 — 按功能收敛的分组

母规则：一个功能按人来做的事分组，而不是按它出自哪个模块分组。 代码按实体组织（“发票”“客户”“付款”）；人不这样。没有人是为了“管理实体”进入系统的：人是为了收款、发货、结账而进来。如果菜单显示的是实体，人就得当翻译。菜单*就是*工作。

B2 — 角色与按角色启用的功能

这里是最出产的那个零件，而理由是工程上的，不是设计上的：启用只在矩阵里声明一次，其余的一切都从它派生。 今天经典错误是把权限写三遍（菜单里、路由守卫里和数据过滤里），然后三者分开。以矩阵为唯一生产者，菜单、路由、服务端权限和测试脚本都是消费者，而方法已经要求的生产者／消费者对称就自己变得可验证了。

矩阵有四列，每个功能一行：*功能*、*归口*（B1 的分组）、*拥有它的角色*、*进入路由*。仅此而已。

B3 — 状态，以及当某样东西不在时人看到什么

大多数“不能用”的投诉，是不会说出“什么都没有”“正在加载”或“失败了”的页面。四个状态，永远，在每张列表和每个详情页面上。

B4 — 操作与错误

B5 — 语言与无障碍

6. 它挂接在哪里，产生哪些产物

本附录不发明新的台阶：它挂在已经存在的台阶上。这避免了闸门重复，也避免了可用性清单通常的命运——被读一次。

它放在哪里（D-043）。 它横贯四个阶段，主要重量在建设循环（台阶 5 到 12），因为那才是做决定和施工的地方。它不是自己的一个台阶：一个编号台阶会迫使整条梯子重编号、改变步数计数，并让本附录在建设转绿之前就受制于合同必须译成八种语言的义务，却不增加任何循环本来没有的闸门。

它如何挂接（D-044）。 一份唯一来源、五个锚点和两个前置入口。规则文本只住在这里，提示词引用它；绝不复制它。把四十五条规则重复进循环的八条提示词里，会稀释它们（它们与每个台阶自己的工作竞争，代理每次遵守得都不一样）、使它们走偏（同一文本的两份副本会自己不同步，正是台阶 11 所追的那种反模式），也不会让它们更横向：让一条规则横向的，是每个块都经过同一道闸门，而不是规则被写在所有地方。

状态（D-049）。 五个锚点已接好：台阶 5、8、9、10、12 的起始提示词以八种语言引用本附录，英文表述在全部语言中只有一段且完全相同，旁边是本地语言译文。本文件与其余方法一起以八种语言在网站发布，其两段提示词已作为契约 anexo-h 进入 docs/html/api/prompts.json：自该处起，build/prompts.mjs 在八种语言中逐字节比对，不同则构建失败。

台阶 6、7 和 11 顶多收到一行：台阶 6 已经把阈值和例外登记为决定（它是声明式例外的天然位置），而台阶 11 正是“矩阵被写在四个地方”那个案子撞上来的地方。不给它们加自己的文本，是为了不稀释它们。

三个产物，都在 docs/ 里：CODE_QUALITY.md（延展）、USABILITY.md（新增，带按规则的结果和已声明的例外）和 PROFILE_MATRIX.md（矩阵，它既是文档，也是菜单的来源）。

7. 配置

每个项目一个文件声明第 2 层和第 3 层。下面是按建议形态写的例子，不是最终取值：

{
  "version": 1,
  "frontend": "react-vite",
  "medido_por": {
    "formato": "prettier",
    "lint": "eslint",
    "tipos": "tsc",
    "complejidad": "eslint-complexity",
    "duplicacion": "jscpd",
    "muertos": "knip",
    "cobertura": "vitest-coverage",
    "mutacion": "stryker",
    "accesibilidad": "axe-core"
  },
  "umbrales": {
    "lineas_por_archivo": 300,
    "lineas_por_funcion": 40,
    "caminos_por_funcion": 10,
    "cobertura_minima": 0,
    "mutacion_objetivo": 0
  },
  "excepciones": [
    {
      "regla": "CQ-17",
      "motivo": "遗留的可打印报表，未使用设计令牌",
      "autoriza": "所有者",
      "revisar": "2027-01-31"
    }
  ]
}

那两个零是故意的，而且正是要紧的部分：最低覆盖率由棘轮用实测值确定，变异目标由所有者在项目有用户时确定。如果它们是零而没有人声明过，闸门会把它报告为未声明的阈值，而不是自己编一个。

8. 这两件东西，按方法使用的形态

代码质量。

可用性。

9. 这个提案不做什么

• 它不增加台阶。 是四十五条横向规则（18 条质量、27 条可用性），不是一个新阶段。它们挂在已经存在的台阶上。
• 它不发明一个分数。 一个“可用性 78”的数字不说明该修什么，而且会被往错的方向优化。按规则报告。第 12 节提出两个派生数字，但它们是带依据的规则计数——不是质量或可用性的评分——也不授权关闭任何东西。
• 它不取代所有者。 首次点击测试、截图和任务测试仍然是人的：它们是唯一能区分“能运行”和“有用”的工具。
• 它不带来出厂阈值。 适配器的那些是一个声明出来的起点；不声明自己阈值的项目继承它们，并被登记为该状态。
• 它不承诺闸门能发现糟糕的分组。 机器可以验证没有重复、没有孤儿；如果一个分组叫“管理”，那得由人来看。

10. 那些决定：什么已解决，什么还缺

已解决

在 D-048 中关闭，以及它带来的两处更正

阻碍撰写提示词的那两个问题已经回答：第 1 个落在第 5 行，第 2 个落在第 6 行。但被批准的那份建议有两处事实错误，写在这里是为了它们不再回来：

1. 计数的缺陷。 凡是本附录说“二十七条规则”的地方，正确的数字是四十五条：18 条质量（CQ-01 至 CQ-18）和 27 条可用性（UX-01 至 UX-27）。那个旧数字来自一份只数了一半的草稿。已在第 6 节和第 9 节更正，并在 D-048 中记下；D-044 的文本按原样保留，因为一项决定是一份登记，不重写。
2. 格式化器、linter、尺寸和复杂度不放宽。 这份建议的一个早期版本把它们送去“警告”，为了不阻塞带遗留债务的项目。这不可能：台阶 9 今天就已经阻断它们，而这次延展是延展，不是替换。遗留债务用一条声明出来的例外——带理由和复查日期——或者用棘轮的基线来解决，不是靠降低规则的严重级别。

还有一条声明出来的限制，因为它是同类中唯一的一条：CQ-12 和 CQ-14 以人工红来阻断。 没有任何工具能证明一个页面不做业务决定。它们在待办项关闭时验证，把人工用例摆在面前，判据与 UX-22 和 UX-27 相同；如果项目撑不住这种关闭，它们因登记的决定降为 AVISA。一条阻断却没人验证的规则，比一条警告的规则更糟。

日历上的待办，不是决定上的待办

翻译。 已完成：本附录以八种语言存在，其两段提示词属于提示词 API，八种版本的英文正文逐字节相同（D-043 如此要求，build/prompts.mjs 在每次构建时验证）。西班牙语仍是正典：若某次译文与西班牙语不一致，以西班牙语为准，并在同一次修改中修正译文。

11. 如何验证闸门确实在把关

一条启发式规则，如果开关它不改变任何东西，那就不是闸门，是装饰。实现的验收测试（PND-002）是一个夹具项目，里面故意种下每个家族的违规：

要看的不仅是颜色：要看报告里那两行关掉说明是否存在。一个没有这一行的绿色结果，是这项测试唯一无法仅凭颜色发现的故障，所以它靠读输出来验证。

12. 合规看板（已决定：两个数字，D-047）

状态。 2026-10-22 在 D-047 中决定：看板带两个数字、带规则集指纹、带棘轮、把人做的部分排除在百分比之外，并且依据是强制的。它不授权关闭块。以下是实现（PND-002）必须满足的规格。

它是什么。 它是闸门已经输出的按规则结果的一个确定性派生。它不测任何新东西，也不判断任何新东西：它数数。如果看板能改变一条规则的裁决，同一件事就有了两个真相来源，而那正是本附录在 UX-10（导航由矩阵派生）和 CQ-14（状态只有一处存放地）里所对抗的。

它不是什么。 它不是验收标准。没有任何数字授权关闭一个块：绿还是红，由每条阻断的规则逐条决定。看板描述趋势、指出该看什么。如果它开始被当作关闭阈值来用，它就不再有用，因为把数字抬上去最短的路是关掉规则。

两个数字，永远不是一个。

为什么是两个：关掉一条规则会抬高合规率，并降低覆盖率。只有一个数字时，关掉是免费的，看板奖励的是失明。有两个朝相反方向移动的数字，这条捷径就消失了：要展示更好的看板，得去修代码，而不是关规则。而覆盖率不测量就无法提高。

规则集的指纹。 每条记录都保存它用什么尺子算出来：目录版本、启用与关掉的规则、前端适配器以及工具版本。没有这些，昨天的 82 和今天的 91 尽管写得一样，却不是同一种测量：它们是两套不同的规则集，序列是假的。两个没有指纹的数字制造进步的幻觉，那比没有看板更糟。如果指纹变了，记录被标为不可比较，或者历史按现行尺子重算；绝不不加说明地画在一起。

棘轮。 合规率不会从一个块到下一个块自行下降，除非有一条解释它的登记决定。这与 CQ-08 中测试覆盖率已经拥有的机制相同：今天的数字是明天的底线。下降不被禁止；没有登记就下降，被禁止。

不进账的东西。 只有人才能判断的东西——首次点击测试（UX-07）、任务测试（UX-06）、截图（UX-27）以及所有人工用例——按块登记为通过或失败，带名字和日期，并作为人类验证覆盖率单独报告。它不进合规率百分比。如果混在一起，结果就是一个百分之六十测量、百分之四十意见的数字，而没人能说出哪一部分是哪一部分。所以第 9 节仍然有效：看板不发明可用性评分，它数规则。

如何证伪它。 扩充第 11 节的验收测试：

它出现在哪里。 在台阶 12 的诚实报告里（锚点 5），并且按这个顺序：先是闸门的二元裁决，然后是两个数字，然后是什么被关掉、关到什么时候，最后是相对上一个块的变动及其被命名的原因。永远带着依据：*下降了四分：CQ-15，收款页面上有三条字符串在目录之外*。没有依据的数字是噪音；依据才让它对一个不读代码的所有者变得可执行。

已声明的风险。 看板会被所有者读，而他不读代码，所以他会希望它上升。数字变成目标，而目标会挤掉目的。防线就是上面那五条，而且正好五条：关掉时相互矛盾的两个数字、让不同尺子无法比较的指纹、不允许无登记下降的棘轮、把人做的部分排除在百分比之外，以及强制的依据，加上绝不用平均值谈判的闸门。这五条里任何一条倒了，看板就关掉：一个被误用的看板，比没有看板害处更大。

13. 登记

本附录的每一项决定都留在 docs/DECISIONES.md，带日期、作者、原文引用和受影响的文件：D-043（形态）、D-044（机制）、D-045（开关）、D-046（开关的纪律）、D-047（带两个数字的看板）。实现及其验收标准活在 PND-002 里。

没有任何决定悬而未决：形态（D-043 和 D-044）、开关（D-045 和 D-046）、看板（D-047），以及带无障碍权重的初始严重级别（D-048）都已确定。正文以八种语言流通，并属于提示词 API，这关闭了日程上仅剩的一项。