本書は、本アプリケーションの操作手順をまとめた利用者向けマニュアルです。画面・ボタン名は実装に準拠しています。

• 対象アプリ: 作業手順ナビシステム（Work Procedure Navigation）
• 構成: フロントエンド（React + TypeScript + Vite）＋ バックエンド（Express REST API・インメモリ）
• 設計トレース: 業務シナリオ → ユースケース図 / クラス図 / 状態マシン図 / アクティビティ図 → 実装

01はじめに

本アプリは、製造現場の作業手順をデジタル化し、作業者を画面で誘導しながら品質を作り込むためのシステムです。次の4本柱で構成されます。

代表的なアクター（利用者像）：現場作業者 / 工程設計者 / 製造管理者 / 品質管理者 / システム管理者。

02起動と終了

2.1 必要環境

• Node.js 18 以降（動作確認は Node.js 23 / macOS）
• 対応OS: macOS / Windows / Linux

2.2 起動手順

2つのサーバーを起動します。ターミナルを2つ使います。

# ① バックエンド（REST API / ポート 4000）
cd app/backend
npm install        # 初回のみ
npm run dev

# ② フロントエンド（画面 / ポート 5173）
cd app/frontend
npm install        # 初回のみ
npm run dev

ブラウザで http://localhost:5173/ を開きます。

2.3 終了手順

各ターミナルで Ctrl + C。または以下で停止します。

lsof -ti:4000,5173 | xargs kill

2.4 検証コマンド

cd app/backend  && npx tsc --noEmit && npx jest    # 型チェック + 100テスト
cd app/frontend && npx tsc --noEmit && npm run build

03画面構成

画面左のサイドバーから各機能へ移動します。上段が業務画面、その下がドメイン別のデータ管理画面です。

データ管理画面は全50エンティティで共通して 一覧 → 詳細 → 新規/編集 の3画面で構成されます（→ 9章）。

04ダッシュボード

トップ画面（/）です。全体状況の把握と、各機能への入り口として使います。

• 上段: 作業中 / エラー・保留 / 完了 / 未解除アラート の件数
• 中段: 作業手順・作業指示・デバイス・アラート履歴の登録件数
• 下段「主要画面」: カードをクリックして各機能へ移動

05作業ナビ

現場作業者が使うメイン画面です（/navi、UC-04〜UC-16）。作業の開始から完了までを1画面で行います。

5.1 作業を開始する（UC-04 / BR-031）

画面上部のパネルで選択モードを選び、「作業を開始」を押します。

開始できない場合は、次のようなメッセージが表示されます。

既に進行中の作業がある場合、画面を開いた時点で自動的にその作業が選択されます。「進行中の作業実績」プルダウンから別の作業へ切り替えることもできます。

5.2 工程を進める

画面の見方は次のとおりです。

• 上部のバッジ列 — 作業実績の状態、選択モード、進捗（現在ステップ / 全ステップ）、言語、スキルレベル。ループ中は 🔁 Forループ 1/2 のようなループバッジが追加表示されます。
• 中央（ステップ表示） — 現在のステップ番号とステップ送り方式（AUTO＝イベントエンジンが進める／MANUAL＝作業者が「次の工程へ」で進める。BR-033）、1ステップに複数の動画・画像をタイル表示（BR-005）、全ステップ必須の説明テキスト、作業者の使用言語での 🔊 音声ガイド（未翻訳は既定言語へフォールバック。BR-006）。
• 右側 — ⚠ 注意ポイント、☑ チェックリスト（「必須」項目をすべてチェックするまで「次の工程へ」は押せない）、工程実績（状態・手戻り回数・ループ反復・標準時間）。

下部（進行操作）

5.3 ポカヨケ制御（UC-08 / UC-09 / UC-11）

「ポカヨケ制御」セクションには、そのステップに設定されたポカヨケ規則に応じた入力欄が自動的に出し分けされます。規則がない工程では「この工程にポカヨケ規則はありません。」と表示されます。

判定結果は画面上部に緑（OK）／赤（NG）のメッセージで表示されます。NGのまま「次の工程へ」を押すと ポカヨケ判定NGのため次工程へ進めません: … となり、進行が止まります（BR-001 強制順序制御）。

5.4 条件分岐とループ（UC-14 / BR-013 / BR-032）

「次の工程へ」を押したときの次工程は、システムが自動的に決定します。

• 条件分岐 — 製品型番やステップの結果（OK／NG）を判定して分岐先を決めます。
• ループ — ループ末尾のステップでは継続／終了を判定します。継続時は戻り先ステップへ移動し「ループ継続: 戻り先ステップへ進みました。」と表示。FORループは指定回数だけ繰り返し、WHILEループは終了条件式が真になるまで繰り返します（無限ループ防止のため上限回数で保護）。

全工程を完了すると「全工程完了。MESへ実績を返却しました。」と表示されます。

06作業分析ダッシュボード

製造管理者向けの分析画面です（/analytics、UC-29〜UC-33）。状況の把握 → 問題の特定 → 原因分析 → 改善判断の順に並んでいます（BR-025）。

6.1 更新操作

右上の2つのボタンで更新方法を切り替えます。

左の「最終更新」バッジで最後に取得した時刻を確認できます。

07トレーサビリティ検索

品質管理者向けの遡及検索画面です（/traceability、UC-18 / BR-017）。

1. 「製品シリアル番号 / 部品ロット」に検索キーを入力します（例: SN-100100）。
2. 遡及検索ボタン、または Enter キーで検索します。

結果は4つのセクションに分かれて表示されます。

追跡レコードは追記のみで更新・削除ができず、改ざん検知用のハッシュが付与されます（BR-016）。

08テストラン

動作確認・デモ用の付加機能です（/simulation、UC-37）。一定間隔で作業状況をランダムに変化させ、分析ダッシュボードがリアルタイムに動く様子を確認できます。

8.1 実行手順

1. 左の「実行条件」を設定します（変化間隔（秒）／乱数シード（再現用）／NG発生率（%））。同じシードなら同じ変化を再現できます。
2. 右上のテストラン開始を押します。以降、設定した間隔で自動的に変化します。
3. 1周期だけ進めるで、任意のタイミングで1周期分だけ手動実行できます。
4. 停止で終了します。

8.2 画面の見方

• 実行条件（左） — 状態（実行中など）・実行番号・生成作業実績件数・生成イベント件数・開始時刻。実行中は入力欄がロックされます。
• リアルタイム作業状況（右上） — 作業中／保留／エラー／完了／中止の件数と主要KPI。
• 変化ログ（右下） — 周期ごとに「開始 / 進行 / NG / 手戻り / 完了 / 保留 / デバイスイベント」の件数を新しい順に最大20件表示します。

09データ管理画面（一覧・詳細・フォーム）

サイドバーのドメイン別メニューから開く画面です。全50エンティティで構造が共通しています。

すべての画面は、データの所属を辿れるように設計されています（BR-034）。ID の内部値ではなく、親を含む識別名（例: モータユニット組立手順 / v2 / 3 / ケース固定ボルトを規定トルクで締め付ける）で表示します。

9.1 一覧画面

• 識別名列が先頭に固定表示されます。クリックで詳細へ移動します。
• 参照（FK）列は参照先の識別名で表示されます。
• 検索ボックスでテキスト項目を検索、列見出しの ⇅ で並び替え。1ページ20件でページ送りが出ます。
• 右端の編集 / 削除で行を直接操作、右上の新規作成で登録画面へ移動します。

9.2 詳細画面

• タイトルが親を含む識別名（例 モータユニット組立手順 / v2）になります。
• 現在の状態 — 状態を持つデータにバッジ表示。
• 操作（状態遷移） — 状態マシンに定義されたイベントがボタンで並びます。実行できない遷移を押すとエラーメッセージが表示されます。
• 詳細情報 — 全項目。参照項目は親の識別名リンクで、クリックで親の詳細へ移動。
• 関連データ — 子データへのリンク。クリックするとこの親でスコープされた子の一覧へ移動します。

9.3 関連データへのドリルダウン

• 上部の青い帯に「〜に関連する作業ステップ（手順バージョンで絞り込み）：7件」と、由来と件数が表示されます。
• 絞り込み解除で全件表示に戻ります。

これにより 作業手順 → 手順バージョン → 作業ステップ → メディア／ポカヨケ／チェックリスト／注意ポイント／必要スキル の順にドリルダウンできます。

9.4 新規作成・編集フォーム

• ラベル右の赤い * は必須項目です。
• 項目の型に応じて、テキスト / 数値 / 日付 / 日時 / チェックボックス / プルダウン（列挙型）が出し分けされます。
• 参照項目は関連先のIDを直接入力します（入力欄の下に「関連 work-steps のID」のようにヒントが出ます）。IDは対象の一覧・詳細画面で確認してください。
• 作成 / 更新で保存し、保存後は詳細画面へ移動。キャンセルで前の画面へ戻ります。

10業務ルールと状態遷移

10.1 作業実績の状態遷移

                保留                    再開
     ┌──────────────────▶ 保留(OnHold) ──────────────┐
     │                        │ 中止                 │
     │                        ▼                      │
 作業中(InProgress)      中止(Aborted) ──[クローズ]──▶ 完了扱い(Closed)
     │  ▲                     ▲                      ▲
     │  │ 是正完了             │ 中止                  │ 実績返却完了
     │  └──── エラー(Error) ◀──┘                      │
     │            ▲  NG検知                          │
     │            └───────────────                   │
     │                                               │
     └──[全工程完了（必須ステップ完了）]──▶ 完了(Completed) ─┘

10.2 手順バージョンの状態遷移

              公開申請          承認・有効化        新バージョン有効化 /
 下書き ──────────▶ 審査中 ──────────▶ 有効 ───有効終了日到来───▶ アーカイブ
   ▲                 │              │ ▲                          │
   └────差戻し────────┘              │ │一時停止/再開               │廃止
                                    ▼ │                          ▼
                                 一時停止                       廃止済

• 公開申請にはワークフロー検証がOKであることが必要（開始ステップが1つ／全ステップが到達可能／説明テキストが全ステップにある／ループに上限回数・終了条件がある）。
• 承認・有効化には有効開始日 ≤ 有効終了日が必要。
• 1つの作業手順に対して同時にActiveなバージョンは1つだけです（BR-010）。

10.3 主な業務ルール

（全34ルール。上表は画面操作に関係する主なものを抜粋しています。）

11シードデータ

バックエンド起動時に、デモ・テストラン用のデータが自動投入されます（608件 / 46コレクション）。追加のスクリプト実行は不要です。

動作確認に使える値の例：

• 進行中の作業実績: WS-00007（作業中）、WS-00008（エラー）
• トレーサビリティ検索キー: SN-100100 〜 SN-100104
• 手動選択の作業手順: PRC-MOT-A100 モータユニット組立手順

12よくある質問・トラブルシュート

13制約事項

• データは在メモリ（インメモリ）保持です。バックエンドを再起動すると、登録したデータはシード（初期）状態に戻ります。DB／Prisma は使用していません。
• ログイン認証はありません。権限は利用者アカウントのロール属性として扱い、業務APIでは loginId による権限判定のみ行います。
• 動画・画像は実ファイルを再生・表示しません。作業ナビのメディア欄はプレースホルダ（🎬 / 🖼️ とキャプション）で、件数と構成を確認するためのものです。
• 音声ガイドは音声を再生しません。ガイド文をテキストで表示するところまでが本デモの範囲です。
• WHILEループの終了条件式は簡易DSL（loopIteration>=N、result==Ok など）で評価します。複雑な条件式には対応していません。
• 対象言語は ja / en / zh / vi / pt を定義していますが、シードデータは日本語・ベトナム語のみ収録しています。
• 本番運用では、永続化層を PostgreSQL（Prisma 等）＋オブジェクトストレージ（S3 等）へ差し替えることを想定しています。