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

## 現在の状況(2026-08-03時点)
P0(環境準備)は完了。TeamWorks側のDB完成待ちのため、P1着手前でいったん開発を中断中。
- 完了済み: WSL2 Ubuntu環境、Next.js/Prisma/husky初期化、GitBucket連携、`d-watch-api.yaml` + Prismモック起動確認、`src/mocks/d-watch-mock.jsx`(PIIスクラブ済み)
- 未着手: P1(共通レイアウト・API共通実装・判定ロジック)以降

## 開発再開手順
中断期間を経て開発を再開する際は、以下の順で確認・実施する。

1. **WSL2 Ubuntu環境の起動確認**
   ```bash
   wsl -l -v   # Windows側PowerShellで実行
   ```
   GUI(XFCEデスクトップ)を使う場合はxrdpの起動も確認する。
   ```bash
   sudo systemctl status xrdp
   ```

2. **Cursorでプロジェクトを開く**
   ```bash
   cd ~/projects/client_dwatch
   cursor .
   ```
   左下に`WSL: Ubuntu`と表示されることを確認する。

3. **GitBucketの最新状態を取り込む**
   ```bash
   git pull origin develop
   ```

4. **依存関係を最新化**
   ```bash
   npm install
   ```

5. **このCLAUDE.mdを読み直してから作業に着手する**
   開発原則・参照資料の優先順位・現在のフェーズをここで再確認する。

6. **DBが完成していれば、Prisma経由でスキーマを取り込む**
   ```bash
   npx prisma db pull
   ```
   取り込んだスキーマを清掃ロボット監視テーブル定義書(28テーブル)と突き合わせ、食い違いがないか確認する。

7. **P1(基盤)から着手する**
   優先順:
   1. 判定ロジック実装+期待値テスト(◎○△×・KPI計算。最優先)
   2. 共通レイアウト実装(`src/mocks/d-watch-mock.jsx`から移植)
   3. API共通実装(認証・エラー形式・ページネーション)