CLAUDE.md — D-Watch 開発コンテキスト

このファイルは Cursor / Claude Code が最初に読むプロジェクトコンテキストです。 実装前に必ず全文を読んでください。 特に「4. 確定仕様」と「7. 禁止事項」は仕様のズレが直接バグになる箇所です。

0. ルールの優先順位

セッション開始時に自動注入される全社共通の作業ルールと、本ファイルの記述が衝突した場合は 以下を優先する。

1. 仕様が不明なら止まる。 全社ルールの「自動モード中は許可待ちで止まらない」は権限確認についての取り決めであり、 仕様の不明点には適用しない。§7 の通り、推測で実装せず確認を求める。 判定基準・閾値・API契約の不明点は特に危険（仕様のズレが直接バグになる）。

2. 判定ロジックは「期待値表の確定 → テスト作成 → 実装」の順を崩さない。 実装を分担・委譲する場合も、期待値表の確定は分担しない（§4.3 / §6.2）。 境界値（完了率 90.0 / 90.1 / 70.0 / 70.1 / 10.0 / 9.9 / 0 / 未実施、 および 89.5 → 表示90% だが判定は ○）は本ファイル §9.4 の表を正とする。

3. 日本語を含む成果物には日本語フォントを明示する。 欧文フォント（Geist 等）は日本語グリフを持たないため、指定しないと フォールバックで中国語フォントに落ち、漢字が中華字形で表示される。 app/globals.css のフォントスタックを正とし、日本語フォントを外さない。

1. プロダクト概要

D-Watch（DFAロボット監視システム） は、店舗等に配置された清掃ロボットの稼働を監視するSaaSビューアーです。

• 夜間に自動実行された清掃の結果を、翌朝DFA運用担当が確認する「翌朝確認型」の運用
• 問題のある施設を検知し、AIが推定原因と対応アドバイスを提示する
• オプションモジュール D-Security（セキュリティ解除→清掃→復帰の自動化）の監視画面も含む

P1スコープ | 項目 | 範囲 | |---|---| | 対象顧客 | 株式会社ドン・キホーテのみ | | ロボットメーカー | PUDU Roboticsのみ（KeenonはP2以降。Whiz iは機能的に劣るため取り扱わない） | | 対応機種 | PUDU CC1のみ（将来候補: PUDU MT1 / Keenon C30 / C40。lib/config/index.ts の ROBOT_MODELS が正。D-087） | | 利用者 | DFA社内のみ（顧客アカウントはP2以降） | | セキュリティ会社 | SECOMのみ |

2. 責任分界 — 何を作り、何を作らないか

★DFA が作るのはビューアー（本リポジトリ）だけです★（2026-09-16 ユーザー確認。D-143）。 ★サーバーを契約し費用を払うのは DFA ですが、構築・保守は TeamWorks です★。 ★D-100 項5 の「DFA が構築するのはアプリ側（VM）」は誤りなので従わないこと★ （★ただし TeamWorks 側の明示確認は未取得。第9回 Q12-1 で照会中★）。

重要: メインDBのスキーマ変更・データ投入処理は本プロジェクトの仕事ではありません。 DBは基本的に読み取り専用で、書き込みは後述の4カラム（robot_error_reports は error_list_id を含む5カラム）のみです。

「APIサーバー」の意味: 本アプリ内の API ルート（app/api/）を指します。TeamWorks が API を 提供するわけではありません。DB へは Prisma で直接アクセスし、間に外部サービスは入りません。 画面はブラウザから自アプリの API ルートを呼び、その中で Prisma が DB を読みます（D-046）。

3. 技術スタック

★メインDBについての注記★（根拠: D-100。TeamWorks 回答 2026-09-10）

• ★なるべく MySQL 互換の SQL を使う★
• ★★MariaDB 特有の DML を使いたい場合は、その箇所を TeamWorks に知らせること★★
• ★ローカル検証環境は MySQL 8.4（dwatch_local）。本番は MariaDB 10.11 なので、 ★ローカルで通っても本番で通らない可能性がある★。生SQL（$queryRaw / $executeRaw）を 書くときは特に注意する★（現状、アプリコードに生SQLは1件も無い。すべて Prisma のクエリビルダ経由）

★★接続先についての注記★★（D-152。2026-10-01 ユーザー確認）

• ★★133.125.238.144 / clean_watch は ステージング★★。★本番DBは別にある★（2026-10-01 ユーザー回答 「これはステージングです、本番は他にあります」）
• ★★D-148（「本番DBそのもの」2026-09-17）は破棄★★。★第9回までの文書の「ステージング」「テスト環境」という呼称は ★正しかった★（D-148 項1 の「誤り」という訂正のほうが誤りだった）
• ★★2026-09-30 23:25〜10-01 00:09（JST）に実データが入った★★（2026-10-01 実測・先方投入。読み取りのみ）。 ★当方のダミー（scripts/seed-local-db.ts 由来）は消えている★。 facilities は ★ドン・キホーテの実店舗10件＋本社★。
• ★★DB に入っている時刻の値は、列の型（TIMESTAMP / DATETIME）によらず JST の壁時計の値★★ （ユーザー指摘 2026-10-01「データベース上の時間は全てJSTに変換済みです」。★実測で確認★: robots.updated_at の最新が生の値で 15:00、そのときの JST が 15:17・DB の NOW() が 06:17。生の値が UTC なら9時間後の未来になり、ありえない）。 ★生の値に9時間を足さないこと★。
  • ★★2026-10-02 TeamWorks 回答（第10回 N-14・N-6c）★★: ★それまでサーバーの時計は UTC（@@system_time_zone = UTC）で、 一部のテーブルはフレームワークの機能を切って書いていたため、current_timestamp() の既定値で UTC の値が入っていた★。 ★DB の既定のタイムゾーンを 'Asia/Tokyo' に変え、データを再登録済み★（先方の申告。★当方の再実測は未了★ — 10-02 は認証エラーで接続できず）。 ★先方の結論: 「timezone を JST で統一したので、以降はズレは生じない」★
  • ★当時の9時間ずれの正体★: control_reports.reported_at は ★UTC で書かれていた★（N-14a）。 robot_error_reports.errored_at は ★正しい JST の値で、ずれていたのは created_at（UTC）の側★（N-14b）。 ★旧記述の「errored_at は二重補正・エラー検知時刻は9時間遅く出る」は誤り★
  • ★アプリのコードは変えない★（2026-10-02 調査）: アダプタは dateStrings: true で、サーバーが返した文字列を UTC とみなすだけ。 ★サーバーが JST になったことで、TIMESTAMP 列も JST の文字列で返り、fromDbJst() の前提どおりになる★。 ★残る危険は、再登録されなかった古い TIMESTAMP 行だけ★（そこだけ +9時間に見える）。★再実測で確かめること★
  • ★一度「TIMESTAMP は UTC で返るので +9時間」と誤って書き（9c175a2）取り消した（d540335）経緯あり★。★推測で9時間ずらさないこと★ ★clean_timetables / clean_schedules / clean_status_histories は0行★、 clean_task_reports は2行（どちらも clean_timetable_id が NULL）。★サーバー本体は昨日と同一★（@@hostname 一致）
• ★帰結★: ★予定が0行なので、清掃詳細ログ・ダッシュボード・アラートは空★。★総清掃面積だけは実績を直接集計するので2回と出る★ （画面どうしで食い違う。★詳細ログを予定起点・実績起点・両方のどれにするかは、データが入ってから検討★。D-151 項7） ★以上は 2026-10-01 時点★。★2026-10-06 は予定が入り始め（先方投入中。予定と実績はまだつながっていない。D-158 末尾）、 ダッシュボードは「各清掃エリアの直近の清掃（7日以内）」（D-159）で11エリアを出した★（先方投入。docs/handoff.md 追記61）
• ★robot_error_reports.serial_number の実値★（2026-10-19 監督の SELECT・先方投入）: セキュリティ（SECURITY_ON）・清掃開始失敗（NOT_STARTED）の行は ★---★（第11回 P-8 の回答は 0）。★serial_number の値や robot_id IS NULL で区分を見分けない — error_type で見分ける★（D-180 項5）。どちらに揃うかは TeamWorks に照会予定（指示書AX §12-1-2）
• ★接続元の制限・TLS（第9回12章）は★検証段階のため保留。顧客へ配布するときに検討する★（ユーザー判断 2026-10-01）。 ★セキュリティの強化はリリース直前にまとめて行う★（ユーザー判断 2026-10-01。D-154）。★その時の対象★: 接続元の制限・TLS（または閉域）、★ステージングDBのパスワード変更★（コメントに実物が入っていた。履歴に残る）、★ALLOW_ALL_WHEN_EMPTY を拒否に倒すか許可リストを入れる★（lib/config/allowed-ips.ts）、★ログインの試行回数制限と cookie の中身★（lib/auth/cookie.ts）、★制御盤のログ中継（作ったら）: 読めるのはログのフォルダだけ・読み取り専用・制御盤ごとの認証★／★許可リストを入れると店舗の制御盤（/api/ds-agent/）が弾かれる — 店舗の IP を載せるか、その経路だけ IP 制限を外してトークン必須にするか★（D-179。未実装）／★CSP を入れるなら app/layout.tsx の <head> のインラインスクリプト（表示設定の復元。D-183）に nonce が要る★ ★第10回では照会しない★。★本番を組むときは、アプリとDBを閉域でつなぐか、DBに TLS を入れるかのどちらかが要る★
• ★★ステージングには、4カラム（status / comment / responded_at / resolved_at）の UPDATE を書き込んでよい★★ （ユーザー指示 2026-10-01「書き込んでよい」）。★実データ（ドン・キホーテのエラー行）の対応状況が書き換わることを承知のうえ★。 ★4カラム以外への書き込みは引き続き禁止★（§7。権限も無い）。★例外は robot_error_reports.error_list_id だけ★（下の「DB接続アカウント」。D-184）。★scripts/seed-local-db.ts は★ステージングに絶対に向けない★ （テーブルを消してから入れ直すため、実データが消える。lib/db/local-guard.ts が dwatch_local 以外を拒否する）
• ★旧: 「本番DBへは書き込まない（2026-09-17）」「書き込んで安全な環境ができるまで着手しない」★ — D-152 で解除

DB接続アカウント（2種）

1. 参照用: 全テーブル SELECT のみ
2. 更新用: robot_error_reports / control_error_histories の status, comment, responded_at, resolved_at のみ UPDATE 可
   • ★加えて robot_error_reports.error_list_id（エラー内容。error_lists.id）★（D-184。2026-10-27 ユーザー回答「すでに更新権限があると思う」。 ★SHOW GRANTS での確認は未了★ — ステージングに接続できないため）。★control_error_histories には無い列★

この4カラム（robot_error_reports は error_list_id を含む5カラム）以外への書き込みコードを書かないでください。権限エラーになります。 ★error_list_id を書くのはエラー一覧の PATCH /errors/{error_id}/status だけ★（事前チェックの /prechecks と D-Sec の保存は4カラムのまま。lib/db/robot-error-write.ts）。

4. 確定仕様 — 実装時に必ず守るルール

ここに書かれた数値・ロジックは TeamWorks との合意事項です。 変更したくなった場合は勝手に変えず、docs/decisions.md を確認し、必要なら合意を取り直してください。

4.1 判定基準（◎○△×）

清掃完了率にもとづく4段階判定。閾値は設定値として外出しする（ハードコード禁止）。

★境界はすべて「上のランクに入る」★（ユーザー指示 2026-09-16「◯、×は90%以上のように境はふくめてください」。D-139）。 90.0 は ◎、70.0 は ○。★× の境界だけは「10%未満」のまま★（同日「10％未満を×としてください」で確定）なので、10.0 は △。 ★D-020b（境界はすべて下のランクに落ちる）は破棄★。

4.2 KPI計算式（週次/月次/年次の集計期間内）

稼働率       = 正常終了（status = 4）の回数 ÷ 清掃予定回数 × 100   ← ★第11回 P-6=A（2026-10-05）★
出発成功率   = 開始できた回数（レポート行がある回数）÷ 清掃予定回数 × 100   ← ★時刻の条件なし（P-6=A）★
清掃完了率   = Σ 1回ごとの完了率 ÷ 1回ごとの完了率が null でない清掃の回数   ← ★1回ごとの完了率 = min(clean_area ÷ task_area × 100, 100) を小数第1位までで切り捨て★
エラー発生率 = エラー発生回数 ÷ 清掃予定回数 × 100   ← ★分母は予定回数（P-6=B）★

★3つの率はサマリ（operation_ratio / launch_ratio / error_ratio）と同じ式★（第11回 P-6。ユーザー指示 2026-10-05「合わせてください」。D-158）。★旧: 稼働率 ＝ 実施回数 ÷ 予定・出発成功率 ＝ 定刻出発回数 ÷ 予定（実際は同じ値になっていた）・エラー発生率 ＝ ÷ 実施回数★。実装は指示書AU

★清掃完了率は「1回ごとの面積比（上限100・小数第1位まで切り捨て）」の単純平均★（★ユーザー判断 2026-10-02「一旦B」。D-155★）。 ★TeamWorks のサマリと同じ式★（第10回 N-3 の回答）。★clean_task_reports.clean_ratio 列は使わない★（先方が「計算式が間違っている。訂正したら回答する」）

• ★確定★（第11回 P-2=A「今の式のまま」。P-1: 訂正後の clean_ratio 列もこの式と同じ値になる。2026-10-05。D-158）。★D-151 の「clean_ratio 列の単純平均」は破棄★。 ★切り替えが1関数で済むよう、1回ごとの完了率を決める関数は1つにする★（lib/judge/kpi.ts。指示書AS）
• ★既知の弱点（承知のうえで採用）★: clean_area は★同じ場所を複数回清掃した面積の総和★（N-4）なので、面積比は清掃の網羅率ではない。 ユーザー提供CSV 189行では ★clean_area > task_area が 129行（68.3%）で、これらは全部 100% になる★。★◎が多めに出る★
• ★全画面で同じ定義★（レポートKPI 当期 / 総清掃面積 F-08 / エリア別完了率 / 要レスキュー R-3 / 詳細ログの1行）
• ★対象は本清掃（precheck = 0）に対応する行と、予定外のタスク★。★事前チェックの回は別の1件として数えない★。
  • ★★予定外のタスク（clean_timetable_id が 0 か NULL）も1件として数える（A案）★★（ユーザー指示 2026-10-29「エラー一覧以外も、予定外タスクを計算して出すようにしてください」「割合はA案で」。指示書BG）: 予定外1件 ＝ 清掃予定回数 +1・開始できた回数 +1・status = 4 なら正常終了 +1・1回ごとの完了率を平均に入れる。予定外のエラー（clean_timetable_id が 0 か NULL）もエラー発生回数・エラー内訳に入れる（期間は errored_at ?? created_at）。 予定外の期間の振り分けは started_at（実際に始めた時刻）。★予定外は未実施・結果待ちにならない★
  • ★今の期間（アプリが計算）だけ★。★確定期間は TeamWorks のサマリのまま★（ユーザー「サマリは変えて貰う予定です」）。サマリが変わるまで、今の期間と確定期間で予定外の扱いが違う
  • ★旧（2026-10-02〜10-29）: 予定外は完了率にも実施回数にも入れず、総清掃面積の面積の合計にだけ含めていた（D-155 項3）★
• ★task_area が 0 の行は、1回ごとの完了率を 0% とする★（第11回 P-5=B。2026-10-05。実装は指示書AU）。★旧（D-155 の暫定）: null として分子にも分母にも入れない★
• ★未実施（レポート行が無い清掃）は分子にも分母にも入れない★（0% として混ぜない）
• ★切り捨ては「1回ごとの値」だけ★。★平均した値は丸めずに判定し、表示のときだけ整数に丸める★（§4.3）
• ★浮動小数の罠★: 0.57 / 1 * 100 は 56.99999… になる。★切り捨ての前に誤差を吸収すること★（期待値表は指示書AS）

4.2.1 ダッシュボードの清掃結果（ユーザー指示 2026-10-29「4の計算式は仕様書に残して」。D-049 / D-173。実装は lib/dashboard/aggregate.ts の computeSummary()）

成功率 = 成功 ÷ (成功 + 失敗 + 未実施) × 100      ← ★結果待ちは分母に入れない★。分母0なら null（画面は「-」）

• ★対象の清掃★: 日付を指定しないとき（直近）は、★清掃エリアごとに1件★ — 開始が直近7日以内（DASHBOARD_LATEST_RUN.lookbackDays）で予定の終了を過ぎた本清掃のうち、開始が最新のもの（D-159）。日付を指定したときは、その日の本清掃すべて
• ★予定外のタスク（clean_timetable_id が NULL か 0）も1件として数える★（指示書BG。2026-10-29）。直近モードの候補は開始＝started_at・終了＝ended_at（null なら開始）。成功か失敗のどちらかになり、未実施・結果待ちにはならない。同じ清掃エリアで開始が同時刻なら予定のある行を採る（lib/dashboard/latest-run.ts の preferOnTie()）
• ★事前チェックの結果は使わない★（§4.4。D-170）
• ★丸めない★。表示のときだけ整数に四捨五入（§4.3）
• 進み具合（schedule_progress）= 対象日に出発した件数 ÷ 対象日の予定件数 × 100（予定件数0なら null）。★対象日は、日付を指定しないとき日本時間の前日、指定したときはその日★（ユーザー判断 2026-10-29「B」 — 清掃結果は前夜の分なので、今日の予定で数えない）。 ★予定件数は予定の表（clean_timetables / clean_timetable_histories の本清掃）の行数★。★clean_schedules の曜日の設定は使わない★（旧。2026-10-29 ステージングで今日の予定が 7件 対 5件と食い違った）。結果待ち・未実施は予定件数にだけ入る。★対象日に始まった（started_at）予定外タスクは予定件数にも出発件数にも1件ずつ入る（A案。指示書BG）★。応答の schedule_progress.date が対象日。lib/dashboard/aggregate.ts の scheduleProgressTargetDate() / computeScheduleProgress()。★要レスキュー・セキュリティのバナーは当日のまま★

4.3 端数処理 ★事故りやすい★

• 表示: 小数第1位を四捨五入して整数で表示する（例: 91.4% → 91%）
• 判定: ◎○△× と L1〜L3 の判定は、丸める前の生値で比較する

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

// ❌ 間違い（89.5%が丸めで90%になり、本当は○なのに◎になる）
const rounded = Math.round(rawRate);
const grade = judgeGrade(rounded);

4.4 清掃開始/終了/失敗の判定

猶予30分は暫定値。設定値として外出しする。

★レポートがまだ無い清掃は「結果待ち」★（ユーザー判断 2026-10-07。D-173）: 予定の開始 ≤ 今 ＜ 予定の終了＋RESULT_WAIT_MINUTES（120）のあいだは失敗に数えない（lib/clean-logs/result-pending.ts の1本。API は CleanLogItem.result_pending）。過ぎたら出発失敗（未実施）。★上の「猶予30分」（LAUNCH_GRACE_MINUTES）はコードで使っていない★（D-091）

★事前チェックの結果も有無も、成功・失敗の判定に使わない★（ユーザー指示 2026-10-07「事前チェックを行っていない清掃や事前チェックが失敗した清掃でも本清掃が成功していれば成功にしてください」。D-170 / D-048）。判定は本清掃のレポート行の有無と完了率だけ。lib/dashboard/__tests__/aggregate.test.ts が見張っている

★「タスクレポートが中断で返る」は、いまは判定に使っていない★（ユーザー判断 2026-10-02。D-155 項2）。clean_task_reports.status（2 清掃中断 / 3 清掃キャンセル / 5 清掃異常終了）は★表示名として出すだけ★で、◎○△× は完了率で決め、未実施（出発失敗）は★レポート行の有無★で決める（§4.7）。★実データが入ってから見直す★

4.5 エスカレーション（Phase A: R1〜R4）

「連続」はカレンダー日ではなく「スケジュール存在日の連続」で数えます。清掃予定がない日は連続を途切れさせません。

★予定外のタスクも、その施設のその日（started_at）の結果に入れる★（指示書BG。2026-10-29）— 連続日数・L1〜L3・要レスキュー・連続問題施設のすべて。★予定外だけの日も「スケジュール存在日」★（完了率 70 未満なら問題日、以上なら連続が切れる）。★予定外は未実施にならない★ので、要レスキューの「未実施の連続」は予定外だけの日で切れる。清掃詳細ログの予定外の行の連続日数は施設×日付で引く（consecutiveProblemDaysByFacilityDate()）

4.6 契約フラグ

• facilities.contract のみが正。★varchar(10) の文字列★であり、★数値ではない★（D-080）
  • ★桁位置がサービスに対応する★。★1桁目 = D-Security / 2桁目 = D-Watch★。 ★契約済み（有効）なサービスの桁を 1 にする★
  • 値の例: 0000000000 = 未設定（既定値） / 1000000000 = D-Securityのみ / 0100000000 = D-Watchのみ / ★1100000000 = 両方★
  • 3桁目以降は将来のサービス用の予備と読める（★定義書に明記なし。P1では読まない★）
  • ❌ ★数値として比較しないこと★。Number("0000000000") は例外を出さずに 0 になり、 contract === 3 のような比較は絶対に真にならない。結果として ★全施設が「契約なし」になりメニューが全部消えるが、例外もテスト失敗も出ない★
  • boolean（monitoring_enabled / d_security_enabled）への変換は ★lib/format/ か lib/config/ の純粋関数1箇所に閉じ込め、桁位置をハードコードしない★（D-080）
• customers.contract は削除依頼済み。参照してはいけません
• ★★contract という列は2つあります★★（2026-09-17 実測。prisma/schema.prisma:141 と :571。行番号は 2026-10-05 時点）
  • ★facilities.contract★（:141）＝ ★これが正★
  • ★clean_schedules.contract★（:571）＝ ★読まないこと★。★型も既定値も facilities と同一★ （varchar(10) / "0000000000"）なので、★取り違えても型エラーにならない★。 ★現在のアプリは読んでいない（正しい状態）★
  • ★用途は未確認★。TeamWorks の定義書にも説明が無い
• メニューの表示制御もこのフラグに基づく（契約のないセクションはメニューごと非表示）
  • ★未実装★（2026-10-06 確認。components/layout/AppShell.tsx は全メニューを無条件に描く）。★P2 で作る。顧客に使わせる前に必ず入れる★（ユーザー判断 2026-10-06。D-160 追記4）

4.7 集計期間とバッチ

• バッチは TeamWorks が実装。DFAはサマリテーブルを読むだけ
• ★週次バッチの「前週」は、月をまたぐと2行になる（D-071 の帰結。第5回 X-3 は TeamWorks 承認済み。D-074 項3。2026-09-08）★ 例: 2026-09-06(日) 6:00 のバッチは 2026/8/6週(08-30〜08-31) と 2026/9/1週(09-01〜09-05) の2行
• ★サマリの粒度は month / week が 0 かどうかで判別する（week=0 が月次、month=0 AND week=0 が年次。 第5回 X-2 は TeamWorks 承認済み。D-074 項3。2026-09-08）。week=0 は予約値なので、API の week は 1 以上のみ受け付ける★
• 進行中の期間（当週・当月・当年）はサマリテーブルに存在しない。 詳細テーブルからその場集計すること
• ★★データの取得元（ユーザー指示 2026-09-30。指示書AQ）★★| 何を | どこから | |---|---| | ★確定期間（週・月・★年★）のKPI★ | ★customer_summaries / facility_summaries（率4列）/ facility_error_summaries★ | | ★直近・昨日・当期の清掃実績★ | ★clean_task_reports★ | | 清掃の予定 | ★clean_timetables と clean_timetable_histories の両方★（precheck = 0 が本清掃）。★同じ id は clean_timetables 側を採る★（履歴の id は本表の id のコピー。D-158 項4・指示書AU 段階3b。読み口は lib/db/timetable-source.ts の1か所） | | ★エラー（制御盤のエラーも含めて）★ | ★robot_error_reports に集約★（★制御盤・セキュリティ・清掃開始失敗のエラーも入る（第11回 P-8〜P-10。D-158）★。★先方の DDL で robot_id は NULL 可になったが、Prisma は未 db pull（NOT NULL のまま）★。読み取りは lib/db/robot-error-select.ts で robot_id / robot を読まない（指示書AU 段階0）。★D-Sec アラートは robot_error_reports のうち error_type が D-S_CONTROL_FAILURE の行だけ（完全一致。SECURITY_ON・NOT_STARTED は出さない）を読み、対応状況・備考はエラー一覧と同じ PATCH /errors/{error_id}/status で書く（D-180）★。★control_error_histories は読まない★。★削除済み（deleted_at が NULL でない）の施設・清掃エリアの行は、エラー一覧（meta.total も）にも D-Sec アラート（summary・ダッシュボードも）にも出さず、その PATCH は404（U8。D-180 項11）★。★施設名・分類の解決は従来どおり deleted_at で絞らない（指示書AX 罠7）★。★区分（ロボット／制御盤／セキュリティ／清掃開始失敗）を画面に作るのは次フェーズ★。★全行（削除済みの施設・清掃エリアの行を除く。U8）の一覧と4カラムの更新はエラー一覧（/errors。D-160・指示書AW）★） |
  • ★clean_status_histories は読まない★（clean_task_reports に一本化。テーブル自体は TeamWorks の管理下なので残る）
  • ★年次は解禁済み★。★D-072 項4 の「P1では年次を読まない」は破棄★。 ★periodOfSummaryRow()（lib/db/report-mapping.ts）は month も見ること★ — week===0 だけで判定すると ★年次行が月次に化けて混入し、重複検知で500になる★
  • ★未実施 ＝ 本清掃に対応する clean_task_reports の行が無いこと★。clean_task_reports には clean_error 相当の列が無い。★「出発失敗」と「未実施」は同じ扱い★（ユーザー確認 2026-09-30）
  • ★clean_task_reports.status は表示名に変換して表示する★（第10回 N-2 で TeamWorks が定義。D-155）: 0 清掃開始前 / 1 清掃中 / 2 清掃中断 / 3 清掃キャンセル / 4 清掃正常終了 / 5 清掃異常終了。★表に無い値（CSV実測の 6 など）は生値のまま出す★（「その他」に潰さない。§4.8 と同じ考え方）。★判定には使わない★（中断・異常終了でも完了率で ◎○△× を出す。ユーザー判断 2026-10-02。§4.4 の「中断で返る＝失敗」は実データを見て見直す）
  • ★clean_task_reports.clean_timetable_id は nullable★。CSV実測では189行すべて NULL。 ★NULL は「予定外のタスク」（下の項目。第10回 N-1 で TeamWorks も同意）★で、★欠損ではない★。★2026-10-29 から今の期間の集計・清掃詳細ログ・ダッシュボード・清掃エリアに1件として入れる（§4.2・指示書BG）★（旧: 完了率・実施回数には入れない。D-155 項3）。 ★旧: 「NULL は TeamWorks が今後埋める前提」（2026-09-30）は、10-01 のユーザー回答で取り下げ★
  • ★ステージングの clean_task_reports は 2026-10-01 に2行入った★（それまでは0行。2026-09-30 実測で update_time が NULL＝作成以来一度も書かれていなかった）。
  • ★★clean_timetable_id が NULL の行は「予定外のタスク」★★（ユーザー回答 2026-10-01「清掃予定をサーバーで決められるものは 今後 clean_timetable_id が発行されるが、予定外のタスクは NULL になる」）。★NULL は欠損ではなく、実在する清掃★
  • ★★clean_timetable_id が 0 の行も「予定外のタスク」★★（TeamWorks 回答 2026-10-27「clean_timetable_id が0以外は予定/実行済タスクになりますし, 0は予定外タスクになります」。 clean_task_reports と robot_error_reports の両方）。★NULL も引き続き予定外★。★判定は lib/db/timetable-link.ts の scheduledTimetableId() 1本★（=== null / { not: null } を直書きしない）。 ★予定タスクを持つのは clean_timetables / clean_statuses / clean_timetable_histories / clean_status_histories の4表★（同回答。アプリが予定として読むのは clean_timetables / clean_timetable_histories の2表）。 ★事前チェックの回（precheck ≠ 0）には clean_task_reports / robot_error_reports の行が入らず、clean_statuses / clean_status_histories は clean_status=2・clean_status_trans=0・clean_error=0 になる予定★（同回答）。★事前チェックの表示の仕様は変えない★（ユーザー指示 2026-10-27「この仕様から特に変更はない」 — 事前チェックの回に紐づく robot_error_reports を失敗として出す）
  • ★★clean_task_reports.started_at に入る値★★（ユーザー回答 2026-10-05「A」で確定）: ★予定のある清掃は予定の clean_timetables.start_at と同じ値★、★予定外のタスクは実際に清掃を始めた時刻★。★過去形の列（started_at / ended_at 等）は実施後に書かれる★（2026-10-01 ユーザー回答） 例: 9/30 23:50 の予定が 10/1 00:10 に始まっても started_at は 9/30 23:50。★帰結: 期間の振り分けは、レポート当期（予定の start_at）・総清掃面積（started_at）・サマリ（第10回 N-9=A started_at）で一致する★。★予定のある清掃の実際の開始時刻は、この列からは分からない★（定刻出発の判定には使えない）。★旧: 「started_at は実際に清掃を始めた時刻」（10-01）は、予定外のタスクについてだけ正しい★ ★2行ともどちらも clean_timetable_id が NULL、status は 4★（2026-10-01 実測・先方投入。§3 の接続先注記も参照）
  • ★ユーザー提供CSV（189行）は、当時のステージングとは別のDBから出たもの★（IDの体系が違う）。 ★ただし 2026-10-01 に入った2行の対象面積（1377.39502 / 898.892509）がCSVの値と完全に一致する★ので、 ★同じ収集処理のデータと考えられる★。★出所は第10回で確認する★
• サマリには丸め前の小数と分子・分母が格納される（検算可能にするため）
  • ★★実DDLと食い違っています★★（2026-09-30 実測・構造由来）。 ★task_count（予定回数）/ launch_count / error_count はあるが、★実施回数の列が無い★★ （prisma/schema.prisma:694-696 / :728-730。2026-10-05 時点）。 ★率は4つとも実在する★（operation_ratio / launch_ratio / clean_ratio / error_ratio）
  • ★帰結★: ★稼働率は検算できず、複数顧客の合算もできない★（★率は加重平均できないため★）。 ★第9回 Q6-2 で実施回数の列の追加を依頼中★
• ★月跨ぎ週は「月境界で分割する」★（D-071 で確定。2026-09-07。TeamWorks のサマリ集計に合わせた）
  • 週は日曜〜土曜。ただし月をまたぐ週は1日で切り、それぞれの月に別々の週として数える
  • ★週の長さは1〜7日で変わる。月の週番号は1〜6★（第6週は年2〜3回発生する）
  • 各月の第1週は必ず1日から始まり、最終週は必ず末日で終わる
  • 例（2026年）: 8月第1週 = 08-01 のみ（1日） / 8月第6週 = 08-30〜08-31（2日） / 9月第1週 = 09-01〜09-05（5日） / 9月第2週 = 09-06〜09-12（7日）
  • 帰属ルールを知っているのは lib/format/period.ts の weekOfMonth() だけにする
  • ★D-067 の旧DFA案（1日を含む週がその月の第1週）は破棄。同じ週を2つの月に分けない 方式だったため、TeamWorks の週次サマリと帰属がズレる★

4.8 エラー種別は変換しない（D-077）

• ★robot_error_reports.error_type も robots.status も、DBから来た値をそのまま表示する★
• ★7分類（ハンドルアップ / LostLocation / オフライン / ブラシエラー / 緊急停止 / 充電不足 / その他） への変換は行わない★
• 理由: 現状 Pudu API から何が返るか不明なため。★推測でマッピングしない★ （§7 の「仕様が不明な箇所を推測で実装すること」の禁止に合致）
• ★D-057 / D-067 の「サーバ側で7分類に寄せる／未知の値は other に寄せる」は破棄★
• ★robots.status = -200（LostLoaction）→「LostLocation」の変換もしない★ （D-070 でそう確定していたが取り下げ。「-200 が LostLocation である」という事実認識は取り下げない。 取り下げるのは画面に出す前に変換する実装方針だけ）
• ★docs/handoff/analysis/error-type-mapping.md は参考資料。実装の下敷きではない★
• ★帰結: 画面には英語識別子（例 EmergencyStop）がそのまま出る。それが意図した挙動★
• ★注意: lib/theme-status.ts の色分けは日本語6文字列の完全一致なので、生値では全部グレーに フォールバックする★

5. 参照資料 — 何が「正」か

資料間で矛盾があったら、上の表の「正」に従ってください。それでも解決しない場合は実装を止めて確認を求めてください（推測で埋めない）。

6. 作業ルール

1. API契約を変えたくなったら、先に d-watch-api.yaml を直す。 実装だけ変えてYAMLと乖離させない
2. 判定ロジック（◎○△×・L1〜L3・KPI計算・丸め）には必ずテストを書く。 期待値表を先に作り、それをテストで固定する。目視確認だけで済ませない
3. 開発は lib/fixtures/ のサンプルデータで行う。 実DBの完成を待たない。
   • APIルートは USE_FIXTURES で fixtures / Prisma を切り替える。画面側のコードは切替を意識しない
   • 判定ロジックは切替の外側に置く（fixture開発中も本番同等のロジックが走る）
   • 用意すべきケースは docs/fixtures.md を参照（境界値・異常系を先に仕込む）
4. TeamWorks待ちの機能はスタブ/モックで先行し、解消後に差し替える。 ブロックされない
5. PRは必ずもう1人がレビューしてからmainにマージする（★レビュー担当は daichi。D-154★）
6. 「実測」と書くときは、その数字の出所を必ず併記する。 「当方のシード由来（scripts/seed-local-db.ts / lib/fixtures/）」/「先方投入」/ 「構造（information_schema / SHOW / EXPLAIN）」のどれかを書く。出所を書けない数字は 「実測」と呼ばない。
   • 理由: テストDBの行が当方のダミーだと気づかないまま、それを根拠に外部（TeamWorks）へ 照会する文書を作りかけた（2026-09-17。送付前に気づいた。 docs/handoff/テストDBのデータ出所_20260917.md）
   • この事故は docs/decisions.md D-111 項7（:6683-6689。2026-09-11）が5日前に予告していた — 「テストDBでは判定できない: 本番のデータ量 / サマリバッチの実挙動 / 本番の time_zone 設定」。 表はあったのに守られなかった

7. 禁止事項

• ❌ メインDBへのマイグレーション作成・スキーマ変更（TeamWorksの領域。prisma db pull で取り込むだけ。 db pull 実施前の prisma/schema.prisma 手書きは対象外、D-056参照）
• ❌ §3 で指定した4カラム（robot_error_reports は error_list_id を含む5カラム。D-184）以外へのDB書き込み
• ❌ 表示用に丸めた値で判定すること（4.3参照）
• ❌ customers.contract の参照（削除依頼済み。facilities.contract を使う）
• ❌ 閾値（90/70/10、猶予30分、L2=2日/L3=3日）のハードコード（設定値として外出し）
• ❌ 点検記録データをメインDBに保存すること（DFA独自ストアに分離）
• ❌ トークン期限/残日数の実装（仕様から除外済み。古い資料に記述が残っているが実装しない）
• ❌ モックに残っている実在の住所・電話番号をそのまま使うこと（ダミー値に置換する）
• ❌ 仕様が不明な箇所を推測で実装すること（確認を求める）
• ❌ エラー種別を推測で7分類に変換すること（D-077。DBの値をそのまま表示する。§4.8参照）
• ❌ git add -A の使用（過去に別作業の途中ファイルを巻き込む事故が起きている。 ★必ずファイルパスを明示する★）

8. 用語

P1の前提: 1清掃エリア = 1ロボット。 テーブル構造は複数台対応可能ですが、P1ではこの前提で実装します。

9. 実装規約

9.1 ディレクトリ構成

app/
  (dashboard)/           画面。モックの画面IDに合わせる
    dashboard/ detail-log/ alerts/ ds-logs/ ds-alerts/
    facilities/ inspections/ reports/ schedules/ system/
  api/                    APIルート
    clean-logs/
      route.ts
      export/route.ts
      [id]/advice/route.ts
      [id]/areas/route.ts
    settings/
      advice/route.ts
components/
  ui/                     Pill, FilterButton, GradeBadge 等の共通部品
  features/               画面固有のコンポーネント（例: detail-log/）
  layout/                 AppShell 等
  theme/                  ThemeProvider
lib/
  judge/                  ★判定ロジック（◎○△×、L1〜L3、KPI計算、丸め）+ __tests__/
  fixtures/               サンプルデータ（DB接続前の開発用。docs/fixtures.md 参照）
  db/                     USE_FIXTURES で fixtures / Prisma を切り替える
  config/                 閾値等の設定値
  clean-logs/             清掃ログ関連のクエリ
  settings/               運用設定（アドバイス等）
  types/                  型定義。YAMLのスキーマ名と揃える
  format/                 表示整形（日時等）
docs/                     spec.md, decisions.md, fixtures.md 等
prisma/schema.prisma      db pull実施後は生成物を正とし手で書き換えない（D-056）。実施前は定義書ベースで手書き
d-watch-api.yaml          API契約
d-watch-mock.jsx          画面レイアウト・文言・遷移の正

9.2 命名

• ファイル/ディレクトリ: kebab-case（detail-log/）
• コンポーネント: PascalCase（CleanLogTable.tsx）
• 関数・変数: camelCase
• DBカラム: snake_case（テーブル定義書の物理名をそのまま使う。勝手にリネームしない）
• API のクエリパラメータ・レスポンスキー: snake_case（YAML準拠）
• 型: lib/types/ に集約し、YAMLのスキーマ名と揃える（CleanLogItem, PrecheckItem 等）

9.3 コーディング規約

• any 禁止。型が不明ならYAMLのスキーマから起こす
• APIレスポンスは必ず型を定義してから実装する
• 日時は ISO 8601（JST, +09:00）。表示整形はコンポーネント側
• 数値の丸めは表示層でのみ行う。ロジック層には生値を渡す
• エラーレスポンスは { error: { code, message, details? } } で統一
• 一覧APIは必ず meta: { total, page, per_page } を返す
• 環境変数は .env.local。認証情報を絶対にコミットしない

9.4 判定ロジック（lib/judge/）

• テストを先に書く。 入力→期待値の表を作り、境界値を必ず含める
  • 完了率: 90.0 / 90.1 / 70.0 / 70.1 / 10.0 / 9.9 / 0 / 未実施(null)
  • 連続日数: 1日 / 2日 / 3日 / スケジュール非存在日を挟むケース
  • 丸め: 90.4 → 表示90だが判定は◎、89.5 → 表示90だが判定は○
• 閾値は lib/config/ から読む。ハードコード禁止
• 判定関数は純粋関数にする（DBアクセスを混ぜない）

9.5 サンプルデータ（lib/fixtures/）

• APIルートは USE_FIXTURES で fixtures / Prisma を切り替える。画面側は切替を意識しない
• 判定ロジックは切替の外側に置く（fixtureのデータにも本番同等の判定を通す）
• fixtures は DB接続後も削除しない（テスト・デモ用）

9.6 フロント

• モック（d-watch-mock.jsx）の画面レイアウト・文言・遷移を正とする
• 判定結果（◎○△×、L1〜L3、ソート順）はAPIから受け取る。フロントで再計算しない
• ダーク/ライト、JP/EN切替の器を壊さない

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.