Fork: 0
develop / client_dwatch
Transfer to URL with SHA Find file
Newer
Older
client_dwatch / CLAUDE.md
@dfa dfa on 3 Aug 5 KB docs: add resume procedure and current status to CLAUDE.md
Raw Blame History

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環境の起動確認

    wsl -l -v   # Windows側PowerShellで実行

    GUI(XFCEデスクトップ)を使う場合はxrdpの起動も確認する。

    sudo systemctl status xrdp

  2. Cursorでプロジェクトを開く

    cd ~/projects/client_dwatch
cursor .

    左下にWSL: Ubuntuと表示されることを確認する。

  3. GitBucketの最新状態を取り込む

    git pull origin develop

  4. 依存関係を最新化

    npm install

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

  6. DBが完成していれば、Prisma経由でスキーマを取り込む

    npx prisma db pull

    取り込んだスキーマを清掃ロボット監視テーブル定義書(28テーブル)と突き合わせ、食い違いがないか確認する。

  7. P1(基盤)から着手する 優先順:

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