設計モデル / Design Models
実装の前に、モデルで合意する。
本アプリの実装は、下記のユースケース図・クラス図から導出されています。アクター・ユースケース（UC）・業務ルール（BR）・ドメインクラスがそのまま実装へトレースされ、操作マニュアルの各章と一対一で対応します。
ユースケース図
Use Case Diagram
クラス図（ドメインモデル）
Domain Class Diagram
本書は、本アプリケーションの操作手順をまとめた利用者向けマニュアルです。画面・ボタン名は実装に準拠しています。
- 対象アプリ: 建設現場 日報・写真整理アプリ
- 構成: フロントエンド (React + TypeScript) ＋ バックエンド (Express REST API)
- 設計トレース: 業務シナリオ → アクティビティ図 / ユースケース図 / クラス図 → 実装
01はじめに
本アプリは、建設現場の日報作成と写真整理をデジタル化するためのシステムです。主な機能は次のとおりです。
| 区分 | 機能 |
|---|---|
| 現場記録 | 電子小黒板付き写真の登録、画像アップロード、位置情報、日報作成 |
| 写真整理 | 写真の自動分類、写真台帳（Excel/PDF/SXF）の出力 |
| 承認 | 日報の提出・承認・差し戻し |
| マスタ・権限 | 工事現場・図面の管理、利用者の権限管理 |
代表的なアクター（利用者像）：現場作業員 / 現場監督 / 元請け / バックオフィス / 本社システム管理者。
本アプリはログイン認証を実装していないため、すべての画面に誰でもアクセスできます。権限は「利用者」データ上の属性として管理します。
02起動と終了
2.1 必要環境
- Node.js 18 以降
- （ダミーデータ投入を使う場合）Python 3
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/ を開きます。
フロントエンドは
/api と /uploads へのアクセスを自動的にバックエンド(4000番)へ転送します。先にバックエンドを起動してください。2.3 終了手順
各ターミナルで Ctrl + C。または以下で停止します。
lsof -ti:4000,5173 | xargs kill03画面構成
画面左のサイドバーから各機能へ移動します。グループ構成は次のとおりです。
| グループ | メニュー | 内容 |
|---|---|---|
| ダッシュボード | ダッシュボード | 件数サマリと最近のデータ |
| 業務 | 日報 / 写真 / 写真台帳 | 日々の記録・整理・台帳出力 |
| マスタ管理 | 工事現場 / 図面 | 基礎データの登録 |
| システム | 利用者 | 利用者と権限の管理 |
各機能は共通して 一覧 → 詳細 → 新規/編集 の3画面で構成されます。
- 一覧画面: 検索・絞り込み・並び替え・ページ送り。行クリックで詳細へ。右上「新規作成」で新規登録。
- 詳細画面: データの内容表示と、右上の操作ボタン（編集・削除・業務操作）。
- 新規/編集画面: 入力フォーム。「作成」または「更新」で保存、「キャンセル」で戻る。
04ダッシュボード
ログイン直後（トップ画面）に表示されます。
- 各データの件数サマリ
- 最近の日報・写真の一覧（クリックで該当の詳細へ移動）
全体状況の把握と、各機能への入り口として利用します。画面左がサイドバー、中央が各機能の表示エリアです。
05写真
電子小黒板を合成した証拠写真を管理します。現場記録の起点となる機能です。
5.1 写真一覧
- サムネイル / 工事名 / 工種 / 位置情報 / 撮影日時 / 同期状態 / 分類 を表示。
- 検索（工事名・工種）、絞り込み（同期状態・分類状態）、並び替え（工種・撮影日時）が可能。
- 画像未登録の写真はサムネイル欄に「なし」と表示されます。
5.2 写真の新規登録（UC-01/02）
右上「新規作成」から登録します。フォームは3ブロックです。
- 写真情報 — 撮影日時（必須）、工種、位置情報タグ、図面、同期状態。チェック: 改ざん防止済 / 分類済
- 写真ファイル — 「ファイルを選択」で画像（JPEG/PNG/WebP/GIF・最大10MB）を選ぶとプレビュー表示。保存時にアップロードされます（編集時は差し替え）。
- 電子小黒板（重要・必須） — 工事名（必須）・工種・測点・撮影日・J-COMSIA適合
⚠️ 小黒板情報（特に工事名）が未入力の写真は登録できません（BR-001：証拠写真として認められない）。
「作成」を押すと登録され、写真詳細へ移動します。
5.3 写真詳細
- 写真ファイル: 画像を表示。右上「画像をアップロード／差し替え」で画像を登録・変更、「画像を削除」で画像のみ削除（メタデータは保持）。
- 写真情報: 撮影日時・工種・位置情報・同期状態・改ざん防止・分類状態・図面。
- 電子小黒板: 工事名・工種・測点・撮影日・J-COMSIA適合と「合成済／未合成」バッジ。
- 右上操作: 一覧へ / 編集 / 分類（未分類のときのみ表示。押すと「分類済」になる＝UC-05）/ 削除。
5.4 画像のアップロード方法（2通り）
- 新規/編集フォーム: 「写真ファイル」でファイルを選び保存。
- 写真詳細: 「画像をアップロード／差し替え」ボタン。
06日報
現場作業員が作成し、写真を紐付けて提出・承認する日次報告です。
6.1 日報一覧
- 報告日 / 工種 / 状態 / デバイス種別 などを表示。状態（下書き・提出済・承認済・差戻し）で絞り込み可能。
6.2 日報の新規作成（UC-03）
右上「新規作成」から登録します。
- 報告日、工種、作業内容（複数行入力可）、状態、デバイス種別、工事現場
- 紐付く写真: 登録済みの写真から選択して関連付けます。
- 「作成」で保存。
6.3 日報詳細とワークフロー（UC-09）
詳細画面の上部に「ワークフロー」セクションがあり、現在の状態バッジと操作ボタンが表示されます。ボタンは状態に応じて出し分けされます。
| 現在の状態 | 表示される操作 | 結果 |
|---|---|---|
| 下書き / 差戻し | 提出 | 提出済へ（※写真が1枚以上必要） |
| 提出済 | 承認 / 差し戻し | 承認済 / 差戻しへ |
| すべて | 同期 | クラウドへ反映（同期状態を更新） |
- 日報情報: 報告日・工種・作業内容・状態・デバイス種別・工事現場。
- 紐付く写真: 関連写真をカード表示。クリックで写真詳細へ。
- 右上: 一覧へ / 編集 / 削除。
上図は「提出済」状態の例で、「承認」「差し戻し」ボタンが表示されています。
⚠️ 写真が1枚も紐付いていない日報は「提出」できません（業務ルール）。先に写真を作成し、日報フォームで紐付けてください。
07写真台帳
分類済み写真をまとめ、提出先に応じた形式で出力する台帳です（UC-06/07）。
7.1 台帳の生成
- サイドバー「写真台帳」→ 一覧画面の「台帳を生成」へ進みます（
/photo-ledgers/generate）。 - 出力形式を選択（Excel / PDF / SXF）。提出先（元請け・施主など）に応じて選びます。
- 分類済み写真の一覧から対象にチェック（「すべて選択／解除」も可能）。ここには 分類済み の写真のみ表示されます。未分類の写真は写真詳細で「分類」してください。
- 「台帳を生成」を押すと台帳が作成され、台帳詳細へ移動します。
写真を1枚も選択していないと生成できません。
7.2 台帳一覧・詳細
- 一覧で過去に生成した台帳（形式・枚数・作成日時）を確認。
- 詳細で含まれる写真や形式を確認できます。
08マスタ管理（工事現場・図面）
写真・日報から参照される基礎データです。先に登録しておくと入力が楽になります。
8.1 工事現場
- 工事名を登録。日報の「工事現場」として参照されます。
- 一覧 → 新規作成 → 工事名入力 → 作成。編集・削除も可能。
8.2 図面
- 図面名と所属工事現場を登録。写真の位置情報付与（撮影位置）で参照されます。
- 一覧 → 新規作成 → 入力 → 作成。
09利用者・権限管理
協力会社・元請け・本社の利用者を管理します（UC-10）。
9.1 利用者一覧・登録
- 氏名・所属会社・権限・状態（有効/無効）を表示。
- 「新規作成」で氏名・所属会社・権限を登録。
9.2 権限変更（UC-10 / BR-005）
利用者詳細の「権限変更」セクションで、権限を選び「権限を変更」を押します。
| 権限 | 想定 |
|---|---|
| 協力会社（Subcontractor） | 下請け |
| 元請け（PrimeContractor） | 承認担当 |
| 本社（HeadOffice） | 管理者 |
所属に応じて閲覧・編集できる情報範囲が変わる想定です（BR-005）。
9.3 無効化
利用者詳細の「無効化」ボタンで、利用者を論理削除（状態を「無効」に）します。データ自体は残ります。
10業務ルールと状態遷移
10.1 日報の状態遷移
提出(写真≥1) 承認
下書き ───────────────▶ 提出済 ────────▶ 承認済
▲ │
│ │ 差し戻し
│ 提出 ▼
差戻し ◀──────────────── （差戻し）- 「提出」は 下書き または 差戻し から可能。提出には写真が1枚以上必要。
- 「承認」「差し戻し」は 提出済 からのみ可能。
- 「同期」はいつでも可能（オフライン入力の通信復帰を想定）。
10.2 主な業務ルール
| ID | 内容 | アプリでの挙動 |
|---|---|---|
| BR-001 | 写真は電子小黒板（工事名・工種・測点・撮影日）を合成し改ざん防止の証拠写真とする | 小黒板（工事名）未入力の写真は登録不可（エラー表示） |
| BR-002 | オフラインでも入力でき、通信復帰時にクラウドへ自動同期する | 日報の「同期」操作で同期状態を更新 |
| BR-003 | 電子納品要件（SXF形式等）に準拠 | 写真台帳の出力形式に SXF を用意 |
| BR-004 | 小黒板は J-COMSIA 規格に適合 | 小黒板に「J-COMSIA適合」項目 |
| BR-005 | 協力会社・元請け・本社ごとに権限制御 | 利用者の権限（ロール）管理 |
| BR-006 | 提出先に応じて Excel/PDF をカスタマイズ出力 | 台帳生成で形式を選択 |
11ダミーデータの投入
動作確認用に、電子小黒板付きのダミー写真（画像つき）を一括投入できます。
# バックエンドを起動した状態で実行
python3 app/scripts/seed_dummy_photos.py # 既定8件
python3 app/scripts/seed_dummy_photos.py --count 4 # 件数指定
python3 app/scripts/seed_dummy_photos.py --no-image # メタデータのみ- Python 標準ライブラリのみで動作（追加インストール不要）。
- 実行のたびにデータが追加されます（重複防止はありません）。
12よくある質問・トラブルシュート
| 症状 | 原因・対処 |
|---|---|
| 写真を保存できない／エラーになる | 電子小黒板の「工事名」が未入力（BR-001）。工事名を入力してください。 |
| 日報を「提出」できない | 紐付く写真が0枚。日報編集で写真を1枚以上紐付けてください。 |
| 台帳生成画面に写真が出ない | 表示対象は「分類済み」写真のみ。写真詳細で「分類」してください。 |
| 画像がアップロードできない | 対応形式は JPEG/PNG/WebP/GIF・最大10MB。SVG等は不可。 |
| 画面は出るがデータが空 | バックエンド未起動。app/backend で npm run dev を実行。 |
| 画像が表示されない | バックエンドが停止している、または再起動でデータが初期化された可能性。 |
| ポートが使用中で起動できない | 既存プロセスを停止：lsof -ti:4000,5173 | xargs kill |
13制約事項
- データは在メモリ（インメモリ）保持です。バックエンドを再起動すると、登録したデータはシード（初期）状態に戻ります。
- アップロード済みの画像ファイル自体は
app/backend/uploads/に残ります。
- アップロード済みの画像ファイル自体は
- ログイン認証はありません。権限は利用者データ上の属性として扱います。
- 写真台帳の「出力」は形式の記録までを行う想定で、実ファイル（Excel/PDF/SXF）の生成は本デモ範囲外です。
- 本番運用では、永続化層を PostgreSQL（Prisma 等）＋オブジェクトストレージ（S3 等）へ差し替えることを想定しています。
