uat-nonit-testcase

面向非 IT 用户的 UAT 测试用例构建器

生成1 个自包含 HTML 文件（无 CDN、无需构建，打开 file:// 仍可运行），作为面向业务用户的 UAT 文档。 总结自 Coteccons 薪资项目——以下规则都是付出代价换来的经验，不得跳过任何步骤。

内容

目的与背景

• **目的：**生成一个自包含、离线可用的 HTML 文件，作为面向非 IT 业务用户的 UAT 文档：按顺序排列、可通过 Ctrl+F 搜索编号的场景表格，明确检查/不检查的范围，附带逐步说明和已模糊处理 PII 的真实截图，以及通过/未通过标记 + 导出 Excel/CSV/PDF。
• 触发条件（何时使用）：“为非 IT 用户创建测试用例”、“业务 UAT 检查清单”、“C&B 测试场景”、“/uat-nonit-testcase”；业务用户（C&B、会计、运营）需要测试某个应用。
• **非目标：**不检查源系统（HRIS/ERP）数据——源数据不一致需单独记录，不计为 bug；不制作真实应用的模型图或 iframe；Agent 不得自行部署到公开托管平台；这不是面向开发人员的自动化测试套件（该场景使用 playwright-verify）。

思维模型

业务用户的原话 → 业务分组 + 检查/不检查的范围 → 真实代码/配置（公式、常量、列来源） → 预先计算的预期数值 → 按顺序排列的“分组-NN”场景 → 真实截图（模糊处理 PII） → 离线可用的 HTML → Playwright 测试 → 交付。

输入与输出约定

	字段	必填？	含义
输入	业务用户的原话	是	他们要检查的业务分组、不愿检查的内容、所需格式
输入	应用的真实代码/配置	是	屏幕 + 路由、公式、常量、每一列数据的来源
输入	用于运行应用并截图的权限（dev-token）	是	通过 Playwright auth bypass 获取真实屏幕截图
输入	项目 brand-kit	否	通过 CSS vars 设置 tokens bg/accent/amber
输出	llmwiki/html/DDMMYY-uat-checklist-<nhóm>.html	是	自包含 HTML 文件
输出	已模糊处理的 assets/uat-shots/*.png	对外分享时需要	仅包含已模糊处理且被页面引用的截图
输出	提供给用户的部署命令	需要托管时	! vercel deploy --prod --yes，由用户自行运行
输出	draft + index + wiki 日志	有 llmwiki 时	输出报告

规则与能力

核心原则（原文详见 Reference — 核心原则一节）：

• RULE-01 (MUST)：使用非技术性语言，采用正式的企业语气。
• RULE-02 (MUST)：在页面开头明确区分检查/不检查的范围。
• RULE-03 (MUST)：必须根据真实代码/配置预先计算预期数值。
• RULE-04 (MUST)：按顺序排列的场景表格是主要交付物。
• RULE-05 (MUST)：场景编号可通过 Ctrl+F 搜索：NHÓM-NN，使用等宽字体。
• RULE-06 (MUST)：默认只包含 5–6 个关键场景；不使用 ⭐/徽章/表情符号。
• RULE-07 (MUST)：免责声明使用醒目的琥珀色高亮，置于表格上方。
• RULE-08 (MUST)：使用真实屏幕截图，不使用模型图或 iframe。
• RULE-09 (MUST)：采用标准布局（主视觉区 → 2 个范围卡片 → 免责声明 → 表格 → 双栏）。

强制技术要求（原文详见 Reference — 强制技术要求一节）：

• RULE-10 (MUST)：完全离线可用：文件内使用纯 CSS，不得使用 Tailwind CDN。
• RULE-11 (MUST)：**<head> 必须完整：**包含 charset + viewport + 真实的 <title>。
• RULE-12 (MUST)：数字列使用 tabular-nums 对齐。
• RULE-13 (MUST)：为所有按钮和选择框提供键盘焦点环 :focus-visible。
• RULE-14 (MUST)：使用 try/catch 包裹 localStorage。
• RULE-15 (MUST)：通过/未通过状态 + 备注须保存到 store；对应行更改颜色，并显示计数徽章。
• RULE-16 (MUST)：提供 3 种导出方式：复制 TSV、带 BOM 的 CSV、通过 window.print() 导出 PDF，并强制使用白色背景和黑色文字。
• RULE-17 (MUST)：将截图传出内部网络前，先模糊处理 PII，再逐个区域裁剪检查。
• RULE-18 (MUST)：Agent 不得自行部署到公开托管平台——提供一条命令让用户自行运行。
• RULE-19 (MUST)：使用 Playwright 进行 auth bypass 后截图；如果 API 返回 401，则使用 ctx.route 返回 []（不要返回 {}）。
• 能力：读取项目代码/配置；运行带 auth bypass 的无头浏览器并截图；处理图像（模糊/裁剪）；编写 HTML 文件、截图和 wiki draft。不得发布到公开托管平台。

失败边界

• 尚未获得业务用户的原话／不清楚业务群体 → 撰写前先 clarify。
• 在代码／配置中找不到真实公式／常量 → 该预期数值标记为 blocked，不得编造数值。
• 无法截取真实屏幕（auth/SSO）→ 标记为 partial，不得用 mockup 或 iframe 替代。
• 模糊处理后的图片经裁剪检查仍泄露 PII → 标记为 failed，重新模糊处理；不得交付不干净的图片。
• Playwright 离线测试出现 JS error，或切换／打印功能失效 → 标记为 failed，修复后再交付。
• 需要公开托管 → 止步于向用户提供部署命令（这不是错误）。

HOW

主要工作流

步骤	类型	输入	操作	输出／退出条件	失败／后续
W01	判断	用户原话	提取业务群体、检查／不检查范围、所需格式	范围	缺少信息 → clarify
W02	确定性	代码库	扫描真实代码／配置：屏幕 + route、公式、常量、列来源	来源表	未找到 → 该项目标记为 blocked
W03	效果	可运行的 app	使用 Playwright auth bypass 截取真实屏幕；如需对外分享，则模糊处理 PII（B01）	图片	模糊处理后仍泄露 → 重做
W04	判断	范围、公式	编写顺序脚本，预先计算预期数值，选出 5–6 个重点案例	脚本表	—
W05	效果	脚本、图片	按标准布局 + 必需技术构建 HTML；如有 brand-kit，则按品牌规范设计	HTML 文件	—
W06	确定性	HTML 文件	Playwright 测试：file:// + 阻止 100% 外部网络 → 0 个 JS error，切换、选择、打印为 PDF	PASS	FAIL → 修复后重复 W06
W07	效果	结果	部署（B02）+ 如有 llmwiki，则记录 wiki 草稿／索引／日志	交付	—

各步骤详情（W01–W07 的事实来源）：

6 步流程

1. 获取业务用户的原话 → 提取：他们要检查的业务群体、拒绝检查的内容、 他们需要的格式（表格！）。
2. 扫描真实代码／配置（Explore agent）：屏幕 + route、公式、常量、各数据列的来源。
3. 截取相关屏幕的真实画面（Playwright，auth bypass）→ 如需对外分享，则模糊处理 PII。
4. 按表格模板编写顺序脚本，预先计算预期数值，选出 5–6 个重点案例。
5. 按标准布局 + 上文必需技术构建 HTML。如项目有 brand-kit，则遵循项目品牌规范 （tokens：通过 CSS vars 设置 bg/accent/amber-warning——更换品牌只需修改 :root）。
6. 交付前使用 Playwright 测试：打开 file:// + 阻止 100% 外部网络 → 0 个 JS error，切换 5↔N 行，选择 Đạt/Không đạt，打印为 PDF 文件。

输出

• llmwiki/html/DDMMYY-uat-checklist-<nhóm>.html（+ 如需对外分享，则使用已模糊处理的 assets/uat-shots/*.png）
• 如有 llmwiki，则按项目的循环流程记录 wiki（草稿 + 索引 + 日志）。

分支

ID	类型	条件	行为	跳过／失败	返回
B01	conditional_required	图片将分享到内网之外	模糊处理 PII（PIL GaussianBlur ≥18）+ 逐个区域裁剪检查；只保留已模糊处理且已被引用的图片	仅供内部使用 → 跳过模糊处理	W04
B02	user_optional	需要公开托管	agent 模糊处理并打包 /tmp/<deploy-dir>，向用户提供由其自行运行的 vercel deploy 命令	agent 不自行部署（RULE-18）	结束
B03	recovery	截图时 API 使用 dev-token 返回 401	ctx.route 返回 []（而不是 {}）	—	W03

验证与停止条件

确定性检查：Playwright 在阻止 100% 外部网络的情况下打开 file:// → 0 个 JS error，切换 5↔N 行正常运行，选择 Đạt/Không đạt 时颜色 + 计数 badge 会变化，并能打印为 PDF 文件。需要人工审核：将预期数值与真实配置屏幕交叉核对；通过裁剪检查目视确认图片模糊处理效果。两项都完成后才能交付。

示例

• 正向： C&B 想要“工资核对清单表格” → 扫描配置，得出 BHXH 上限为 46,8tr → TRICH-02 场景中，预期 50tr 工资对应 3.744.000 → 生成包含 6 个关键 case 的 HTML，设有“显示全部 N 个场景”按钮，离线测试无 JS error → llmwiki/html/DDMMYY-uat-checklist-luong.html。
• 边界/失败： 用户要求“把真实应用嵌入页面，方便使用” → iframe 因 Microsoft SSO + cookie partitioning 无法运行 → 拒绝使用 iframe，改用真实截图 +“打开应用（新窗口）”按钮。
• 边界： 图片模糊处理后，溢出列外的姓名尾部仍然可见 → 裁剪检查时发现 → 打包前重新模糊处理。

参考 — 核心原则（根据真实用户反馈总结）

1. 使用非技术语言，采用正式的企业语气。 不用 emoji、代号、文件路径或 API 名称。使用“测试目录”“通过 / 未通过”（UI 上不用 Pass/Fail）、“系统自动计算”（不用“引擎”）。数据来源只标明名称：来自 HRIS / 导入 Excel / 用户输入 / 系统自动计算——不解释具体机制。
2. 在页面顶部立即明确区分检查范围与非检查范围。 用 2 张卡片 ✓/✗：应用自动计算的内容 + 用户输入的内容需要检查；从源系统（HRIS/ERP）带入的数据无需检查——“如果和源数据一致，直接导出源数据使用就行，何必再检查”。源数据偏差需单独记录，不计为 bug。
3. 预期数值必须根据真实代码/配置预先计算。 读取后端/配置，获取真实公式和常量（例如 BHXH 上限为 46,8tr → 50tr 工资对应准确的 3.744.000）。一个具体数值胜过十行描述。记录前先与真实配置界面交叉核对。
4. 按顺序排列的场景表格是主要交付物——业务用户想要“表格清单”，不想要漂亮网页。标准列：编号（Ctrl+F） | 场景 | 界面 | 操作步骤 | 预期结果 | 结果 | 备注。场景顺序 = 实际操作顺序：设置 → 输入数据 → 计算 → 各项业务 → 汇总 → 结账。
5. 场景编号可通过 Ctrl+F 搜索：分组-NN monospace（LUONG-01、TRICH-02、CHOT-01）。将其作为报告 bug 时的通用语言（“TRICH-02 未通过 + 截图”）。
6. 默认只显示 5–6 个覆盖所有业务组的关键场景，并提供“显示全部 N 个场景”按钮以展开。在展开视图中，关键 case 通过浅色背景 + 左侧强调色竖条区分——不要使用 ⭐/徽章/emoji（企业旧系统环境）。
7. 覆盖免责声明（琥珀色高亮，置于表格上方）： 超出标准的复杂公式 → 在 Excel 外计算，然后直接覆盖对应单元格的值（双击 → 输入 → 连同原因一起保存）；系统会保存修改前后记录并支持撤销——参见 OVR 场景。
8. 使用真实屏幕截图，不用 mockup，不用 iframe。
   • 虚构数字的 mockup → 用户会问“看起来都不真实，做这个有什么用”。弃用。
   • 嵌入真实应用的 iframe → 因 SSO（Microsoft 会阻止在 frame 中登录）+ cookie partitioning 而无法运行。弃用。
   • 最终方案：真实截图（Playwright + dev-token bypass），右侧设置粘性图片面板，每个项目都设有按钮，可将图片切换为对应界面；提供“打开应用（新窗口）”按钮以进行实际操作。
9. 标准布局： 简短的 hero → 2 张范围卡片 → 免责声明 → 场景表格（附“复制到 Excel”/“下载 CSV”/“导出 PDF”按钮）→ 2 列分栏：左侧为按业务组排列的逐步操作面板（步骤编号、 “预期值”输入框、复选框），右侧为粘性图片面板。

参考 — 必须掌握的技术（踩坑踩够了）

• 彻底离线可用：在文件中使用纯 CSS，禁止使用 Tailwind CDN（网络受限 = 页面空白）。 可以使用 Google Fonts，但必须提供回退字体栈。
• <head> 必须完整： <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1">
  • 真正的 <title>。缺少 viewport → 业务人员在小屏笔记本电脑/平板上查看时，表格会横向溢出。
• 数字列使用 tabular-nums 对齐（td.num, .exp-val{font-variant-numeric:tabular-nums}）——预期数值 （工资、BHXH 上限……）必须对齐，方便快速核查；比例字体会让数字列错位，难以发现误差。
• 键盘焦点环： 所有按钮（复制 Excel / 下载 CSV / 导出 PDF /“显示全部”）+ 达标/不达标选择框都需要 :focus-visible{outline:2px solid var(--accent);outline-offset:2px}——业务人员经常使用 Tab/Enter 操作，失去焦点环就会找不到位置。（用 :focus:not(:focus-visible){outline:none} 去除鼠标点击产生的焦点环。）
• localStorage 使用 try/catch 包装——file:// 可能会阻止存储，未处理会导致整个脚本崩溃：

  const store={get(k){try{return localStorage.getItem(k)}catch(_){return null}},
               set(k,v){try{localStorage.setItem(k,v)}catch(_){}}};
  

• 达标/不达标状态 + 备注保存到 store，行颜色随之变化（达标 = 浅色 accent，不达标 = amber）， 徽标计数为 达标 x · 不达标 y / N。
• 提供 3 种导出方式：复制 TSV（可直接粘贴到 Excel，使用 execCommand 回退方案）、带 BOM  的 CSV（Excel VN 可正确读取 UTF-8）、PDF = 自动展开全部内容 → window.print() + @media print（隐藏按钮/图片/分栏，强制白底黑字——深色背景打印出来会一团糟）。
• 将图片发出内网前先模糊处理 PII（在原始 2400px 图片上使用 PIL GaussianBlur ≥18）： 员工编号列 + 姓名（包括姓名列中的代码 chip）、录入/审批/修改人员列、侧边栏角落的账号 chip。 模糊处理后必须重新裁切并逐个区域检查——姓名尾部超出列宽、模糊边缘上露出首行，是两种典型错误。 只部署已模糊处理且已通过参考页面核验的图片；从交付包中删除多余图片。
• Agent 不会自行部署到公开托管服务——分类器会拦截。流程：Agent 模糊处理并打包 （/tmp/<deploy-dir> 中包含 index.html），然后提供一条命令 ! vercel deploy --prod --yes 让用户自行运行。
• 使用 Playwright 截屏：通过 addInitScript/addCookies 设置 localStorage（accessToken/user/expiry）+ 已认证 cookie；如果某个 API 使用 dev-token 返回 401，则通过 ctx.route 返回 []（不要返回 {}——页面调用 .forEach 会崩溃）。

交付 — 输出报告

完成后，写入草稿 llmwiki/wiki/sources/draft/DDMMYY-<ten>.md（Type: draft, Status: proposed, Tags: uat-nonit-testcase, output-report）+ 更新 wiki/index.md 和 wiki/log.md——遵循本套件中其他技能的 output-report 标准。