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

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

0. 最初に読むもの

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

余裕があれば 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/ の下がおすすめです。

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 したディレクトリの中で、このリポジトリ用のコミット情報を設定します。

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

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

確認：

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

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

1-6. 起動

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。

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

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

2-3. ブランチとPR

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

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

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

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%」ですが判定は◎です。 丸めてから判定すると◎が消えます。判定は必ず丸める前の値で。

// ✅ 正しい
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. 困ったとき

7. 用語のメモ