前端显示完整性审计（ui-audit.py）¶

位置：deploy/nfos/tools/ui-audit.py ｜语言：python3 ｜是否需要 root：否

工具性质：本地静态审计（只读 CSS；只写 --out 指定的文件） 运行前提：仓库检出必须在场（默认 CSS 路径与 lint-layout.py 都从仓库根推导）。可从任意位置运行（工具自动向上找到含 deploy/nfos 的祖先目录） 部署状态：随仓库检出运行，不部署到 /opt/Cy/services/system.d/nfos/

用途¶

把 nf.css 里“会显示不全”的可疑模式量化成计数 + 位置清单，供「改动前 / 改动后」对比。

源码 docstring（逐字引用）：

用途：把 nf.css 里的“会显示不全”的可疑模式量化成计数 + 位置清单，
      供「改动前 / 改动后」对比。输出 UTF-8 文本，直接重定向到文件。

审计内容分两块：

块	内容
1. CSS 模式计数	对 `--css` 文件统计 15 条模式：`overflow:hidden`、`overflow-x:hidden`、`overflow-y:hidden`、`overflow:auto\\|scroll`、`white-space:nowrap`、`text-overflow:ellipsis`、`height:<N>px (写死)`、`max-height:<N>px/vh`、`min-width:0`、`overflow-wrap\\|word-break`、`overflow-wrap:anywhere`、`grid-template repeat(N,1fr) 写死列数`、`grid-template auto-fit/auto-fill`、`white-space:pre-wrap`、`white-space:pre(非wrap)`；并输出文件字节数与 `sha256(前16)`
1b. 明细	四张行号清单：`nowrap 明细`、`ellipsis 明细`、`overflow:hidden 明细`、`写死 height 明细`
2. lint 底座（默认执行）	以子进程跑 `apps/web/tests/lint-layout.py --site index --json`，按 `R1/R2/R4/R6/R7` 列出命中；再跑一次 7 站点汇总，用于确认 7 份 css 同步后计数是否整齐 ×7

典型场景¶

改 nf.css（或同步 7 份站点 CSS）之前先跑一次存基线，改完再跑一次做逐项对比；
排查“内容被裁掉 / 长文本拖不出横向滚动条 / 右侧在屏外”一类显示完整性问题时，先用它把可疑模式定位到具体行号；
与 ui-delta.py（前后对比）、ui-keyrules.py（关键类最终生效声明）、ui-coverage.py（类覆盖率）联用，构成“无浏览器时的显示完整性证据链”。

用法与参数¶

源码 docstring 给出的用法（逐字引用，.scratch/ 为升级前旧路径；本页按新位置书写，路径参数不变）：

用法：
  python .scratch/ui-audit.py --css apps/web/index/css/nf.css --out .scratch/audit-before.txt

参数来自 argparse.ArgumentParser()（默认值逐字来自源码）：

参数	类型	默认值	说明
`--css`	字符串（文件路径）	`<repo>/apps/web/index/css/nf.css`（由 `ROOT` 拼接的绝对路径）	被审计的 CSS 文件
`--out`	字符串（文件路径）	`''`（空 = 写 stdout）	输出文件；给值时打印 `written: <path> (<N> bytes)`
`--no-lint`	开关（`store_true`）	`False`	为真时跳过 `lint-layout.py` 底座块，只输出第 1 块与明细

无参数时的默认行为：审计仓库默认的 apps/web/index/css/nf.css，执行 lint 底座（两次子进程：--site index 与 7 站点汇总），结果按 UTF-8 字节写 stdout（不落盘）。

默认路径是相对仓库根推导出的绝对路径；也就是说 --css 省略时不需要 cd 到任何目录，但仓库检出必须在场。若显式传 --css apps/web/index/css/nf.css 这类相对路径，则相对当前工作目录解析。

示例¶

改动前存基线、改动后存新档（推荐两次都落盘，便于 diff）：

python deploy/nfos/tools/ui-audit.py --css apps/web/index/css/nf.css --out .scratch/audit-before.txt

只做 CSS 模式计数、不依赖 lint-layout.py：

python deploy/nfos/tools/ui-audit.py --no-lint

期望输出形态（落盘时只打印一行；不给 --out 时输出正文到 stdout）：

written: .scratch/audit-before.txt (12345 bytes)

正文形如：

== 文件: apps/web/index/css/nf.css ==
字节数: ...  sha256(前16): ...
-- 模式计数 --
  white-space:nowrap                     123
  ...
-- lint-layout.py (site=index) 计数 --
  R1  ...
  合计 ...

情形	期望退出码
正常完成	`0`（源码未调用 `sys.exit`）
CSS 文件缺失 / `--out` 不可写	`1`（Python traceback）
不带 `--no-lint` 时 `lint-layout.py` 失败或输出非 JSON	`1`（`subprocess` 输出解析异常，Python traceback）

注意：“命中了多少条可疑模式”不影响退出码 —— 本工具是计数器/清单，不是断言器，不会因为计数高而失败。

依赖与权限¶

语言/版本：Python 3（#!/usr/bin/env python3）。
第三方依赖：无，标准库 argparse / io / os / re / sys / json / subprocess / hashlib。
仓库依赖：必需 —— dump_lint() 以 sys.executable 起子进程执行 <repo>/apps/web/tests/lint-layout.py（cwd=ROOT），并 import 其 JSON 输出。加 --no-lint 可去掉这一依赖（但默认 --css 仍由仓库根推导）。
权限：不需要 root；写权限仅用于 --out。

风险与注意事项¶

只读 CSS，只写 --out：工具本身不修改 nf.css，也不改任何仓库文件。若不传 --out，它只写 stdout，完全不落盘。
会起子进程：默认执行两次 lint-layout.py（捕获 stdout、cwd 为仓库根、env 注入 PYTHONIOENCODING=utf-8）。它不写报告到别处，但 lint-layout.py 自身的副作用（若有）会一并发生。
不依赖浏览器：审计是纯文本/正则统计，不能证明视觉上真的没被裁掉；它的价值是“把可疑模式定位到行号 + 给出可对比的数字”。
计数会包含注释里的字样（本工具不做注释剥离；ui-delta.py 才提供“剥离注释后计数”的口径）。因此与 ui-delta.py 的数字不应直接互相校验。
明细清单只覆盖 4 类模式（nowrap / ellipsis / overflow:hidden / 写死 height），其余模式的行号不在输出里。

回滚¶

本工具不部署到线上、不改线上系统；不改动任何被审计文件。

产出/改动位置：仅 --out 指定的文件（例如 .scratch/audit-before.txt）。
清理方式：

Remove-Item -Force .scratch/audit-before.txt

不给 --out 时无任何落盘物，无需清理；线上侧无需回滚。