# D-Watch 開発手順書（たけうち りき さん向け）

Daigoが GitHub リポジトリと初期セットアップを済ませてあります。
この手順書のとおりに進めれば開発を始められます。

---

## 0. 最初に読むもの

clone したら、まずこの2つに目を通してください。**ここに書いてあることが仕様の正です。**

| ファイル | 内容 |
|---|---|
| `CLAUDE.md` | プロジェクト全体像、確定仕様（判定基準・計算式・端数処理）、**禁止事項** |
| `docs/spec.md` | 何をどの順で作るか（機能一覧とマイルストーン M0〜M7） |

余裕があれば `docs/decisions.md`（なぜこの仕様なのか）も。実装中に「これ変えたほうがよくない?」と思ったとき、
だいたいその論点は過去に検討済みでここに理由が書いてあります。

---

## 1. 環境準備（初回のみ）

### 1-1. 必要なもの

- Node.js（**20以上**。Daigoの環境は v24 系）
- Git
- Cursor
- GitHub アカウント（`DFA-takeuchi`。Organization への招待が届いています）

### 1-2. GitHub に会社メールを登録

コミット履歴に会社のメールアドレスが残るようにします。

```
GitHub → Settings → Emails → Add email address
→ daichi@dfarobotics.com を追加
```

アカウント自体は既存のもので構いません。**新しくアカウントを作る必要はありません。**

### 1-3. Cursor の設定 ★重要★

会社のコードを扱うので、**Privacy Mode を必ずONにしてください。**

```
Cursor → Settings（左下の歯車） → General → Privacy
→ 「Privacy Mode (Legacy)」が enabled になっていること
```

`Privacy Mode (Legacy)` は、コードが学習に使われないだけでなく**保存もされない**最も厳格な設定です。
画面に `Switch to Privacy Mode` というリンクが出ますが、これは制限の緩い新方式なので**押さないでください**。

アカウントは**会社のメールアドレス**（daichi@dfarobotics.com）で作成してください。
プランはまず Pro（$20/月）で始めます。使いすぎて枠を超えるようなら Daigo に相談してください。

### 1-4. リポジトリを clone

置き場所は `~/dev/` の下がおすすめです。

```bash
mkdir -p ~/dev
cd ~/dev
git clone https://github.com/DFARobotics/d-watch.git
cd d-watch
```

> ⚠️ **iCloud Drive / Google Drive / Dropbox の同期フォルダの中には置かないでください。**
> `.git` が同期で壊れて復旧できなくなる事故がよくあります。
> Mac はデスクトップや書類フォルダが iCloud 同期対象になっていることが多いので注意。

### 1-5. Git の設定 ★忘れやすい★

clone したディレクトリの中で、このリポジトリ用のコミット情報を設定します。

```bash
git config user.email "daichi@dfarobotics.com"
git config user.name "（GitHubの表示名）"
```

**`--global` は付けないでください。** このリポジトリだけの設定になり、個人のGit設定は変わりません。

確認：

```bash
git config user.email    # daichi@dfarobotics.com が返ること
git config user.name
```

ここを飛ばすと、コミットが個人のメールアドレスで記録されます。**最初のコミット前に必ず設定してください。**

### 1-6. 起動

```bash
npm install
cp .env.example .env.local
npm run dev          # http://localhost:3000
```

`.env.local` に `USE_FIXTURES=true` が入っていることを確認してください。
**しばらくの間、DBには繋ぎません。** サンプルデータで開発します（後述）。

★**`.env.local` に `ALLOW_DIRECT_ACCESS=true` が入っていることも確認してください**★
（`.env.example` に含まれています）。nginx を通らない直接アクセスを通す開発専用スイッチで、
★**本番では設定しません**★（未設定＝拒否）。本番側の手順は `docs/deploy.md` を見てください。

> なお、ローカルで全ページが 403 にならないのは、実際には
> `lib/config/allowed-ips.ts` の `ALLOWED_IPS` が空 かつ `ALLOW_ALL_WHEN_EMPTY = true`
> だからです（★`next start` / `next dev` は `X-Forwarded-For` が無いとき socket の接続元を
> 自分で入れるため、`ALLOW_DIRECT_ACCESS` は実際には発火しません★。D-101 の実測）。
> それでも `ALLOW_DIRECT_ACCESS=true` は設定しておいてください —
> 許可リストを埋めて検証するときに必要になります。

### 1-7. 動く見本を確認

ブラウザで以下を開いて、JSONが返ることを確認してください。

```
http://localhost:3000/api/clean-logs
http://localhost:3000/api/clean-logs?result=problem
```

これが `app/api/clean-logs/route.ts` です。**他の一覧APIはこの形を真似して作ります。**

---

## 2. 開発の進め方

### 2-1. サンプルデータで開発する

DBはTeamWorks（外部の会社）が構築中で、まだ繋げません。
その間は `lib/fixtures/` のサンプルデータを使って全画面を作ります。**もう用意してあります。**

- APIは `USE_FIXTURES=true` の間、サンプルデータを返します
- 画面のコードは「DBかサンプルか」を意識しません。あとで切り替えるだけです
- サンプルデータの中身は `docs/fixtures.md` を参照

サンプルデータには、判定の境界値・エスカレーション・空データなど**わざと厄介なケース**を仕込んであります。
きれいなデータだけで作ると本番接続時に一気に崩れるためです。消したり整えたりしないでください。

なお、サンプルデータの店舗名・住所・電話番号はすべて**架空のもの**です（バリューマート等）。
実在の情報をコードに書かない運用にしているので、データを足すときも架空の値でお願いします。

### 2-2. 作る順番

`docs/spec.md` の M0〜M7 の順です。リキさんの担当は主に画面side。

| | 内容 |
|---|---|
| **M2** | ダッシュボード、清掃詳細ログ ← **ここから** |
| M3 | アラート、D-Secログ、D-Secアラート |
| M4 | レポート |
| M5 | 施設ロボットマスタ、スケジュール |

画面のレイアウト・文言・遷移は**モック（`d-watch-mock.jsx`）が正**です。これを移植する形で作ります。

> モックには実在の店舗名・住所・電話番号が残っています。**移植するときは fixtures の架空データに置き換えてください。**

### 2-3. ブランチとPR

`main` に直接pushはできません（ブランチ保護がかかっています）。必ずブランチを切ってPRを出します。

```bash
git checkout -b feature/dashboard      # 作業ブランチを切る
# ... 作業 ...
git add .
git commit -m "ダッシュボードの数値カードを実装"
git push -u origin feature/dashboard
```

GitHub上でPRを作成 → マージ。マージ後はローカルを戻します。

```bash
git checkout main
git pull --prune
git branch -d feature/dashboard
```

**承認は必須にしていません**（自分でマージできます）。ただし `lib/judge/`（判定ロジック）を触るPRだけは、
マージ前に Daigo に一声かけてください。ここは間違えると運用が成立しない箇所です。

### 2-4. CI

PRを作るとGitHub Actionsが自動で Lint / テスト / ビルドを実行します。

- 赤くなってもマージはできます（今のところ必須にしていません）
- ただし**赤いまま放置しないでください**。原因が分からなければ Daigo に相談を

---

## 3. Cursor の使い方

### 3-1. 最初に必ず

Cursorのチャットで作業を依頼する前に、コンテキストとして以下を読ませてください。

```
@CLAUDE.md @docs/spec.md を読んで。これから清掃詳細ログ画面を作ります。
```

`CLAUDE.md` にプロジェクトのルールが全部書いてあるので、これを読ませるかどうかで生成コードの質が変わります。

**チャットはタスク単位で新しく開いてください**（ダッシュボード用、清掃詳細ログ用…）。
1つのチャットを延々と続けると、古い文脈に引きずられて精度が落ちます。
新しいチャットを開いたら、上のルール読み込みも毎回やり直してください。

### 3-2. API を実装するとき

```
@d-watch-api.yaml の GET /prechecks を Next.js の APIルートで実装して。
app/api/clean-logs/route.ts と同じ形で、データは lib/db から取得して。
```

`d-watch-api.yaml` がAPIの仕様書（契約書）です。**これに書いてあるとおりに作ります。**

### 3-3. 画面を作るとき

モックの該当部分を見せながら依頼するのが確実です。

```
モックの清掃詳細ログ画面を Next.js のコンポーネントに移植して。
テーブルのカラムとフィルタはモックのとおりに。
```

### 3-4. エージェントに任せるとき

コマンド実行も含めて依頼できますが、**実行前にコマンドの中身を必ず読んでください。**
特に削除系（`rm`、`Remove-Item`）と上書き系は、確認せずに `Run` を押さないこと。

また、エージェントは「やりました」と言って実際にはやっていないことがあります。
結果は自分で `git status` や画面表示で確認してください。

---

## 4. これだけは守ってほしいこと

`CLAUDE.md` の「7. 禁止事項」に全部書いてありますが、特に事故りやすいものを4つ。

### ❌ 認証情報をコミットしない
DB接続情報やAPIキーは `.env.local` にだけ書きます。
一度GitHubに上げると履歴から消すのが大変です。

### ❌ 丸めた値で判定しない
完了率90.4%は、表示は「90%」ですが判定は**◎**です。
丸めてから判定すると◎が消えます。判定は必ず丸める前の値で。

```ts
// ✅ 正しい
const grade = judgeGrade(rawRate);      // 生の値で判定
const display = Math.round(rawRate);     // 表示用に丸める
```

### ❌ 閾値をハードコードしない
90 / 70 / 10、猶予30分、L2=2日 / L3=3日 は、あとから変わる可能性があります。
**`lib/config/` から読む形にしてください**（もう用意してあります）。

### ❌ 仕様が分からないところを推測で埋めない
資料に書いていないことが出てきたら、**手を止めてDaigoに聞いてください。**
推測で作ると、あとで全部やり直しになることがあります。

---

## 5. 判定ロジックについて

◎○△×の判定、L1〜L3のエスカレーション、KPIの計算 — このあたりは
**間違えると運用が成立しない**ので、必ずテストを書きます。

- 仕様は `CLAUDE.md` の 4.1〜4.5
- テストに入れるべき値は `docs/fixtures.md` の「判定の境界値」の表
- Cursorに書かせたコードをそのまま信用せず、テストが通ることで確認します

`lib/judge/` は Daigo が先に用意します。それまでの間、
`lib/fixtures/clean-logs.ts` にある `expectedGrade()` は fixture 生成用の暫定実装なので、
**画面コードからは呼ばないでください**（`lib/judge/` ができたら削除します）。

ここだけは慎重にお願いします。他はある程度スピード優先で大丈夫です。

---

## 6. 困ったとき

| 状況 | どうする |
|---|---|
| 仕様が分からない | `CLAUDE.md` → `docs/spec.md` → `docs/decisions.md` の順に探す。なければDaigoに聞く |
| APIの形が分からない | `d-watch-api.yaml` を見る |
| APIの書き方が分からない | `app/api/clean-logs/route.ts` を見る（動く見本） |
| 画面のデザインで迷う | モック（`d-watch-mock.jsx`）が正。それでも迷ったらUI仕様書v6.0 |
| サンプルデータに欲しいケースがない | `lib/fixtures/` に足してOK。`docs/fixtures.md` も更新する |
| どういう運用で使われるか知りたい | `D-Watch_運用ガイド`（Googleドライブ） |
| 資料同士が矛盾している | Daigoに連絡（資料側を直します） |

---

## 7. 用語のメモ

| 用語 | 意味 |
|---|---|
| D-Watch | このシステム。清掃ロボットの稼働監視ビューアー |
| D-Security | オプション機能。セキュリティ解除→清掃→復帰の自動化 |
| 清掃エリア | 施設内の清掃対象区域。「区画」とも呼ばれていたが**清掃エリアに統一** |
| 施設 | ロボットが置かれている店舗 |
| 事前チェック | 清掃開始の60分前/30分前にロボットの状態を確認する仕組み |
| Pudu Cloud | ロボットメーカー(PUDU)のクラウド。ロボットの状態やタスク結果の取得元 |
| TeamWorks | DBとデータ収集を担当している外部の開発会社 |