D-Watch 開発ガイド(AIエージェント向け)

プロジェクト概要

清掃ロボット監視ダッシュボード「D-Watch」。ドン・キホーテ/MEGAドンキ等の店舗に設置された清掃ロボット・D-S制御盤の稼働状況を監視するWebアプリ。

体制・責任分界

• DFA内製2名(環境担当/ダッシュボード担当) + Cursor / Claude Code
• TeamWorks側の責任: DB・データ収集・サマリバッチ
• DFA側の責任: APIサーバー・ビューアー・点検記録

技術スタック

• Next.js(App Router)+ TypeScript。フロントとAPIは1リポジトリ・1デプロイで完結
• Prisma(prisma db pullでTeamWorks構築のMySQLスキーマを自動取込。schema.prismaは自動生成物として扱い手動編集しない)
• MySQL 8(参照用+アラート更新用の2アカウント)
• 点検記録は独自ストア(SQLite + オブジェクトストレージ、メインDBと分離)
• 認証: 簡易トークン + IP制限(P1は社内利用のみ)
• APIモック: Prism(OpenAPI YAMLから自動起動、DB完成を待たずフロント開発を進める)

リポジトリ・運用

• ソース管理: GitBucket(https://git.d-sec.dfarobotics.com/git/develop/client_dwatch.git)。GitHubではない
• デフォルトブランチ: develop。作業はfeatureブランチを切ってPull Request経由でマージ
• CI: サーバー側CIは無し。git hook(husky)でローカル強制
  • pre-commit: lint-staged(変更ファイルのみLint)
  • pre-push: 型チェック+テスト
• 相互PRレビュー必須: AIが書いたコードも含め、必ずもう1名がレビューしてからマージする

参照資料の優先順位(矛盾があった場合)

1. d-watch-mock.jsx(画面レイアウト・文言・遷移の正)
2. d-watch-api.yaml(API契約の正。エンドポイント・JSONスキーマ・enum・エラー形式)
3. 清掃ロボット監視テーブル定義書(DBスキーマの正、28テーブル)

領域をまたぐ矛盾は都度このマップを更新して解消する。

開発の原則(5箇条)

1. モックファースト: フロントはPrismモックAPI相手に開発し、実DBの完成を待たない。接続先の切替だけで本番化する
2. 判定ロジックは期待値表で固定: ◎○△×・L1〜L3・KPI計算・整数丸めは、入力→出力の期待値表を先に作りテストで固定する。生成コードの目視確認だけで済ませない
3. APIの変更はYAMLが先: 実装中に契約を変えたくなったら、まずd-watch-api.yamlを直してからコードに反映する
4. 相互PRレビュー: AIが書いたコードこそ、もう1人が必ずレビューしてからmainにマージする
5. TeamWorks待ちでブロックしない: 各フェーズの「依存」列にある待ち項目は、モック・スタブで先行しておき解消後に差し替える

開発フェーズ(P0→P1は順序必須、P2以降は基本この順、P6は並走可)

P0 環境準備 → P1 基盤(共通レイアウト・API共通実装・判定ロジック) → P2 コア画面 → P3 アラート系 → P4 レポート → P5 マスタ/Viewer → P6 点検記録(並走可) → P7 仕上げ(本番デプロイ)

本番インフラ

さくらのクラウドVM(Linux、systemd管理、nginx リバースプロキシ想定)。さくらのレンタルサーバーは利用不可(Node.js常駐プロセスを稼働できないため)。