uat-nonit-testcase

NON-ITユーザー向けUATテストケースビルダー

自己完結型のHTMLファイルを1つ生成します（CDN不要、ビルド不要、file://で開いても動作）。業務ユーザー向けのUAT資料です。 Payroll Cotecconsプロジェクトの知見をまとめたものです。以下のルールは、実際に失敗を経験して得た教訓です。手順を省略しないでください。

WHAT

目的と背景

• 目的： 非ITの業務ユーザー向けUAT資料として、オフラインで確実に動作する自己完結型HTMLファイルを1つ生成します。Ctrl+Fで検索できるコード付きの逐次シナリオ表、チェック対象／対象外の範囲、PIIをぼかした実際の画像付き手順、合格／不合格の記録、Excel／CSV／PDFへのエクスポートを備えます。
• 利用タイミング： 「非IT向けのテストケースを作成」「業務向けUATチェックリスト」「C&B向けテストシナリオ」「/uat-nonit-testcase」など。アプリをテストする必要がある業務ユーザー（C&B、会計、運用）を対象とします。
• 対象外： ソースシステム（HRIS/ERP）のデータはチェックしません。ソース側の不一致は別途記録し、バグには含めません。モックアップや実際のアプリのiframeは使用しません。エージェントは公開ホスティングに自動デプロイしません。開発者向けの自動テストスイートではありません（それはplaywright-verifyの役割です）。

基本的な考え方

業務ユーザーの発言そのまま → 業務グループ＋チェック対象／対象外の範囲 → 実際のコード／設定（計算式、定数、列の参照元）→ 事前計算済みの期待値 → 逐次シナリオグループ-NN → 実際の画像（PIIをぼかす）→ オフラインで確実に動作するHTML → Playwrightテスト → 納品

入力と出力の仕様

	フィールド	必須？	説明
入力	業務ユーザーの発言そのまま	はい	チェックする業務グループ、チェックしない項目、希望する形式
入力	アプリの実際のコード／設定	はい	画面とルート、計算式、定数、各データ列の参照元
入力	アプリを実行して撮影する権限（dev-token）	はい	Playwrightの認証バイパスを使って実際の画面を撮影
入力	プロジェクトの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 log	llmwikiがある場合	出力レポート

ルールと機能

中核となる原則（「Reference — 中核となる原則」の項に記載された全文）：

• RULE-01（必須）：技術用語を避け、企業向けの正式な文体を使用します。
• RULE-02（必須）：チェック対象／対象外の範囲をページの冒頭で明確に分けます。
• RULE-03（必須）：期待値は実際のコード／設定から事前に計算します。
• RULE-04（必須）：逐次シナリオ表を主な成果物とします。
• RULE-05（必須）：Ctrl+Fで検索できるシナリオコードを付けます：NHÓM-NNを等幅フォントで表示します。
• RULE-06（必須）：重要なシナリオはデフォルトで5～6件のみとし、⭐／バッジ／絵文字は使いません。
• RULE-07（必須）：上書き免責事項をアンバーで強調表示し、表の上に配置します。
• RULE-08（必須）：実際の画面画像を使用し、モックアップやiframeは使用しません。
• RULE-09（必須）：標準レイアウト（ヒーロー → 範囲を示す2つのカード → 免責事項 → 表 → 2列の分割レイアウト）。

必須の技術要件（「Reference — 必須の技術要件」の項に記載された全文）：

• RULE-10（必須）：完全なオフライン対応： CSSはファイル内に記述し、Tailwind CDNは使用しません。
• RULE-11（必須）：<head>に必要な内容を含めます： charset＋viewport＋実際の<title>。
• RULE-12（必須）：数値列にはtabular-numsを適用します。
• RULE-13（必須）：すべてのボタンと選択欄に、キーボード操作用のフォーカスリング:focus-visibleを設定します。
• RULE-14（必須）：localStorageをtry/catchで囲みます。
• RULE-15（必須）：合格／不合格の状態とメモをstoreに保存し、行の色を変え、バッジに件数を表示します。
• RULE-16（必須）：3種類のエクスポートに対応します： TSVをコピー、BOM付きCSV、白背景・黒文字を強制するwindow.print()経由のPDF。
• RULE-17（必須）：画像を内部ネットワークの外に出す前にPIIをぼかし、各領域を切り抜いて確認します。
• RULE-18（必須）：エージェントは公開ホスティングに自動デプロイしません。ユーザー自身が実行するコマンドを1つ提示します。
• RULE-19（必須）：認証バイパスを使ってPlaywrightでスクリーンショットを撮影します。APIが401を返した場合は、ctx.routeで[]を返します（{}ではありません）。
• 機能：プロジェクトのコード／設定を読み取る、認証バイパス付きでヘッドレスブラウザーを実行して撮影する、画像を処理する（ぼかし／切り抜き）、HTMLファイル＋画像＋wiki draftを書き出す。公開ホスティングには公開しません。

失敗の境界

• ビジネスユーザーの発言がない／業務グループが不明 → 作成前に clarify してください。
• コード／設定で実際の計算式や定数が見つからない → 該当する期待値は blocked とし、数値を捏造しないでください。
• 実際の画面をキャプチャできない（認証／SSO） → partial とし、モックアップや iframe で代用しないでください。
• ぼかし後の画像を切り抜いて精査しても PII が見える → failed。ぼかし直し、未処理の画像は納品しないでください。
• オフラインの Playwright テストで JS エラーがある、またはトグル／印刷が動作しない → failed。納品前に修正してください。
• 公開ホスティングが必要 → ユーザー向けのデプロイコマンドで停止します（エラーではありません）。

方法

メインワークフロー

ステップ	種別	入力	アクション	出力／終了条件	失敗／次の処理
W01	判断	ユーザーの発言そのまま	業務グループ、チェックする／しない範囲、希望する形式を抽出	範囲	不足 → clarify
W02	決定的	コードベース	実際のコード／設定をスキャン：画面＋ルート、計算式、定数、列の出典	出典表	見つからない → 該当項目を blocked
W03	副作用	実行可能なアプリ	Playwright の認証バイパスで実際の画面をキャプチャ。外部共有する場合は PII をぼかす（B01）	画像	ぼかしが不十分 → やり直し
W04	判断	範囲、計算式	順序立てたシナリオを作成し、期待値を事前計算して、重要なケースを 5～6 件選ぶ	シナリオ表	—
W05	副作用	シナリオ、画像	標準レイアウト＋必須技術要件に沿って HTML を構築。brand-kit があればブランドを適用	HTML ファイル	—
W06	決定的	HTML ファイル	Playwright でテスト：file:// ＋外部ネットワークを 100% 遮断 → JS エラー 0 件、トグル、選択、PDF 印刷	PASS	FAIL → 修正して W06 を繰り返す
W07	副作用	結果	デプロイ（B02）＋ llmwiki があれば wiki のドラフト／インデックス／ログを記録	納品	—

各ステップの詳細（W01～W07 の信頼できる情報源）：

6 ステップの手順

1. ビジネスユーザーの発言をそのまま取得 → チェックする業務グループ、チェックを拒否する項目、 希望する形式（表！）を抽出します。
2. 実際のコード／設定をスキャン（Explore agent）：画面＋ルート、計算式、定数、各データ列の出典。
3. 関連する画面の実際の画像をキャプチャ（Playwright、認証バイパス）→ 外部共有する場合は PII をぼかします。
4. 表テンプレートに沿って順序立てたシナリオを作成し、期待値を事前計算して、重要なケースを 5～6 件選びます。
5. 上記の標準レイアウト＋必須技術要件に沿って HTML を構築します。プロジェクトの brand-kit があればブランドを適用します （トークン：CSS vars 経由の bg/accent/amber-cảnh-báo — ブランドの変更は :root のみを編集）。
6. 納品前に Playwright でテストします：file:// を開き、外部ネットワークを 100% 遮断 → JS エラー 0 件、トグル 5↔N 行、達成／未達成を選択、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

検証と停止条件

必須：外部ネットワークを 100% 遮断した状態で Playwright から file:// を開き、JS エラー 0 件、5↔N 行のトグルが動作し、達成／未達成の選択で色＋件数バッジが変わり、PDF 印刷がファイルに出力されること。要レビュー：期待値を実際の設定画面と突き合わせて確認すること、ぼかし画像を目視で切り抜いて確認すること。両方が完了した場合にのみ納品します。

例

• ポジティブ： C&B が「月次給与チェックリストを表形式で」と依頼 → 設定をスキャンして社会保険料の上限が46,8trと判明 → 50trの給与に対するシナリオ TRICH-02 の期待値は正確に3.744.000 → 重要な6ケースを含むHTML、「全N件のシナリオを表示」ボタン、オフラインテストでJSエラー0件 → llmwiki/html/DDMMYY-uat-checklist-luong.html。
• 境界／失敗： ユーザーが「便宜上、実際のアプリをページに埋め込んで」と要望 → Microsoft SSOとCookieのパーティショニングによりiframeが動作しない → iframeは使わず、実際のスクリーンショットと「アプリを開く（新しいウィンドウ）」ボタンを使用します。
• 境界： ぼかし後の画像でも、列からはみ出した名前の末尾が見えている → トリミング確認で検出 → パッケージ化前に再度ぼかします。

参考 — 基本原則（実際のユーザーフィードバックから学んだこと）

1. 専門用語を避けた言葉遣いと、企業向けのフォーマルな文体。 絵文字、コードネーム、ファイルパス、API名は使いません。「テスト一覧」、「合格／不合格」（UI上でPass/Failは使わない）、「システムが自動計算」（「エンジン」は使わない）。データソースは名前だけを示します：HRISから／Excelをインポート／ユーザーが入力／システムが自動計算 — 仕組みの説明は不要です。
2. チェック対象／対象外の範囲をページの冒頭で明確に分けます。 ✓／✗のカードを2つ表示します：アプリが自動計算した値とユーザーが入力した値はチェック対象、システムの元データ（HRIS／ERP）から引き継いだ値はチェック対象外です — 「元データと同じなら、元データを出力して使えばよく、再確認する必要はありません」。元データの不一致は別途記録し、バグには数えません。
3. 期待値は実際のコード／設定から事前に計算しておきます。 バックエンド／設定から実際の計算式と定数を読み取ります（例：社会保険料の上限46,8tr → 給与50trの場合、正確に3.744.000）。具体的な数値1つは、説明文10行より価値があります。記載前に実際の設定画面と相互照合します。
4. 時系列順のシナリオ表が主要な成果物です。業務ユーザーが求めているのは「表形式の一覧」であり、見栄えのよいWebページではありません。標準の列：コード（Ctrl+F） | シナリオ | 画面 | 実施手順 | 期待結果 | 結果 | 備考。シナリオの順序は実際の作業順にします：設定 → データ入力 → 計算 → 各業務処理 → 集計 → 締め処理。
5. シナリオコードはCtrl+Fで検索できる形式にします：グループ-NN の等幅フォント表記（LUONG-01、TRICH-02、CHOT-01）。バグ報告時の共通言語として使います（「TRICH-02が失敗＋スクリーンショット」）。
6. デフォルトでは業務グループを十分にカバーする重要シナリオを5〜6件だけ表示し、「全N件のシナリオを表示」ボタンから展開できるようにします。展開時には、重要ケースを淡い背景色＋アクセントの左側バーで区別します — ⭐／バッジ／絵文字は使いません（レガシーな企業環境に適さないため）。
7. 上書きに関する注意書き（アンバー色で強調し、表の上に配置）： 標準外の複雑な計算式はExcelで計算してから、該当するセルに値を直接上書きします（ダブルクリック → 入力 → 理由を添えて保存）。システムは変更前／変更後の値と取り消し操作を記録します — シナリオOVRを参照してください。
8. 実際の画面を使用し、モックアップやiframeは使いません。
   • 架空の数値を使ったモックアップ → ユーザーから「実際と違うなら何のために使うのですか」と問われます。使用しません。
   • 実際のアプリをiframeに埋め込む → SSO（Microsoftがフレーム内のログインをブロック）とCookieのパーティショニングにより動作しません。使用しません。
   • 方針：実際のスクリーンショット（Playwright＋dev-tokenによるバイパス）を使用し、右側に画像パネルを固定表示します。各項目に、その画面に対応する画像へ切り替えるボタンを設置し、実際の操作用に「アプリを開く（新しいウィンドウ）」ボタンを設けます。
9. 標準レイアウト： 短いヒーロー領域 → 範囲を示す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 がないと、小型ノート PC や業務用タブレットでテーブルが横にはみ出します。
• 数値列は tabular-nums で整列（td.num, .exp-val{font-variant-numeric:tabular-nums}） — 期待値 （給与、社会保険の上限など）はすばやく確認できるよう、列を揃える必要があります。プロポーショナルフォントでは数値が列ごとにずれて、誤差を見つけにくくなります。
• キーボードのフォーカスリング： すべてのボタン（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(_){}}};
  

• 合格／不合格の状態とメモをストアに保存し、行の色を変えます（合格 = 薄い accent、不合格 = amber）。 バッジには 合格 x · 不合格 y / N と表示します。
• 3 種類のエクスポート：TSV をコピー（Excel にそのまま貼り付け、フォールバックは execCommand）、BOM  付き CSV（ベトナム語版 Excel で UTF-8 を正しく読み込み）、PDF = すべてを自動展開して window.print() + @media print（ボタン／画像／分割表示を非表示にし、背景を白、文字を黒に強制 — 暗い背景のまま印刷すると紙面が使い物になりません）。
• 社内ネットワーク外に画像を出す前に PII をぼかす（元画像のサイズが 2400px の場合、PIL GaussianBlur ≥18）： 社員番号列 + 氏名列（氏名列内のコードチップも含む）、入力者／承認者／編集者の列、サイドバーのアカウントチップ。 ぼかした後は、必ず各領域を切り出して細部を確認してください — 氏名の末尾が列からはみ出すことと、ぼかし領域の端にある先頭行は、よくある 2 つのミスです。 デプロイするのは、ぼかし済みかつ参照ページで承認済みの画像だけにしてください。不要な画像はパッケージから削除します。
• エージェントが公開ホスティングへ自動デプロイすることは禁止 — classifier が適切にブロックします。手順：エージェントがぼかしてパッケージ化し（/tmp/<deploy-dir> に index.html を含める）、ユーザーに ! vercel deploy --prod --yes というコマンドを 1 つ提示し、ユーザー自身が実行します。
• Playwright でスクリーンショットを撮るには、addInitScript/addCookies を使って localStorage（accessToken/user/expiry）と認証済み Cookie を設定します。dev-token で 401 になる API は、ctx.route で [] を返します（{} は不可 — ページが .forEach を呼び出すとエラーになります）。

納品 — Output Report

完了後、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 標準に従ってください。