uat-nonit-testcase

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

UAT Test-case Builder cho người dùng NON-IT

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

Sinh 1 file HTML tự chứa (không CDN, không build, mở
file://
vẫn chạy) làm tài liệu UAT cho business user. Đúc kết từ dự án Payroll Coteccons — các quy tắc dưới đây là bài học đã trả giá, KHÔNG bỏ bước.
生成 1 个自包含的 HTML 文件(不依赖 CDN、无需构建,通过
file://
打开仍可运行),用作面向业务用户的 UAT 文档。该实现总结自 Coteccons Payroll 项目——以下规则均来自实际付出代价后总结的经验,不得省略任何步骤。

WHAT

内容

Purpose và context

目的与背景

  • Purpose: sinh MỘT file HTML tự chứa, offline-proof làm tài liệu UAT cho business user non-IT: bảng kịch bản tuần tự có mã Ctrl+F, phạm vi check/không-check, step-by-step kèm ảnh thật đã blur PII, Đạt/Không đạt + xuất Excel/CSV/PDF.
  • Trigger (when to use): "tạo test case cho non-IT", "checklist UAT cho nghiệp vụ", "kịch bản kiểm thử cho C&B", "/uat-nonit-testcase"; người dùng nghiệp vụ (C&B, kế toán, vận hành) cần kiểm thử một app.
  • Non-goals: không kiểm dữ liệu hệ thống nguồn (HRIS/ERP) — sai lệch nguồn ghi riêng, không tính bug; không mockup hay iframe app thật; agent KHÔNG tự deploy ra hosting công khai; không phải bộ test tự động cho dev (đó là
    playwright-verify
    ).
  • 目的:生成一个自包含、离线可用的 HTML 文件,作为非 IT 业务用户的 UAT 文档:包含可通过 Ctrl+F 搜索代码的顺序场景表、依据数据源划分的检查/不检查范围、附带已模糊处理 PII 的真实屏幕截图的分步说明,以及“通过/不通过”状态和 Excel/CSV/PDF 导出。
  • 触发条件(何时使用):“为 non-IT 创建测试用例”“业务流程 UAT 检查清单”“C&B 测试场景”“/uat-nonit-testcase”;C&B、会计、运营等业务用户需要测试某个应用时使用。
  • **非目标:**不检查源系统数据(HRIS/ERP)——源数据差异单独记录,不计为 bug;不使用 mockup,也不使用 iframe 嵌入真实应用;Agent 不自行部署到公共托管环境;这不是面向开发人员的自动化测试套件(那属于
    playwright-verify
    )。

Mental model

思维模型

lời business user nguyên văn → nhóm nghiệp vụ + phạm vi check/không-check → code/config thật (công thức, hằng số, nguồn cột) → số kỳ vọng tính sẵn → kịch bản tuần tự NHÓM-NN → ảnh thật (blur PII) → HTML offline-proof → Playwright test → giao
.
业务用户原话 → 业务分组 + 检查/不检查范围 → 真实代码/配置(公式、常量、列来源)→ 预先计算的预期数值 → 按分组编号排序的场景 → 真实截图(模糊 PII)→ 离线可用 HTML → Playwright 测试 → 交付
。

Input và output contract

输入与输出约定

FieldRequired?Ý nghĩa
Inlời business user nguyên văncónhóm nghiệp vụ họ check, cái họ từ chối check, định dạng họ muốn
Incode/config thật của appcómàn hình + route, công thức, hằng số, nguồn từng cột dữ liệu
Inquyền chạy app để chụp (dev-token)cóảnh màn hình thật qua Playwright auth bypass
Inbrand-kit dự ánkhôngtokens bg/accent/amber qua CSS vars
Out
llmwiki/html/DDMMYY-uat-checklist-<nhóm>.html
cófile HTML tự chứa
Out
assets/uat-shots/*.png
đã blur
nếu share ngoàichỉ ảnh đã blur + được trang tham chiếu
Outlệnh deploy cho usernếu cần hosting
! vercel deploy --prod --yes
để user tự chạy
Outdraft + index + log wikinếu có llmwikioutput report
字段是否必填含义
输入业务用户原话是用户检查的业务分组、拒绝检查的内容以及期望格式
输入应用的真实代码/配置是页面与 route、公式、常量及每列数据的来源
输入运行应用的权限(dev-token)是通过 Playwright auth bypass 截取真实屏幕截图
输入项目 brand-kit否通过 CSS vars 设置 bg/accent/amber token
输出
llmwiki/html/DDMMYY-uat-checklist-<nhóm>.html
是自包含的 HTML 文件
输出
assets/uat-shots/*.png
,已模糊处理
对外分享时仅保留已模糊处理并被页面引用的图片
输出供用户执行的部署命令需要托管时
! vercel deploy --prod --yes
,由用户自行运行
输出wiki draft + index + log存在 llmwiki 时输出报告

Rules và capabilities

规则与能力

Nguyên tắc cốt lõi (chi tiết nguyên văn ở mục Reference — Nguyên tắc cốt lõi):
  • RULE-01 (MUST): Ngôn ngữ phi kỹ thuật, giọng formal doanh nghiệp.
  • RULE-02 (MUST): Phạm vi check / không-check tách bạch ngay đầu trang.
  • RULE-03 (MUST): Số kỳ vọng phải TÍNH SẴN từ code/config thật.
  • RULE-04 (MUST): Bảng kịch bản tuần tự là deliverable chính.
  • RULE-05 (MUST): Mã kịch bản Ctrl+F được:
    NHÓM-NN
    monospace.
  • RULE-06 (MUST): Mặc định chỉ 5–6 kịch bản trọng yếu; không ⭐/badge/emoji.
  • RULE-07 (MUST): Disclaimer ghi đè (highlight amber, đặt trên bảng).
  • RULE-08 (MUST): Ảnh màn hình THẬT, không mockup, không iframe.
  • RULE-09 (MUST): Layout chuẩn (hero → 2 card phạm vi → disclaimer → bảng → split 2 cột).
Kỹ thuật bắt buộc (chi tiết nguyên văn ở mục Reference — Kỹ thuật bắt buộc):
  • RULE-10 (MUST): Offline-proof tuyệt đối: CSS thuần trong file, KHÔNG Tailwind CDN.
  • RULE-11 (MUST):
    <head>
    đủ:
    charset + viewport +
    <title>
    thật.
  • RULE-12 (MUST): Cột số căn theo
    tabular-nums
    .
  • RULE-13 (MUST): Focus ring bàn phím
    :focus-visible
    cho mọi nút + ô chọn.
  • RULE-14 (MUST):
    localStorage
    bọc try/catch
    .
  • RULE-15 (MUST): Trạng thái Đạt/Không đạt + ghi chú lưu store, dòng đổi màu, badge đếm.
  • RULE-16 (MUST): Xuất 3 kiểu: Copy TSV, CSV có BOM, PDF qua
    window.print()
    ép nền trắng chữ đen.
  • RULE-17 (MUST): Blur PII trước khi đưa ảnh ra khỏi mạng nội bộ, rồi crop-soi lại từng vùng.
  • RULE-18 (MUST): Agent không tự deploy ra hosting công khai — đưa user 1 lệnh tự chạy.
  • RULE-19 (MUST): Chụp màn hình bằng Playwright với auth bypass; API 401 thì
    ctx.route
    trả
    []
    (KHÔNG
    {}
    ).
  • Capabilities: đọc code/config dự án; chạy trình duyệt headless có auth bypass để chụp; xử lý ảnh (blur/crop); ghi file HTML + ảnh + wiki draft. Không publish ra hosting công khai.
核心原则(原文详情见“参考 — 核心原则”):
  • RULE-01 (MUST):使用非技术语言和企业正式语气。
  • RULE-02 (MUST):在页面开头明确区分检查/不检查范围。
  • RULE-03 (MUST):预期数值必须根据真实代码/配置预先计算。
  • RULE-04 (MUST):顺序场景表是主要交付物。
  • RULE-05 (MUST):场景代码支持 Ctrl+F 搜索:使用
    GROUP-NN
    monospace。
  • RULE-06 (MUST):默认仅展示 5–6 个关键场景;不使用 ⭐/badge/emoji。
  • RULE-07 (MUST):使用醒目的琥珀色高亮免责声明,并将其放在表格上方。
  • RULE-08 (MUST):使用真实屏幕截图,不使用 mockup,也不使用 iframe。
  • RULE-09 (MUST):采用标准布局:hero 区 → 2 张范围卡片 → 免责声明 → 表格 → 双栏布局。
强制技术要求(原文详情见“参考 — 强制技术要求”):
  • RULE-10 (MUST):必须完全离线可用:CSS 直接写入文件,不得使用 Tailwind CDN。
  • RULE-11 (MUST):
    <head>
    必须完整
    :包含 charset、viewport 和真实的
    <title>
    。
  • RULE-12 (MUST):数字列使用
    tabular-nums
    对齐。
  • RULE-13 (MUST):所有按钮和选择框都必须具备键盘 focus ring:使用
    :focus-visible
    。
  • RULE-14 (MUST):
    localStorage
    必须包裹在 try/catch 中。
  • RULE-15 (MUST):“通过/不通过”状态和备注必须保存在 store 中,对应行变更颜色,并显示计数徽章。
  • RULE-16 (MUST):支持 3 种导出方式:复制 TSV、导出带 BOM 的 CSV、通过
    window.print()
    导出 PDF 并强制使用白底黑字。
  • RULE-17 (MUST):将图片带出内部网络之前必须模糊处理 PII,然后逐个区域裁剪放大复查。
  • RULE-18 (MUST):Agent 不自行部署到公共托管环境——只向用户提供 1 条自行执行的命令。
  • RULE-19 (MUST):使用 Playwright 配合 auth bypass 截取屏幕;如果 API 返回 401,则由
    ctx.route
    返回
    []
    (不得返回
    {}
    )。
  • 能力:读取项目代码/配置;运行带 auth bypass 的 headless 浏览器进行截图;处理图片(模糊/裁剪);写入 HTML 文件、图片和 wiki draft。不得发布到公共托管环境。

Failure boundaries

失败边界

  • Chưa có lời business user / không rõ nhóm nghiệp vụ → clarify trước khi soạn.
  • Không tìm được công thức/hằng số thật trong code/config → blocked cho số kỳ vọng đó, không bịa số.
  • Không chụp được màn hình thật (auth/SSO) → partial, không thay bằng mockup hay iframe.
  • Ảnh sau blur còn lộ PII khi crop-soi → failed, blur lại; không giao ảnh chưa sạch.
  • Test Playwright offline có JS error hoặc toggle/print hỏng → failed, sửa trước khi giao.
  • Cần hosting công khai → dừng ở lệnh deploy cho user (không phải lỗi).
  • 尚未获得业务用户原话或业务分组不明确 → 编制前必须先 clarify。
  • 在代码/配置中找不到真实公式/常量 → 对应预期数值标记为 blocked,不得编造数字。
  • 无法截取真实屏幕画面(auth/SSO)→ 标记为 partial,不得用 mockup 或 iframe 替代。
  • 模糊处理后的图片在裁剪放大检查时仍暴露 PII → 标记为 failed,必须重新模糊处理;不得交付尚未清理干净的图片。
  • Playwright 离线测试出现 JS error,或 toggle/print 功能异常 → 标记为 failed,修复后才能交付。
  • 需要公共托管 → 停在向用户提供部署命令的步骤(这不属于错误)。

HOW

执行方式

Main workflow

主工作流

StepTypeInputsActionOutputs/exitFailure/next
W01judgmentlời user nguyên vănRút nhóm nghiệp vụ, phạm vi check / không-check, định dạng muốnphạm vithiếu → clarify
W02deterministiccodebaseQuét code/config thật: màn hình + route, công thức, hằng số, nguồn cộtbảng nguồnkhông thấy → blocked cho mục đó
W03effectapp chạy đượcChụp màn hình thật bằng Playwright auth bypass; blur PII nếu share ngoài (B01)ảnhblur lộ → làm lại
W04judgmentphạm vi, công thứcSoạn kịch bản tuần tự, tính sẵn số kỳ vọng, chọn 5–6 case trọng yếubảng kịch bản—
W05effectkịch bản, ảnhBuild HTML theo layout chuẩn + kỹ thuật bắt buộc; brand theo brand-kit nếu cófile HTML—
W06deterministicfile HTMLTest Playwright:
file://
+ chặn 100% mạng ngoài → 0 JS error, toggle, select, print-to-pdf
PASSFAIL → sửa, lặp W06
W07effectkết quảDeploy (B02) + ghi wiki draft/index/log nếu có llmwikigiao—
Chi tiết từng bước (nguồn chân lý cho W01–W07):
步骤类型输入操作输出/退出条件失败/下一步
W01judgment用户原话提取业务分组、检查/不检查范围及期望格式范围缺失 → clarify
W02deterministiccodebase扫描真实代码/配置:页面与 route、公式、常量、列来源来源表未找到 → 对应项目标记 blocked
W03effect可运行的应用使用 Playwright auth bypass 截取真实屏幕;对外分享时模糊处理 PII(B01)图片模糊后仍暴露 → 重新处理
W04judgment范围、公式编写顺序场景、预先计算预期数值,并选择 5–6 个关键用例场景表—
W05effect场景、图片按标准布局和强制技术要求构建 HTML;如果存在 brand-kit,则应用品牌样式HTML 文件—
W06deterministicHTML 文件使用 Playwright 测试:通过
file://
打开并拦截 100% 外部网络,要求 0 JS error,并验证 toggle、select 和 print-to-pdf
PASSFAIL → 修复并重复 W06
W07effect结果按 B02 处理部署;如果存在 llmwiki,则写入 wiki draft/index/log交付—
以下为各步骤的详细信息(W01–W07 的唯一事实来源):

Quy trình 6 bước

6 步流程

  1. Lấy lời business user nguyên văn → rút ra: nhóm nghiệp vụ họ check, cái họ từ chối check, định dạng họ muốn (bảng!).
  2. Quét code/config thật (Explore agent): màn hình + route, công thức, hằng số, nguồn từng cột dữ liệu.
  3. Chụp màn hình thật các màn liên quan (Playwright, auth bypass) → blur PII nếu sẽ share ngoài.
  4. Soạn kịch bản tuần tự theo template bảng, tính sẵn số kỳ vọng, chọn 5–6 case trọng yếu.
  5. Build HTML theo layout chuẩn + kỹ thuật bắt buộc ở trên. Brand theo brand-kit dự án nếu có (tokens: bg/accent/amber-cảnh-báo qua CSS vars — đổi brand chỉ sửa
    :root
    ).
  6. Test bằng Playwright trước khi giao: mở
    file://
    + chặn 100% mạng ngoài → 0 JS error, toggle 5↔N dòng, select Đạt/Không đạt, print-to-pdf ra file.
  1. 获取业务用户原话 → 提取:用户检查的业务分组、拒绝检查的内容、期望格式(表格)。
  2. 扫描真实代码/配置(Explore Agent):页面与 route、公式、常量、每列数据的来源。
  3. 截取真实屏幕画面中的相关页面(Playwright、auth bypass)→ 如果将对外分享,则模糊处理 PII。
  4. 按照表格模板编写顺序场景,预先计算预期数值,并选择 5–6 个关键用例。
  5. 构建 HTML,遵循上述标准布局和强制技术要求。如果存在项目 brand-kit,则应用品牌样式 (token:bg/accent/amber-warning 通过 CSS vars 设置——更换品牌时只需修改
    :root
    )。
  6. 交付前使用 Playwright 测试:通过
    file://
    打开并拦截 100% 外部网络 → 0 JS error,切换 5↔N 行, 选择“通过/不通过”,并将 print-to-pdf 输出为文件。

Output

输出

  • llmwiki/html/DDMMYY-uat-checklist-<nhóm>.html
    (+
    assets/uat-shots/*.png
    đã blur nếu share ngoài)
  • Ghi wiki theo loop của dự án (draft + index + log) nếu có llmwiki.
  • llmwiki/html/DDMMYY-uat-checklist-<nhóm>.html
    (如果对外分享,还应包含已模糊处理的
    assets/uat-shots/*.png
    )
  • 如果存在 llmwiki,则按照项目 loop 写入 wiki(draft + index + log)。

Branches

分支

IDKindGuardHành viSkip / failureRejoin
B01conditional_requiredảnh sẽ share ra ngoài mạng nội bộblur PII (PIL GaussianBlur ≥18) + crop-soi lại từng vùng; chỉ giữ ảnh đã blur + được tham chiếuchỉ dùng nội bộ → skip blurW04
B02user_optionalcần đưa lên hosting công khaiagent blur + đóng gói
/tmp/<deploy-dir>
, đưa user lệnh vercel deploy tự chạy
agent không tự deploy (RULE-18)kết thúc
B03recoveryAPI trả 401 với dev-token khi chụp
ctx.route
trả
[]
(không
{}
)
—W03
ID类型条件行为跳过/失败处理汇合点
B01conditional_required图片将共享至内部网络之外模糊处理 PII(PIL GaussianBlur ≥18),再逐个区域裁剪放大复查;仅保留已模糊处理并被引用的图片仅供内部使用 → 跳过模糊处理W04
B02user_optional需要发布至公共托管环境Agent 模糊处理并打包
/tmp/<deploy-dir>
,向用户提供自行执行 vercel deploy 的命令
Agent 不自行部署(RULE-18)结束
B03recovery使用 dev-token 截图时 API 返回 401由
ctx.route
返回
[]
(不得返回
{}
)
—W03

Validation và stopping

验证与停止条件

Tất định: Playwright mở
file://
với mạng ngoài bị chặn 100% → 0 JS error, toggle 5↔N dòng chạy, chọn Đạt/Không đạt đổi màu + badge đếm, print-to-pdf ra file. Cần review: số kỳ vọng đối chiếu chéo màn hình cấu hình thật; ảnh blur crop-soi bằng mắt. Chỉ giao khi cả hai xong.
确定性验证:Playwright 通过
file://
打开文件并拦截 100% 外部网络 → 0 JS error;能够切换 5↔N 行;选择“通过/不通过”后行颜色变化且计数徽章更新;能够通过 print-to-pdf 生成文件。人工复核:将预期数值与真实配置页面交叉核对;通过肉眼对模糊处理后的图片进行裁剪放大检查。只有两项验证均完成后才能交付。

Examples

示例

  • Positive: C&B muốn "list dạng bảng kiểm lương tháng" → quét config ra trần BHXH 46,8tr → kịch bản
    TRICH-02
    lương 50tr kỳ vọng đúng 3.744.000 → HTML 6 case trọng yếu, nút "Hiển thị đầy đủ N kịch bản", test offline 0 JS error →
    llmwiki/html/DDMMYY-uat-checklist-luong.html
    .
  • Boundary/failure: user đòi "nhúng app thật vào trang cho tiện" → iframe chết vì SSO Microsoft + cookie partitioning → từ chối iframe, dùng ảnh chụp thật + nút "Mở ứng dụng (cửa sổ mới)".
  • Boundary: ảnh sau blur còn lộ đuôi tên tràn cột → crop-soi phát hiện → blur lại trước khi đóng gói.
  • **正向:**C&B 希望获得“月度工资表形式的清单”→ 从配置中扫描出 BHXH 上限为 4680 万 → 场景
    TRICH-02
    :工资为 5000 万,预期结果正确值为 3,744,000 → 生成包含 6 个关键场景的 HTML,带有“显示全部 N 个场景”按钮,离线测试 0 JS error →
    llmwiki/html/DDMMYY-uat-checklist-luong.html
    。
  • **边界/失败:**用户要求“把真实应用嵌入页面以便操作”→ iframe 因 Microsoft SSO + cookie partitioning 而失效 → 拒绝使用 iframe,改用真实截图 + “打开应用(新窗口)”按钮。
  • **边界:**模糊处理后的截图仍在溢出列中暴露姓名尾部 → 通过裁剪放大检查发现 → 打包前再次模糊处理。

Reference — Nguyên tắc cốt lõi (học từ phản hồi người dùng thật)

参考 — 核心原则(总结自真实用户反馈)

  1. Ngôn ngữ phi kỹ thuật, giọng formal doanh nghiệp. Không emoji, không codename, không file path, không tên API. "Danh mục kiểm thử", "Đạt / Không đạt" (không Pass/Fail trên UI), "hệ thống tự tính" (không "engine"). Nguồn dữ liệu chỉ gọi tên:
    từ HRIS
    /
    import Excel
    /
    người dùng nhập
    /
    hệ thống tự tính
    — không giải thích cơ chế.
  2. Phạm vi check / không-check tách bạch ngay đầu trang. 2 card ✓/✗: cái app tự tính + người dùng nhập thì CHECK; dữ liệu hệ thống nguồn (HRIS/ERP) mang sang thì KHÔNG — "nếu y như nguồn thì xuất nguồn ra dùng, kiểm lại làm gì". Sai lệch dữ liệu nguồn ghi nhận riêng, không tính bug.
  3. Số kỳ vọng phải TÍNH SẴN từ code/config thật. Đọc backend/config lấy công thức + hằng số thật (vd trần BHXH 46,8tr → lương 50tr ra đúng 3.744.000). Một con số cụ thể đáng giá hơn mười dòng mô tả. Đối chiếu chéo với màn hình cấu hình thật trước khi ghi.
  4. Bảng kịch bản tuần tự là deliverable chính — business user muốn "list dạng bảng", không muốn trang web đẹp. Cột chuẩn:
    Mã (Ctrl+F) | Kịch bản | Màn hình | Bước thực hiện | Kết quả mong đợi | KQ | Ghi chú
    . Thứ tự kịch bản = thứ tự làm thật: setup → dữ liệu vào → tính → từng nghiệp vụ → tổng → khóa sổ.
  5. Mã kịch bản Ctrl+F được:
    NHÓM-NN
    monospace (
    LUONG-01
    ,
    TRICH-02
    ,
    CHOT-01
    ). Dùng làm ngôn ngữ chung khi báo bug ("TRICH-02 fail + ảnh chụp").
  6. Mặc định chỉ 5–6 kịch bản trọng yếu phủ đủ các nhóm nghiệp vụ, nút "Hiển thị đầy đủ N kịch bản" để mở rộng. Khi mở rộng, case trọng yếu phân biệt bằng màu nền nhạt + thanh trái accent — KHÔNG dùng ⭐/badge/emoji (môi trường doanh nghiệp legacy).
  7. Disclaimer ghi đè (highlight amber, đặt trên bảng): công thức phức tạp ngoài chuẩn → tính ngoài Excel rồi ghi đè trực tiếp giá trị vào ô tương ứng (nhấp đúp → nhập → lưu kèm lý do); hệ thống lưu vết trước/sau + hoàn tác — tham chiếu kịch bản OVR.
  8. Ảnh màn hình THẬT, không mockup, không iframe.
    • Mockup số giả → user hỏi "không giống thật thì lấy ra làm gì". Bỏ.
    • Iframe app thật → chết vì SSO (Microsoft chặn login trong frame) + cookie partitioning. Bỏ.
    • Chốt: ảnh chụp thật (Playwright + dev-token bypass), panel ảnh sticky bên phải, nút tại mỗi mục đổi ảnh sang đúng màn hình; nút "Mở ứng dụng (cửa sổ mới)" cho thao tác thật.
  9. Layout chuẩn: hero ngắn → 2 card phạm vi → disclaimer → bảng kịch bản (+nút Sao chép Excel / Tải CSV / Xuất PDF) → split 2 cột: trái panel step-by-step theo nhóm nghiệp vụ (bước đánh số, ô "Giá trị kỳ vọng", checkbox), phải ảnh sticky.
  1. 使用非技术语言和企业正式语气。 不使用 emoji、codename、file path 或 API 名称。UI 中使用“测试项”“通过/不通过”(不要使用 Pass/Fail)、“系统自动计算”(不要使用“engine”)。数据源只按名称称呼:
    从 HRIS 导入
    /
    导入 Excel
    /
    用户输入
    /
    系统自动计算
    ——不解释内部机制。
  2. 在页面开头明确区分检查/不检查范围。 使用 2 张 ✓/✗ 卡片:应用自动计算和用户输入属于检查范围;从源系统(HRIS/ERP)迁移而来的数据不属于检查范围——“如果与源系统一致,还要导出源数据再检查,有什么意义”。源数据差异应单独记录,不计为 bug。
  3. 预期数值必须根据真实代码/配置预先计算。 读取 backend/config 获取真实公式和常量 (例如 BHXH 上限为 4680 万,则工资为 5000 万时应得到 3,744,000)。一个具体数字比十行描述更有价值。 写入前必须与真实配置页面交叉核对。
  4. 顺序场景表是主要交付物——业务用户需要的是“表格形式的清单”,而不是一个漂亮的网页。标准列:
    代码 (Ctrl+F) | 场景 | 页面 | 操作步骤 | 预期结果 | 结果 | 备注
    。场景顺序 = 实际执行顺序:准备 → 输入数据 → 计算 → 逐项业务 → 汇总 → 锁定账套。
  5. 场景代码支持 Ctrl+F 搜索:使用
    GROUP-NN
    monospace(
    LUONG-01
    、
    TRICH-02
    、
    CHOT-01
    )。将其作为报告 bug 时使用的共同标识(“TRICH-02 fail + 截图”)。
  6. 默认仅展示 5–6 个关键场景,覆盖所有业务分组,并通过“显示全部 N 个场景”按钮展开。展开后,关键场景使用 浅色背景 + accent 左侧竖条加以区分——不得使用 ⭐/badge/emoji(企业旧版环境)。
  7. **免责声明使用醒目的琥珀色高亮,并放在表格上方:**对于不符合标准的复杂公式 → 在 Excel 外部计算后,直接覆盖对应单元格中的值(双击 → 输入 → 保存并附上原因);系统保存前后值并支持撤销——参考 OVR 场景。
  8. 必须使用真实屏幕截图,不使用 mockup,也不使用 iframe。
    • 虚假 mockup 数字 → 用户会问“既然与真实情况不同,拿来有什么用”。删除。
    • 真实应用 iframe → 会因 SSO(Microsoft 阻止在 frame 中登录)+ cookie partitioning 而失效。删除。
    • 最终方案:真实截图(Playwright + dev-token bypass),右侧使用 sticky 图片面板,每个板块提供一个按钮来切换到对应页面;提供“打开应用(新窗口)”按钮以执行真实操作。
  9. **标准布局:**简短 hero 区 → 2 张范围卡片 → 免责声明 → 场景表(带“复制 Excel / 下载 CSV / 导出 PDF”按钮)→ 双栏布局:左侧为按业务分组的分步面板(编号步骤、“预期值”字段、checkbox),右侧为 sticky 图片面板。

Reference — Kỹ thuật bắt buộc (đã vấp đủ)

参考 — 强制技术要求(均已实际踩坑)

  • Offline-proof tuyệt đối: CSS thuần trong file, KHÔNG Tailwind CDN (mạng chặn = trang trắng). Google Fonts cho phép nhưng phải có fallback stack.
  • <head>
    đủ:
    <meta charset="utf-8">
    +
    <meta name="viewport" content="width=device-width, initial-scale=1">
    • <title>
      thật. Thiếu viewport → bảng tràn ngang trên laptop nhỏ/máy tính bảng của nghiệp vụ.
  • Cột số căn theo
    tabular-nums
    (
    td.num, .exp-val{font-variant-numeric:tabular-nums}
    ) — số kỳ vọng (lương, trần BHXH…) phải thẳng cột để soi nhanh; font tỉ lệ làm số nhảy cột, sai lệch khó thấy.
  • Focus ring bàn phím: mọi nút (Sao chép Excel / Tải CSV / Xuất PDF / "Hiển thị đầy đủ") + ô chọn Đạt/Không đạt cần
    :focus-visible{outline:2px solid var(--accent);outline-offset:2px}
    — nghiệp vụ hay thao tác bằng Tab/Enter, mất ring là lạc chỗ. (Bỏ ring chuột bằng
    :focus:not(:focus-visible){outline:none}
    .)
  • localStorage
    bọc try/catch
    —
    file://
    có thể chặn storage, để hở là chết toàn bộ script:
    js
    const store={get(k){try{return localStorage.getItem(k)}catch(_){return null}},
                 set(k,v){try{localStorage.setItem(k,v)}catch(_){}}};
  • Trạng thái Đạt/Không đạt + ghi chú lưu store, dòng đổi màu (Đạt = accent nhạt, Không đạt = amber), badge đếm
    Đạt x · Không đạt y / N
    .
  • Xuất 3 kiểu: Copy TSV (dán thẳng Excel, fallback execCommand), CSV có BOM
    
    (Excel VN đọc đúng UTF-8), PDF = tự expand đủ bộ →
    window.print()
    +
    @media print
    (ẩn nút/ảnh/split, ép nền trắng chữ đen — nền dark in giấy là hỏng).
  • Blur PII trước khi đưa ảnh ra khỏi mạng nội bộ (PIL GaussianBlur ≥18 trên ảnh gốc 2400px): cột mã NV + họ tên (cả chip code trong cột tên), cột người nhập/duyệt/sửa, chip tài khoản góc sidebar. Sau blur PHẢI crop-soi lại từng vùng — tail tên tràn cột và dòng đầu trên mép blur là 2 lỗi kinh điển. Chỉ deploy ảnh đã blur + đã được trang tham chiếu; ảnh thừa xóa khỏi gói.
  • Agent không tự deploy ra hosting công khai — classifier chặn đúng. Quy trình: agent blur + đóng gói (
    /tmp/<deploy-dir>
    với index.html), đưa user 1 lệnh
    ! vercel deploy --prod --yes
    tự chạy.
  • Chụp màn hình bằng Playwright: set localStorage (accessToken/user/expiry) + cookie authed qua
    addInitScript
    /
    addCookies
    ; API nào 401 với dev-token thì
    ctx.route
    trả
    []
    (KHÔNG
    {}
    — page gọi
    .forEach
    là vỡ).
  • 必须完全离线可用:CSS 直接写入文件,不得使用 Tailwind CDN(网络被拦截时页面会变成空白)。 可以使用 Google Fonts,但必须配置 fallback stack。
  • <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 上限等)必须整齐成列,便于快速核对;比例字体可能导致数字在列中跳动,造成难以发现的偏差。
  • **键盘 focus ring:**所有按钮(复制 Excel / 下载 CSV / 导出 PDF /“显示全部”)以及“通过/不通过”选择框 都需要
    :focus-visible{outline:2px solid var(--accent);outline-offset:2px}
    ——业务人员经常使用 Tab/Enter 操作,缺少 focus ring 会造成操作迷失。(使用
    :focus:not(:focus-visible){outline:none}
    移除鼠标 focus ring。)
  • localStorage
    必须包裹在 try/catch 中
    ——
    file://
    环境可能阻止 storage,一旦出现未处理异常,整个 script 都会失效:
    js
    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): 员工编号 + 姓名列(包括姓名列中的 code chip)、录入/审批/修改人列,以及 sidebar 角落的账户 chip。 模糊处理后必须逐个区域裁剪放大复查——姓名尾部溢出列和首行贴近模糊边缘是 2 个经典问题。 只能部署已模糊处理并被页面引用的图片;应从交付包中删除多余图片。
  • Agent 不自行部署到公共托管环境——classifier 必须准确拦截。流程:Agent 完成模糊处理并打包 (
    /tmp/<deploy-dir>
    ,其中包含 index.html),然后向用户提供 1 条
    ! vercel deploy --prod --yes
    命令,由用户自行执行。
  • 使用 Playwright 截取屏幕:设置 localStorage(accessToken/user/expiry),并通过
    addInitScript
    /
    addCookies
    注入 authed cookie; 如果使用 dev-token 时 API 返回 401,则由
    ctx.route
    返回
    []
    (不得返回
    {}
    ——页面会调用
    .forEach
    从而崩溃)。

Delivery — Output Report

交付 — 输出报告

Sau khi xong, ghi draft
llmwiki/wiki/sources/draft/DDMMYY-<ten>.md
(Type: draft, Status: proposed, Tags: uat-nonit-testcase, output-report) + cập nhật
wiki/index.md
và
wiki/log.md
— theo chuẩn output-report của các skill khác trong bộ này.
完成后,写入 draft
llmwiki/wiki/sources/draft/DDMMYY-<ten>.md
(Type: draft,Status: proposed,Tags: uat-nonit-testcase, output-report),并更新
wiki/index.md
和
wiki/log.md
——遵循本套 skill 中其他 skill 的 output-report 标准。