# 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常駐プロセスを稼働できないため)。