# decisions.md — 決定事項と経緯 「なぜこの仕様なのか」を遡るための記録です。実装中に仕様を変えたくなったら、まずここを読んでください。 **過去に一度検討して却下した案が多く含まれています。** 同じ議論を繰り返さないための文書です。 記法: `[確定]` = 合意済み / `[暫定]` = 運用しながら調整 / `[回答待ち]` = TeamWorks確認中 --- ## アーキテクチャ ### D-001 `[確定]` バックエンドを Laravel から Next.js + Prisma に変更 - **決定**: Next.js（React + APIルート）+ Prisma + TypeScript の単一リポジトリ構成 - **背景**: 当初はTeamWorksが実装する前提でPHP 8 / Laravel 12を想定していたが、DFA内製（バイブコーディング）に方針転換した - **理由**: - 非エンジニア2名体制で PHP + JS の2言語を管理するのは現実的でない - Prisma の `db pull` でTeamWorks構築スキーマを自動取り込みでき、定義書との食い違いを機械検出できる - Cursor / Claude Code の生成精度が Next.js + Prisma で最も高い - **影響**: `d-watch-api.yaml`（OpenAPI）は実装言語非依存のため、そのまま流用可能 ### D-002 `[確定]` MCP経由のDB直結ビューアーは採用しない - **決定**: 従来通り API + ビューアーを実装する - **却下した案**: MCPでDBに直結し、AIが都度SQLを生成して表示する方式 - **理由**: - 常時表示・自動更新ができない（監視ダッシュボードの要件に反する） - 判定ロジック（◎○△×、丸め）の一貫性が保証できない - アラート対応状況の更新・写真アップロードが成立しない - P2の顧客開放時にDB直結ツールを顧客に配れない - **補足**: MCPは「開発の加速」と「社内アドホック分析」には有用。方式の置き換えではなく併用する ### D-003 `[確定]` インフラは「さくらのクラウド」（レンタルサーバではない） - **決定**: さくらのクラウド上のVM 1台。DBと同一ネットワークで閉域接続 - **理由**: - さくらの**レンタルサーバ**は共有ホスティング（PHP/CGI向け）でNode.js常駐プロセスを動かせない - さくらクラウドはガバメントクラウド認定済み、円安リスク回避、従量課金なしでコスト予測可能（確認事項#3） - **却下した案**: さくらVPS（クラウド内DBへの経路をインターネット越しに設ける必要があり非推奨） ### D-004 `[確定]` 点検記録はメインDBと分離した独自ストアで管理 - **決定**: SQLite + オブジェクトストレージ。TeamWorks構築DBには保存しない - **理由**: 点検記録はDFAの業務データであり、ロボット監視データとはライフサイクルが異なる。TeamWorksへの依頼・調整コストをかけずにDFA単独で改修できる状態を保つ - **影響**: 写真は Before/After × 7項目 = 最大14枚/記録。年間8,400枚程度を想定 --- ## データモデル ### D-010 `[確定]` 契約フラグは `facilities.contract` のみを正とする - **決定**: `facilities.contract`（0:未設定 / 1:D-Security / 2:D-Watch / 3:両方）を追加。`customers.contract` は削除 - **背景**: 当初、契約状態の表現が `customers.契約モジュール` / `clean_schedules.service_config` / facilities側フラグ の3箇所に分散していた（確認事項#14） - **理由**: 同一チェーン内でも店舗ごとに契約内容が異なるため施設単位が必須。顧客側にも持たせると二重管理による不整合の温床になる - **実装上の注意**: `customers.contract` を参照するコードを書かないこと ### D-011 `[確定]` `customers.group_id` は 0 をセンチネル値として使う（NULL不可） - **決定**: NOT NULL、デフォルト0。0 = グループなし - **背景**: 要件定義書3.4では「nullable」と記載していたが、TeamWorksがインデックス効率を理由にセンチネル値方式を採用 - **API層の扱い**: レスポンスでは 0 → `null` に変換して返す（`d-watch-api.yaml` は nullable 定義） ### D-012 `[確定]` 主要業務テーブルへの `facility_id` 追加 — ★実DDLで反映済み（2026-09-07 確認）★ - **依頼中**: robots / controls / clean_statuses / clean_statuses履歴 / clean_schedules / clean_timetables / robot_error_reports / control_error_histories / 清掃タスク報告 - **背景**: 当初は `section_id → facility_id → customer_id` の多段JOINが必要な構造だった（確認事項#17） - **理由**: DFAの運用は施設単位の参照・集計が中心。多段JOINなしで施設から直接引ける構造が必要 - **暫定対応**: 反映されるまでは多段JOINで実装し、追加後にクエリを単純化する - **★2026-09-07 追記: 依頼した9テーブルすべてに `facility_id` が存在することを実DDL （`clean_watch_20260907.sql`）で確認しました。多段JOINは不要です。** 確認したテーブル: robots / controls / clean_statuses / clean_status_histories / clean_schedules / clean_timetables / robot_error_reports / control_error_histories / clean_task_reports ### D-013 `[確定]` 対応日時は `responded_at` / `resolved_at` の2カラム — ★実DDLで反映済み（2026-09-07 確認）★ - **依頼中**: TeamWorksの初回実装は `responsed_at` 1カラムのみだった - **理由**: 画面で「対応開始」と「解消」を別々に表示するため、1カラムだとどちらかの時刻が失われる。綴りも `responded_at` が正 - **暫定対応**: APIスキーマは2カラム前提で先行実装 - **★2026-09-07 追記: `robot_error_reports` / `control_error_histories` の両方に `responded_at` と `resolved_at` が存在することを確認。綴りも正しい（`responsed_at` ではない）。 待ちは解消しています。** ### D-014 `[確定]` 障害サマリテーブルを追加 - **決定**: `customer_error_summaries` / `facility_error_summaries` を新規追加（TeamWorks対応済み） - **理由**: レポート画面のエラー種別内訳・連続問題施設の集計に、既存の顧客サマリ/店舗サマリでは粒度が足りなかった（確認事項#18） --- ## 判定ロジック・計算 ### D-020 `[確定]` 端数処理は「小数第1位を四捨五入して整数表示」 - **決定**: 表示は整数（例: 91.4% → `91%`）。清掃完了率も同様 - **経緯**: 当初「小数第2位を四捨五入して第1位まで」で提案したが、DFA判断で整数表示に変更 - **★重要**: **判定（◎○△×、L1〜L3）は丸める前の生値で比較する。** 丸めた値で判定すると 90.4% が 90% になり ◎ 判定が消える ### D-020b `[破棄]` 判定の境界値はすべて「下のランクに落ちる」 — ★★D-139 で逆のルールに変更（境界は上のランクに入る。90.0 は ◎、70.0 は ○）。★10.0 が △ であることだけは D-139 でも変わらない★★★ - **★2026-09-16: この規則は採用していません。D-139 が正です。**★ ユーザー指示「◯、×は90%以上のように境はふくめてください」により、 `judgeGrade()` の比較は `>` から `>=` に変わりました（× の「10%未満」だけは据え置き）。 - **決定（当時）**: 完了率 90.0 は ○、70.0 は △、**10.0 は △**（×ではない） - **背景**: `docs/fixtures.md` の境界値表で 10.0 を × と記載していたが、`CLAUDE.md` 4.1 の 「× = 完了率10%**未満**」と矛盾していた。M1の期待値表テストで検出 - **理由**: ◎は「90%超」、○は「70%超」と、境界値そのものは下のランクに落ちる規則で統一されている。 ×だけ「10%以下」にすると規則が崩れる - **対応**: `docs/fixtures.md` の表を修正。`CLAUDE.md` は変更なし（こちらが正） - **補足**: 完了率がちょうど10.000%になる実データはまず発生しないため運用影響はないが、 テストで値を固定する以上どちらかに決める必要があった ### D-021 `[確定]` 清掃完了率は面積ベース - **決定**: `Σ清掃面積 ÷ Σ清掃対象面積 × 100` - **背景**: 時間ベース / ルート距離ベースの可能性もあったが、Pudu Cloud管理画面の算出ロジックが面積ベースであることを確認（確認事項#13） ### D-022 `[確定]` サマリテーブルには丸め前の値と分子・分母を格納 - **決定**: 率カラムは小数のまま格納。あわせて分子・分母カラム（清掃予定回数 / 清掃実施回数 / 定刻出発回数 / 清掃面積合計 / 清掃対象面積合計 / エラー件数）を持つ - **理由**: 丸め済みの整数を格納されると判定ができなくなる。分子分母があれば数値検証（検算）も可能になる ### D-023 `[確定]` バッチは期末確定方式。当期はDFA側でその場集計 - **決定**: 週次=毎週日曜6:00に前週（日〜土）、月次=毎月1日6:00に前月、年次=毎年1/1 6:00に前年 - **帰結**: **進行中の週/月/年はサマリテーブルに存在しない。** 当期分はDFA側APIが詳細テーブルから集計する - **却下した案**: 毎日当期分を洗い替えする方式（DFA側実装は楽になるが、TeamWorks側のバッチ負荷が上がる） ### D-024 `[破棄]` 月跨ぎ週の帰属は「週の開始日（日曜）が属する年月」 — ★D-067 で逆のルールに変更★ - **DFA案**: 週の開始日基準。月次・年次集計は暦月・暦年の日単位で締める（週とは独立に集計） - **背景**: 週の定義が日〜土のため、月末が水曜の場合などに週が月を跨ぐ - **★2026-09-07: この案は採用しませんでした。D-067 が正です。**★ ### D-025 `[暫定]` 清掃失敗の判定猶予は30分 - **決定**: 予定開始時刻 + 30分を経過してもタスク開始が確認できなければ未実施と判定 - **注意**: 暫定値のため**設定値として外出しする**（ハードコード禁止） ### D-026 `[確定]` 「連続」はスケジュール存在日の連続 - **決定**: L2（2日連続）/ L3（3日以上連続）のカウントは、カレンダー日ではなく清掃予定がある日の連続で数える - **理由**: 定休日等でスケジュールがない日を挟んでも、問題の連続性は途切れていないため --- ## スコープ ### D-036 `[確定]` アドバイスは「発火条件＝仕様」「文言＝運用設定」に分離する - **決定**: 該当ルールの判定は `lib/judge/advice.ts`（テストで固定）、表示文言は運用設定から編集可能にする - **理由**: 文言は運用しながら磨いていくもので、変えるたびにテストが壊れるのは不合理。 一方で発火条件は仕様であり、勝手に変わってはいけない - **保存先**: `data/settings/advice.json`（DFA側の設定ファイル）。**メインDBには保存しない** - **編集可能**: title / text（推定原因）/ actions（推奨アクション） - **編集不可**: level / icon / condition（発火条件の説明） - **既定値**: `lib/config/advice-rules.ts`。未編集のルールは既定値がそのまま使われるため、 既定値を改善すると編集していないルールへ自動反映される ### D-037 `[確定]` アドバイスは該当ルールを全件返す（単数ではない） - **決定**: `GET /clean-logs/{id}/advice` は `advices` 配列を返す。行バッジの色は `max_level` - **背景**: `d-watch-api.yaml` は当初 `matched_rule`（単数）だったが、モックは複数を積み上げて表示していた - **理由**: 3日連続かつオフラインの行では「オンサイト訪問検討」と「ルーター再起動」の両方が必要。 1本に絞ると対応漏れが出る - **対応**: YAMLを配列形式に修正（API契約はYAMLが先。D-040） ### D-038 `[確定]` R1〜R4の発火条件はモックではなくCLAUDE.md 4.5に従う - **決定**: R3は「2日以上連続」、R4は「3日以上連続」で発火する - **背景**: モックの `getAdvice()` は当日の判定だけで R3/R4 を出していた（連続日数を見ていなかった）。 モックのダミーデータに連続日数がなかったための簡略実装 - **判断**: モックは「画面レイアウト・文言の正」、仕様は `CLAUDE.md` が正（CLAUDE.md 5.） - **帰結**: 文言はモックから移植し、発火条件は仕様に従う。3日連続時は R3 と R4 が両方出る（段階的対応を促すため意図的） - **あわせて**: R1は「未実施（完了率null）」でも発火する。モックは完了率0を条件にしていたが、 実データでは未出発なら完了率はnullになる ### D-039 `[確定]` Phase B相当の3ルール（B1〜B3）をP1に含める - **決定**: マップ更新の確認（B1）/ ハンドルアップ検知（B2）/ オフライン検知（B3）を実装する - **理由**: モックに既に存在し、実装コストがほぼゼロ。運用上も有用 - **注意**: `docs/spec.md` ではPhase B送りとしていた内容。エラーコード別ルールの本格展開は引き続きPhase B ★**2026-09-08 追記: この決定が正。実装も従っている。**★ - `lib/config/advice-rules.ts:16` の `AdviceRuleId` は **`"R1" | "R2" | "R3" | "R4" | "B1" | "B2" | "B3"`**。定義も7本すべて存在する - `lib/judge/advice.ts:75-85` が `B1` / `B2` / `B3` を実際に `matched` へ積んでいる - ★**要件定義書 P1 v2.2 の 5.1.6 は B1〜B3 を「Phase B（P1後半〜P2）」としているが、 本決定が意図的に上書きしている。`docs/decisions.md` が決定の正**★（`CLAUDE.md` §5） - ★**当方（Claude）が2026-09-08 に「B2/B3 は Phase B なので P1 スコープ外」と回答したのは誤り。**★ 要件定義書だけを見て本決定を見落とした。**他メンバーの指摘で判明。** ★**帰結: ハンドルアップ／オフラインが取れない問題は「Phase B の話」ではなく P1 の欠落である**★ `lib/judge/advice.ts:80-86` の発火条件は**日本語文字列の完全一致**: ```ts if (status1h === "ハンドルアップ" || status30m === "ハンドルアップ") matched.push("B2"); if (status1h === "オフライン" || status30m === "オフライン") matched.push("B3"); ``` - **fixtures にはこの文字列が入っているので、いまは B2/B3 が正しく発火する** - ★**実データに接続した時点で、`error_type`／`robots.status` からこの2つの文字列を 作れないと、B2/B3 は例外もテスト失敗も出さずに二度と発火しなくなる**★ - **これは「静かに壊れる」種類の欠落。`prismaSource` 実装時の必須確認項目とすること** ### D-030 `[確定]` トークン期限/残日数の機能は実装しない - **決定**: D-Secログ・D-Secアラートの両方から除外 - **背景**: 画面要件整理シートで不要と確定。モックとUI仕様書v6.0、運用ガイドには記述が残っているが**実装対象外** - **注意**: 古い資料に従って実装しないこと ### D-031 `[確定]` 点検記録をP1スコープに追加 - **決定**: モックに存在していたが要件定義書・画面要件整理シートに記載がなかった点検記録画面を、正式にP1スコープに含める - **前提**: メインDBとは別管理のため、TeamWorksへの確認・依頼は不要（D-004） ### D-032 `[確定]` システム管理はP1限定スコープ - 実装する: 表示設定、運用設定（閾値類） - 実装しない: 通知設定 / 顧客管理 / グループ管理（D-Security側画面を流用） - スコープ外: ユーザー管理 / 権限管理 / 監査ログ（ユーザー管理未実装のため。P2以降） ### D-033 `[確定]` 取り扱いメーカーは PUDU と Keenon のみ - **決定**: Whiz i は機能的に劣るため取り扱わない - **P1範囲**: PUDU Roboticsのみ（KeenonはP2以降） - **未反映**: 要件定義書・UI仕様書へのWhiz i除外の明記は未対応 ### D-034 `[確定]` エリア別完了率はPhase B送りの可能性あり - **状況**: Pudu Cloud APIがエリア（区画）別の完了率を返すかが未確認（確認事項#10）。走行距離は「おそらく含まれない」との回答 - **暫定**: `GET /clean-logs/{id}/areas` は 501 を返す仮実装で先行し、調査結果次第で本実装またはPhase B送り ### D-035 `[確定]` P1は「1清掃エリア = 1ロボット」前提 - テーブル構造は複数台対応可能だが、P1ではこの前提で判定ロジックを実装する --- ## 開発プロセス ### D-040 `[確定]` API契約はYAMLが先 - 実装中にAPIを変えたくなったら、先に `d-watch-api.yaml` を修正してからコードに反映する。YAMLと実装を乖離させない ### D-041 `[確定]` 判定ロジックは期待値表テストで固定 - ◎○△×・L1〜L3・KPI計算・丸めは、入力→出力の期待値表を先に作りテストで固定する - **バイブコーディングで唯一妥協してはいけない箇所。** 生成コードの目視確認だけで済ませない ### D-042 `[確定]` DB書き込みは4カラムのみ - `robot_error_reports` / `control_error_histories` の `status` / `comment` / `responded_at` / `resolved_at` のみ - DBアカウントもカラム単位GRANTで権限を絞る（アプリのバグでデータを破壊できない構造にする） ### D-044 `[確定]` DB接続前はサンプルデータ（fixtures）で開発する - **決定**: `lib/fixtures/` にサンプルデータを置き、環境変数 `USE_FIXTURES` で実DBと切り替える。ある程度画面ができてからDB接続する - **却下した案**: Prism（OpenAPIからのモックサーバ）を使う - PrismはYAMLのexample値をそのまま返すため、**全レコードが同じ値になる** - フィルタ（△×のみ/全件/×のみ）、判定バッジの色分け、L1〜L3の3段階表示、ページング、空データ表示が確認できない - **理由**: モック（`d-watch-mock.jsx`）に既に良質なダミーデータ（LOG/PRECHK/DSA/RANK/ROBOTS/SCHED/DSDEV/INSPECTIONS）があり、これを型付きで移植する方が早く確実。別プロセスを立てる必要もない - **設計上の注意**: **判定ロジック（`lib/judge/`）は切替の外側**に置く。fixture開発中も本番同等のロジックが走るようにする - **DB接続の進め方**: スキーマの答え合わせ（`prisma db pull` と定義書の突き合わせ）だけはM1で早めに行う。カラム名の食い違いが後から見つかると全画面に波及するため。画面開発はfixtureのまま継続する - 詳細は `docs/fixtures.md` ### D-045 `[確定]` fixtures はDB接続後も削除しない - テスト用・デモ用・障害切り分け用（「画面の問題かDBの問題か」を切り分けられる）に残す ### D-043 `[確定]` モックの実在住所・電話番号はダミー値に置換する - モック（`d-watch-mock.jsx`）には実在の店舗住所・電話番号が残っている。コンポーネント分割の際にダミー値へ置換する ### D-046 `[確定]` ビューアーは自アプリの API ルート経由で DB を読む - **決定**: 画面はブラウザから自アプリの `app/api/...` に HTTP リクエストを送り、Route Handler が Prisma で DB を読む。**この構成を維持する**（`docs/spec.md` の各画面の「API:」記述の通り） - **背景**: 「ビューアーは DB を SQL で直接読み、API は使わない」という認識との食い違いが確認されたため、 事実を確認した上で改めて確定した - **確認した事実**: - `app/api/...` は**本アプリと同一プロセス・同一リポジトリ**の中にある（D-001）。 TeamWorks が API サーバーを提供するわけではない - `docs/spec.md` §4「TeamWorks待ち項目の一覧」に **API は1件も無い**。 待っているのは DB アカウント・ステージングDB・カラム追加・サマリ集計バッチ等、すべてデータ側 - DB へは Prisma で**直接**アクセスしており、間に外部サービスは存在しない - Prisma はブラウザでは動かせない（DB 接続情報をブラウザに渡せない）。 したがってどの構成を選んでも、DB を読むのは必ずサーバー側になる - **却下した案**: Server Component から Prisma を直接呼び、ブラウザ↔自サーバーの HTTP 往復を省く方式 - 初期表示は速くなるが、`detail-log` のようにフィルタ・検索・ページングを持つ画面では 結局サーバーへの問い合わせ口が別途必要になる - 判定ロジックが Server Component 側と API 側の2箇所に散る恐れがある（D-002 の却下理由2 と同種） - `d-watch-api.yaml`（API契約の正）の `/dashboard` が未実装のまま残り、D-040 に反する - **用語の注意**: `CLAUDE.md` §2 の「APIサーバー」は**本アプリ内の API ルート**を指す。外部サービスではない ### D-047 `[確定]` 動作ログは pino で stdout に構造化出力する - **決定**: `pino` で1行1JSON を **stdout のみ**に出す。日時は ISO 8601 JST（`+09:00`、ミリ秒付き）で フィールド名は `timestamp`。レベルは `LOG_LEVEL` 環境変数（未設定時は `NODE_ENV` から判定） - **ファイル化とローテーションはアプリでやらない**。systemd の `StandardOutput=append:` と logrotate に委ねる。 全社ルール7 の「ログファイルとして残す」は満たしつつ、アプリ側の失敗モード（ディスク満杯・権限）を持たない - **却下した案**: 自作の薄いロガー（`JSON.stringify(error)` が `message` / `stack` を落とす罠がある）/ winston（強みのローテーションがOS委譲では活きない）/ アプリからのファイル直書き / PM2 でのログ管理 - **相関ID**: `x-request-id` を `AsyncLocalStorage` に載せ、pino の `mixin()` で全ログへ自動付与する。 `proxy.ts` が未着手のため、現在はヘッダが無ければルート側で生成する（`proxy.ts` 投入後もそのまま動く） - **マスキング**: 個人情報・自由記述と認証情報を**キー名で**弾く3段構え（allowlist 型 + 実行時チェック + テスト）。 施設は `facility_id` で参照し名前を書かない。非本番は例外、本番はキーを除去して継続する （ログ呼び出しは catch 節の中から行われるため、ここで例外を投げるとリクエストを 500 にしてしまう） - **判定ロジックは変更しない**（`CLAUDE.md` §9.4 の純粋関数を維持）。記録は呼び出し側で行い、 入力の生値・その時点のしきい値スナップショット・結果の3点セットを残す（F-10 でしきい値が可変になるため） - 詳細は `docs/logging-design.md` ### D-048 `[確定]` failure_breakdown は M2 のレスポンスから省略する - **決定**: ダッシュボードの「失敗の内訳」（ロボット異常 / 未実施 / セキュリティ有効 / 制御盤異常）は M2 では返さない。M3 送りとする - **★空配列ではなく、プロパティごと省略する**: 空配列は「当日の失敗が0件」を意味するため、 未実装をそれで表すと UI が「失敗なし」として正常表示してしまう。プロパティが無ければ UI 側で undefined（未実装）と `[]`（0件）を区別できる - **理由**: 4分類の分類元（`robot_error_reports` / `control_error_histories` / D-Security アラート）は、 型定義・DataSource のメソッド・fixtures のいずれもコード上に存在しない - **展開**: F-03（アラート画面、M3）でも同じデータが必要になるため、そこでまとめて用意する - **却下した案**: 既存の `status_1h` / `status_30m` から分類する - 理由は事前チェックの仕様にある。本来の清掃開始時刻が23:00の場合、22:00と22:30に 短時間動作させて迷子などの異常が出ていないかを確認する運用になっており、各回で結果が変わりうる - 例: 22:00に迷子 → 店舗に連絡して解決 → 22:30は正常 → 23:00の清掃は成功。 この行は**成功**だが `status_1h` には異常が残るため、これを失敗として分類すると誤りになる ### D-049 `[確定]` schedule_progress の planned / completed / rate の定義 - **決定**: - `planned` = 当日のスケジュールマスタの該当件数（`active` が true のもののみ、曜日で絞る） - `completed` = 出発した件数（`departed === true`） - `rate` = `planned` が 0 のとき `null`（0除算を避ける。画面は「予定なし」と表示する） - **★`planned` は清掃ログの行数ではない**: 行数を使うと、収集処理が止まって当日の行が0件のときに 「本当に定休日」と「収集処理の障害」が区別できなくなる - **`completed` は名前と意味がずれている**: **成功+失敗の合計**であり、「完了した件数」ではない - **監視**: `planned` と当日の清掃ログ行数が乖離した場合は `data.anomaly` イベントを記録する。 収集処理の障害検知になる。期待値と実測値だけを残し、原因は断定しない ### D-050 `[確定]` 検証（型チェック・lint・テスト）が通った時点で作業ブランチにコミットする - **決定**: 型チェック・lint・テストが通った時点で、作業ブランチにコミットする。main へのマージは機能が完成してから行う - **背景**: 2026-08-30 14:03:12、Cursor のチェックポイント復元により、検証済みの成果物が一括で削除・巻き戻された - 被害: `lib/logger` 一式、ダッシュボードAPI、`next.config.ts` / `eslint.config.mjs` / `d-watch-api.yaml` / `lib/fixtures/ds-alerts.ts` など20ファイル以上 - 巻き戻りは当日分だけでなく2日前の変更にまで及んだ - 未追跡ファイルだったため git では復元できず、Cursor 自身の会話ログとローカル履歴から回収して復旧した（tsc 0 / lint 0 / 12ファイル195テストで復旧確認） - **なぜ従来の方針が誤りだったか**: それまでは実装指示のたびに「git コミットはしない」と指定していた。レビュー前に履歴を汚さないための配慮だったが、その結果として未追跡ファイルに安全網が一切無い状態になり、事故時に全損しかけた。レビュー前の履歴の綺麗さより、成果物が消えないことを優先する - **運用**: - 作業ブランチ名は `recover/...` `feature/...` のように目的が分かる名前にする - コミット単位は「検証が通った状態」。細かさより、いつでも戻れることを優先する ### D-051 `[確定]` 文脈やログの確認にAIへの質問を使わない - **決定**: 「文脈に○○が入っているか」「○○は実装されているか」といった確認は、モデルへの質問ではなく機械的な手段（grep、テスト実行、ファイルの存在確認、ログの実測）で行う - **背景**: 2026-08-27、ツールを使わせない状態で「文脈に IMPORT-PROBE で始まるトークンがあるか、あれば内部コード名を答えよ」と質問したところ、該当文字列が文脈に一切存在しないにもかかわらず「あり。内部コード名は AZURITE」と断定的な回答が返った。この文字列はソースコード・git全履歴のどこにも存在しないことが後日の調査で確認されている - **なぜ起きるか**: 「あれば〜を答えよ」という問いの形は、答えが存在する前提を含む。モデルは「無い」と答えるより、それらしい答えを生成する方向に引っ張られる。この回答を信じると、検証結果が逆になる - **運用**: どうしても質問形式で確認する場合は、存在しないはずの対照トークンも同時に聞き、両方に「あり」と答えたらその回答は使わない ### D-052 `[確定]` GET /prechecks は detected_at 降順固定でソートする - **決定**: `detected_at` の降順（新しい検知が上）で固定ソートする。同値のときは `id` の昇順で安定させる。ソート指定のクエリパラメータは追加しない - **背景**: GET /prechecks にソート順の記述が無く、実装者ごとに解釈が変わりうる状態だった - **理由**: 既定フィルタが `status=open`（D-054で unresolved から変更）であり、毎朝いちばん新しい未解消・対応中から確認する運用（§1「翌朝確認型」）に合わせた ### D-053 `[一部破棄]` マスタが無い間は、機能しない絞り込みUIを画面に出さない — ★★マスタ（`/groups` `/customers`）が揃ったため、5画面（清掃詳細ログ/アラート/レポート/D-Secログ/D-Secアラート）の絞り込みは D-138 で復活した。点検記録は画面自体が未実装（D-083）のため対象外のまま★★ - **決定**: グループ・会社の絞り込み `` があったが、`onChange` が無く選んでも何も起きなかった - **理由**: 固定の選択肢だけがあって何も起きないUIは、不具合と区別できないため - **運用**: マスタが揃った時点で、グループ・会社の絞り込みは全画面まとめて実装する ### D-054 `[確定]` prechecks の status に open を追加し既定にする。summary.unresolved は解消していない件数とする - **決定**: - GET /prechecks の `status` enum に `open` を追加する: `[open, unresolved, in_progress, resolved, all]`。既定値を `unresolved` から `open` に変更する。`open` = 未解消+対応中（`resolution_status !== "resolved"`） - `summary.unresolved` は「解消していない件数（未解消+対応中）」とする。`resolved` との合計が `total` になる。★フィールド名は変えない★（名前を変えると型と実装の両方に波及するため） - **背景**: `summary` は `{unresolved, resolved, total}` の3値だが、対応状況（`resolution_status`）は未解消/対応中/解消の3状態ある。fixturesの8件は未解消3+対応中2+解消3であり、`unresolved`(3)+`resolved`(3)=6 が `total`(8) と合わない状態だった - **理由**: - spec.md のサマリ3カード（未解消/解消/合計）が合計と整合する解釈が、`unresolved` を「未解消+対応中」とする以外にないこと - `ds-alerts` の `status=open`（未対応+対応中）と同じ意味にして、2つのAPIで解釈を揃えること - **追記**: summary は status フィルタの前に計算する。状況で変わると既定表示で解消済みが常に0になり、サマリーの意味がなくなる ### D-055 `[確定]` ds-devices と ds-alerts のソート順を固定する - **決定**: - `ds-devices`: 異常→通信断→正常の順（既存の3箇所で確定済み）に加え、同一状態内は `serial_number` の昇順で安定させる。★これは安定化のためだけの規則で、運用上の優先度を表すものではない★（長く通信が切れている順などの意味づけは決まっていない） - `ds-alerts`: `detected_at` の降順（D-052と同じ規則）。同値のときは `id` の昇順で安定させる - ソート指定のクエリパラメータは追加しない（固定ソート） - **背景**: GET /ds-devices と GET /ds-alerts のどちらも、同一状態内・同値時の並びが未定義だった ### D-056 `[確定]` schema.prisma は db pull 実施前まではテーブル定義書を正として手書きする - **決定**: - db pull を実施する前は、TeamWorks提供のテーブル定義書を正として `prisma/schema.prisma` を手書きする - db pull を実施した後は、生成物を正とし、以後は手で書き換えない - **背景**: `CLAUDE.md` と `docs/architecture.md` は「`prisma/schema.prisma` は `db pull` で生成。手で書き換えない」と定めていたが、 `docs/spec.md` はM1の手順として「Prismaスキーマを定義書ベースで手書きし、`db pull` で答え合わせ」を指示しており、 db pull 実施前の期間について2つの文書が矛盾したままになっていた - **理由**: spec.md が指示する手書き＋答え合わせの手順を実行するには、手書き版が一時的に存在する期間が必要になる。 手書き版と db pull 版を突き合わせることが、カラム名・型の食い違いを早期に見つける唯一の手段になる - **運用**: 手書き期間中であることを `prisma/schema.prisma` の冒頭コメントに明記する ### D-057 `[確定]` TeamWorks 回答によりテーブル定義の確認事項が確定した - **決定**: TeamWorksからの回答を受け、`prisma/schema.prisma` の確認中コメント（A-1, A-2, B-1〜B-6）を確定内容に更新した - **A-1**: makers テーブルは提供されない。メーカー情報は設定ファイルで代替する。`Maker` モデルは削除し、`devices.maker_id` に外部キーは張らない（0〜255の範囲で運用） - **A-2**: clean_status は符号あり tinyint（-1: 清掃完了(セキュリティ無効) というコード値があるため）。`clean_status_trans` / `clean_error` は対象外（負値の定義が無い） - **B-2**: controls.facility_id は外部キーとして定義する（開発環境は定義済み） - **B-4**: link_schedules は controls とのリレーションを張らない。外部キーは section_id のみ（定義書の fk_link_schedules_control_id は誤り） - **B-6**: customer_contacts.contact_type / facility_contacts.contact_type は unsigned tinyint に統一。customer_contacts.email / facility_contacts.email は varchar(100) に統一（定義書の記載違いは typo） - **B-3**: clean_ratio（clean_statuses / clean_status_histories / clean_task_reports）は取得元で 100 に丸められる。上限は 100 で、画面側での頭打ち処理は不要 - **B-5**: clean_schedules.end_time は時が 24〜29 を取りうる（HHMM形式、日跨ぎで翌6:00まで設定可能にするための表現）。start_time は 0000〜2359 - **B-1**: precheck は 0: 本清掃 / 1: 1回目 / 2: 2回目（clean_timetables の定義が正。clean_timetable_histories 側の定義書の記述「9: 本清掃」は誤り）。clean_timetables.precheck の @default(9) は定義書のまま維持し、既定値の意図は未確認のままとした - **C-1（未確定・継続）**: robot_error_reports.responsed_at / control_error_histories.responsed_at のカラム名はそのまま。実DDLでの正式名は未確認で、定義書の他のtypoや廃止済みテーブル・カラムの指摘と合わせて、実際のスキーマ文（DDL）を入手するまでは定義書表記のまま実装を進める - **付随情報（回答に含まれていた実装上の知識）**: - サマリの各比率は `clean_status_histories` から算出・生成される。★当期分は同じ元データからこちらでも算出できる★ - `error_type` は PUDU Cloud 由来で列挙が未定義。★プログラム側で分類する必要がある★（画面の7分類はこちら側の分類であり、未知の値は「その他」に寄せる設計が必要） - **★今後の方針★**: 今後は定義書ではなく、実際のスキーマ文（DDL）を正とする。定義書には既に廃止されたテーブル・カラムが含まれていることが確認されているため - **背景**: `prisma/schema.prisma` には D-056 の運用に従い「TeamWorksへ確認中」のコメントが10箇所あった。今回の回答で A-1, A-2, B-1〜B-6 は確定し、C-1（responsed_at のカラム名）のみ確認中として残っている - **★その後（2026-09-03 追記）★**: **C-1 は D-059 の実DDL照合で解消した**（正式名は `responded_at`。定義書の `responsed_at` が誤記）。一方で **B-6 は実DDLに反映されていない**（下記）。この節の記述は D-057 を確定した時点のものである - **★B-6 は実DDLに未反映（2026-09-03 追記）★**: 上の B-6 は「`contact_type` を unsigned tinyint に、`email` を varchar(100) に統一する」という回答だったが、**受領した実DDL（`clean_watch_20260902.sql`）には適用されていない。** 実測値は `customer_contacts.contact_type` = `bigint unsigned` / `facility_contacts.contact_type` = `tinyint unsigned`、`customer_contacts.email` = `varchar(100)` / `facility_contacts.email` = `varchar(255)` で**食い違ったまま**。 D-059 により実DDLが正となるため、`prisma/schema.prisma` は**現行DDLどおり（食い違ったまま）**にしてある。 **★`schema.prisma` を手で B-6 の内容に寄せてはいけない。★** 直すのは TeamWorks 側のDDLで、こちらは修正後のDDLを `db pull` で取り込む（D-061 で TeamWorks が再度「両テーブルとも tinyint / varchar(100)」と回答済み） ### D-058 `[確定]` clean_link_schedules は参照しない。link_schedules を使う - **決定**: `clean_link_schedules` テーブルは参照しない。API・クエリ実装は `link_schedules` を使う - **背景**: 実DDL（`clean_watch_20260902.sql`）を db pull で取り込んだところ、`link_schedules` と完全に同一構造（カラム名・型・既定値・NULL許容・FK先すべて一致）の `clean_link_schedules` が存在することが判明した。table_options に `AUTO_INCREMENT=` の記載が無く、一度も行が挿入されていないことも確認済み - **理由**: TeamWorks より不要テーブルと確認済み。データも0件のため、現時点で実装に使う理由がない - **運用**: `prisma/schema.prisma` には db pull の結果どおりモデルとして残す（削除すると db pull のたびに再追加され差分ノイズになるため）。モデルの直上にコメントで不使用の旨を明記する ### D-059 `[確定]` 以後 schema.prisma は実DDLを正とし、db pull の生成結果を採用する - **決定**: 定義書ではなく、TeamWorksから提供された実DDL（ダンプファイル）を正として `prisma/schema.prisma` を維持する。DDLを受領したら `prisma db pull` で答え合わせし、生成結果をそのまま採用する（1件ずつの手当てはしない） - **背景**: 実DDL（`clean_watch_20260902.sql` / 受領日2026-09-02）を用いて既存の手書き版（28モデル）を db pull で答え合わせしたところ、49件の差分が見つかった。うち3件は定義書の誤記（`responsed_at`→`responded_at`、`sireal_number`→`serial_number`）、8件は定義書にあるが実DDLには存在しない廃止済みカラムだった - **理由**: 定義書には誤記や廃止済み項目が含まれることが実証されており、手書きでの追随はスキーマのズレ＝バグに直結する（CLAUDE.md §0）。db pull による機械的な突き合わせが最も確実 - **運用**: db pull は既存の `prisma/schema.prisma` に対して実行する（新規ファイルへの `--print` ではない）。既存モデルの PascalCase 命名 + `@@map` は db pull の enrich 挙動（`--force` を付けない）により維持される。Prisma 固有の `@updatedAt` は db pull が出力しないため、DDL の `ON UPDATE CURRENT_TIMESTAMP` の有無を個別に確認して手で付け外しする - **この決定により新たに発生した確認事項**: 実DDLを正とした結果、次の3件が TeamWorks への確認待ちになった（`docs/handoff.md` の A-1 / A-2 / A-3）。 **回答が来るまでスキーマを動かさないこと** - `robot_error_reports` に主キーが無い（UNIQUE は `error_id` のみ） - `clean_status_histories` / `clean_timetable_histories` の `id` が AUTO_INCREMENT でない - D-057 B-6（`contact` 系の型統一）が実DDLに未反映（詳細は D-057 の追記を参照） ### D-060 `[確定]` Schedule.end_time は「翌04:30」の整形済み文字列で返す - **決定**: `clean_schedules.end_time` は HHMM 文字列で**時が 24〜29 を取る**（D-057 B-5。`2830` は翌日4:30）。 API の `Schedule.end_time` は、24時以降を**翌日表記に正規化した整形済み文字列**で返す。 - `0300` → `"03:00"`（24時未満はそのまま `HH:MM`） - `2830` → `"翌04:30"` - `start_time` は 0000〜2359 のみなので常に `HH:MM` - **理由**: スケジュール画面は「開始 - 終了」を並べて表示するだけの用途で、運用担当が `28:30` を「翌4:30」と読み替える負担を画面側に持ち込まないため - **却下した案**: - `"28:30"` をそのまま返す → 文字列比較でソートでき API が表示ロジックを持たずに済むが、 運用担当が読み替える必要がある - `"04:30"` + `end_next_day: boolean` を追加 → API契約に1フィールド増え、時刻ソートの比較関数が2段になる - **★この決定に伴う制約（実装時に必ず対応すること）★**: 1. **`d-watch-api.yaml` の `Schedule.end_time` を先に直す**（`example: "03:00"` のみで形式の規定が無い）。 CLAUDE.md 作業ルール1「API契約を変えたくなったら先にYAMLを直す」 2. **EN 表示で「翌」が日本語のまま残る。** モックには JP/EN 切替があるため、 EN 側の文言（`"+1d 04:30"` 等）をどうするかを実装時に決めること。 決めるまでは**この決定を「JP のみ確定」として扱う** 3. **終了時刻でのソートができなくなる**（`"翌04:30"` < `"03:00"` になる）。 ソートが必要になったら、整形前の HHMM を別フィールドで持つか、比較用のキーを別に作ること 4. 変換は純粋関数として `lib/format/` に置き、**テストを先に書く**（CLAUDE.md §9.4）。 境界値: `0000` / `2359` / `2400` / `2830` / `2959` / 桁数不正 / 数字以外 ### D-061 `[確定]` TeamWorks 第1回回答（実DDL照合）を反映する - **経緯**: 共有文書「実DDL照合結果と確認事項」（第1回）を TeamWorks へ送付し、**A-1〜A-3 / B-1〜B-3 の回答を受領した**（2026-09-03）。 ★引き継ぎ文書は第1回PDFを「送付待ち」としていたが、実際には**送付済み・回答済み**だった。記録が漏れていた★ - **★番号の衝突に注意★**: D-057 の A-1/A-2/B-1〜B-6 は**定義書レビュー回**の採番で、本項の A-1/A-2/A-3/B-1〜B-3 は**実DDL照合回（第1回）**の採番。**同じ記号で別の質問を指す。** 混同しないこと | # | 質問 | 回答 | こちらの対応 | |---|---|---|---| | A-1 | `robot_error_reports` の主キーと `id` の意味 | **`error_id` を主キーと位置付けて対応する予定**（運用を以て最終回答とする暫定）。**`id` も `error_id` も英字を含むため数値型にできない** | **`PrecheckItem.id` を `number` → `string` に変更し、値は `error_id` にする**（下記） | | A-2 | 履歴テーブルの `id` は誰が採番するか | **データベースが `auto_increment` で採番する。** 元テーブルと履歴テーブルは**1対1** | ビューアーはこの2テーブルを参照しないため実装に影響なし。現行DDLに AUTO_INCREMENT が無い点は修正版DDL待ち | | A-3 | D-057 B-6（contact 系の型）はいつ反映されるか | **`contact_type` は両テーブルとも tinyint、`email` は両テーブルとも varchar(100)** | DDL側の修正を待ち、`db pull` で取り込む。**`schema.prisma` を手で直さない**（D-059） | | B-1 | 外部キーが3本欠けている | **制約は後から追加する** | **孤児行を想定した実装はやめる。** 追加後のDDLに合わせる | | B-2 | インデックスが1本欠けている | **後から追加する。現状は20施設弱** | 当面の性能懸念は小さいと判断。追加後のDDLに合わせる | | B-3 | `timestamp NOT NULL` に DEFAULT 句が無い | **指摘どおり追加する**（`created_at`: 新規作成時 / `updated_at`: 新規作成時・更新時） | 追加後のDDLに合わせる | - **★`PrecheckItem.id` を `number` → `string` に変更する（A-1 の帰結）★** - `lib/types/index.ts` の `PrecheckItem.id` と `d-watch-api.yaml`（`type: integer` → `type: string`）を変更する。 **CLAUDE.md 作業ルール1に従い、YAML を先に直すこと** - `lib/prechecks/query.ts` の `sortPrechecks()` が `a.id - b.id` と**数値減算に依存している**。文字列比較へ変更が必要 - `lib/fixtures/prechecks.ts` の `id` も文字列にする - **指示書D の 4-1 が同じ `lib/prechecks/query.ts` を触る。指示書D を先に実行し、その後にこの変更を入れること**（衝突回避） - `PATCH /prechecks/{id}/status` の設計が可能になった（`error_id` をキーにする）。ただし**DB更新用アカウントの発行待ち** - **★次にDDLを受領したら指示書E をやり直す★**: A-3 / B-1 / B-2 / B-3（および A-2 の auto_increment）で**DDLが更新される見込み**。 受領したら `docs/handoff/指示書E_スキーマを実DDLに一致.md` の手順で `db pull` をやり直す（D-059） - **未回答**: DB更新用アカウントの発行のみ。第1回 C-1（アドバイス規則 R3）は TeamWorks 案件ではなく**DFA 内部で決めるもの** ### D-062 `[一部破棄]` 判定基準の範囲表記を「10%以上70%以下」に統一する — ★★範囲そのものが D-139 で「10%以上70%**未満**」に変わった。★「境界の含む/含まないが読み取れる表記を使う」という決定の趣旨は有効★で、書く形だけが変わる★★ - **決定**: △判定の範囲を表す「10〜69%」という表記を、すべて「10%以上70%以下」の形（境界の含む/含まないが読み取れる表記）に統一する - **背景**: 実装は `rate > 70` で○、`rate < 10` で×、それ以外が△（`lib/judge/grade.ts`）。「10〜69%」だと69.0超〜70.0の範囲が表記上どちらにも該当しない（例: 69.5%は実装では△だが「10〜69%」からは読み取れない）。`docs/handoff/指示書D_実装解析の不整合.md` 赤3の指摘 - **理由**: 曖昧な範囲表記は「信じると実装を誤った方向に直してしまう」危険がある（境界値のズレは実装のバグに直結する。CLAUDE.md §0） - **対応した6箇所**: `CLAUDE.md:102`（§4.1判定基準表）／`lib/config/advice-rules.ts:101`（B1の`condition`。**ユーザー向け文言の変更を含む**。`GET /api/settings/advice`のレスポンスに載る）／`lib/judge/grade.ts:15`（JSDoc）／`lib/judge/advice.ts:19,72`（JSDoc・実装コメント）／`d-watch-api.yaml:274`（OpenAPIのdescription） - **運用**: 「10〜70%」のような別の曖昧表記への置き換えは不可。今後この判定基準に触れる文書・コメントを書く／直すときは「10%以上70%以下」の形を使うこと - → ★【D-139 で変更済み】★ ★2026-09-16 以降は「10%以上70%**未満**」の形を使うこと★ — 境界が上のランクに入る規則になり、70.0 は ○ になったため「70%以下」は**誤り**になりました （上の1行は当時の記録として残してあります。★そのまま真似しないこと★）。 ★「境界の含む/含まないが読み取れる表記を使う」という本決定の趣旨は有効★で、書く形だけが変わります。 - **注記**: `lib/judge/grade.ts` の判定ロジック本体（`judgeGrade()`、22-28行目）は変更していない。テスト3本（`grade.test.ts`の境界値テスト・`advice.test.ts:66`）とD-020bの確定合意（10.0%は△）を維持したまま、コメント・文言のみを実装に合わせて修正した。あわせて `lib/judge/__tests__/advice.test.ts` に境界値`completionRate: 70.0`でB1が出ることを固定するテストを1件追加した（従来はしきい値比較を`>=`に書き換えてもテストが通ってしまう抜けがあった） ### D-063 `[確定]` docs/logging-design.md §5「記録条件」を実装（advice ルートは無条件記録）に合わせる - **決定**: `docs/logging-design.md` §5「記録条件」の記述を、`app/api/clean-logs/[id]/advice/route.ts` の実装（判定根拠の記録に条件を設けず無条件に出す）に合わせて書き換える。記録条件は「1回の呼び出しで何件を判定するか」で経路を分ける形に整理し、advice ルート（1件/呼び出し）は無条件記録、一覧変換側（`lib/db/` の`judge.grade`、約360行/日）は条件1〜4のいずれかに該当する行のみ記録する設計を明記する - **背景**: 旧§5は`JUDGE_LOG_BOUNDARY_MARGIN`/`LOG_JUDGE_VERBOSE`という未実装の環境変数を前提に書かれていたが、advice ルートの実装は明示的に「記録条件は設けず無条件に出す」とコメントで宣言しており、文書と実装が逆方向に食い違っていた（`docs/handoff/指示書D_実装解析の不整合.md` 3-6の指摘） - **理由**: CLAUDE.md 作業ルールの原則どおり、未実装の設計文書ではなく実装済みの挙動を正として文書を合わせる（逆に文書に合わせて実装を書き換えると、動いているadviceルートの挙動を壊す） - **一覧変換側（`judge.grade`）の条件1〜4・verboseモードは引き続き未実装。** Prisma実装（一覧のDB接続）と同時に実装する。条件4（生値がしきい値の近傍±0.5にある行を記録）は、CLAUDE.md §4.3が指摘する「表示用に丸めた値で判定すると事故る」境界（例: 89.5%は表示90%だが判定は○）を捕捉するために必須とする - **連動修正**: §8 ステップ11・§10 フェーズ表フェーズ3の記述も、新§5と矛盾しないよう「advice ルートは無条件記録、一覧変換側の条件4を含む記録条件はPrisma実装と同時」の趣旨に修正した ### D-064 `[確定]` クエリバリデーションの422レスポンスは details に失敗項目名を返す（prechecks / ds-alerts / ds-devices を clean-logs に揃える） - **決定**: `/prechecks`・`/ds-alerts`・`/ds-devices` のクエリパラメータバリデーションを、既に union 型 + `details` を実装済みの `/clean-logs`（`lib/clean-logs/query.ts`）と同じ形に揃える。共通の型 `QueryParseResult` / `QueryParseFailure` と失敗生成ヘルパー `fail()` を新設の `lib/api/query-result.ts` に置く - **背景**: 3ルートとも、クエリパース失敗時に `details: null` を返し、どのパラメータが不正か呼び出し側に分からなかった（`docs/handoff/指示書D_実装解析の不整合.md` 4-1の指摘）。3本ともパーサが失敗した項目名を既に保持しており「情報が無いから返せない」ケースではなく、3ルートとも同一シグネチャの `errorResponse` ヘルパーが重複定義されていたため、1本だけ直すと不整合の種類が増えると判断し3本同時に対応した - **共通型の置き場**: `lib/api/query-result.ts` に新設（`lib/clean-logs/query.ts` 内に置いたままexportすると、prechecks/ds-alerts/ds-devicesが「清掃ログ」という無関係なドメインに依存することになるため）。エラー形式 `{ error: { code, message, details? } }` はCLAUDE.md §9.3が全API共通と定めており、共通の形は`lib/api/`という共通の場所に置く（`lib/api/client.ts`と同じ考え方）。`lib/clean-logs/query.ts` のローカル定義は今回変更していない（将来importへ寄せる余地を残す） - **あわせて対応（4-2）**: `app/api/prechecks/route.ts` / `app/api/ds-alerts/route.ts` / `app/api/ds-devices/route.ts` / `app/api/clean-logs/route.ts` の500エラー経路で、既に定義済みの `errorResponse(error, status)` ヘルパーを使わず `NextResponse.json` を直呼びしていた箇所を `errorResponse(body, 500)` に統一した（完全に等価な置換）。**`app/api/clean-logs/[id]/advice/route.ts`・`[id]/areas/route.ts`・`app/api/settings/advice/route.ts`（body先組み立てが必要な別シグネチャの「形B」）は対象外**（`logApiError`の設計意図を壊すため） - **範囲外（意図的に触っていない）**: `errorResponse`ヘルパー自体の共通モジュール化（7ルートに重複定義があるが統合は別件）。`PrecheckItem.id`の`number`→`string`化（D-061のA-1帰結。`lib/prechecks/query.ts`の`sortPrechecks()`は本決定でも数値減算のまま変更していない。D-061の記載どおり、この変更は本決定の後に別途実施すること） - **テスト**: 既存テストの `.toBeNull()` / オプショナルチェーン前提のアサーションをunion型前提に書き換え、`details`の中身を`toEqual`で検証するテストを6件追加（prechecks +3, ds-alerts +2, ds-devices +1）。テスト総数 260 → 267 ### D-065 `[確定]` TeamWorks 第2回回答（D-Sec / 事前チェック / 曜日順）を反映する - **経緯**: 共有文書「確認事項（第2回）」への回答を受領（2026-09-03）。 **★B-α（D-Sec のデータ取得元）と B-β（事前チェック時点の状態）が両方とも解決した★** #### Q1 D-Security | # | 回答 | |---|---| | Q1-1 備考 | **DB側に対応するカラムは無い**（先方から逆質問）。モックの「セキュリティ復帰失敗」「6時間以上通信なし」は**検知側が出す情報ではなく、運用担当が書き留めるメモ**。→ ★**列は落とさず、ビューアー側の入力欄として実装する**★（下記） | | Q1-2 `controls.status` | **0: 正常 / 1: 異常**。異常判定は `control_reports.reported_at` からの経過時間。**時間帯ごとのしきい値は `link_schedules.intervals`（単位: 秒）** | | Q1-3 `control_error_histories.status` | **0: 未対応 / 1: 対応中 / 2: 対応済** | | Q1-3 アラート種別 | ★**D-S制御盤で発生するアラートは「生死報告がない」の1種類だけ**★。API認証失敗のようなものは存在しない | | Q1-3 アラート詳細文 | ★**存在しない**★（種別が1つしかないため） | | Q1-4 `security_statuses.status` | **0: セキュリティ無効 / 1: セキュリティ有効**。現在の状態を表す。`security_status_histories` はその変更履歴 | - **★F-06 D-Secログの「通信状態」は3状態ではなく2状態にする★** モックは「正常 / 通信断 / 異常」の3状態だが、`controls.status` は 0/1 の2値で、 かつ「異常＝生死報告が来ていない」なので**通信断と異常は同じもの**。 → **「正常 / 異常」の2状態**に変更する。`DsConnectionStatus` の型も変更が必要 - **★`DsAlertType` の `security_off` は制御盤アラートではない★** 制御盤のアラートは `disconnected`（生死報告なし）のみ。 「セキュリティが解除されたまま戻っていない」は `security_statuses.status = 0` が続いている状態から **DFA 側で導出する**もので、`control_error_histories` には入らない。 → 導出してよいかを第3回で確認する（下記） - **通信断の判定に `link_schedules.intervals` を使う。** D-058 のとおり `clean_link_schedules` ではなく `link_schedules` が正。ただし `VarChar(120)` で**書式が不明**なため第3回で確認する - **★D-Secログの「備考」はビューアー側の機能として実装する★** DB に対応カラムは無いが、**列を落とすのではなく運用担当が入力・編集できる欄にする**。 保存先は **DFA の独自ストア**（メインDBには書き込まない。D-042 の更新可4カラムの対象外であり、 そもそもデバイス単位のメモはメインDBの責務ではない）。 前例: 点検記録は SQLite + オブジェクトストレージ（D-004）、運用設定は `data/settings/advice.json`（D-036） - ~~**保存先の具体（SQLite か JSON か）は未決。**~~ ★**解消（D-072 #8 / D-075）。JSON で確定**★ （`data/settings/ds-device-notes.json`）。1デバイスにつき短いテキスト1本なので `data/settings/` 方式で足りると判断した。読み書きは `lib/settings/json-store.ts` （D-075 で実装）を薄く包んで使う - ★**これは F-06（実装済み）への機能追加です。** 独自ストア・保存API・YAML の変更・入力UI が要るため、 **既存画面の小修正ではなく独立した作業として扱うこと**★ #### Q2 事前チェック（60分前 / 30分前）時点のロボット状態 - **`clean_timetables` と `clean_statuses` の2テーブルから判定できる。** `clean_timetables.precheck`（0: 本清掃 / 1: 1回目 / 2: 2回目）の行に対して、 `clean_statuses.clean_timetable_id` で紐づく行を見る - **エラーが発生していれば `robot_error_reports` に記録される。エラーが無ければ standby（待機）** - **`robots.status`（smallint）のコード表を受領**（47値）。要点: - 負値: `-300` Notice / `-200` Lost Location / `-100` Error - `0` Standby - `100`番台 Goto Pile（充電ステーションへの移動） - `200`番台 Charging（`201` Charging Line / `202` Charging Pile / `203` Workspace Water Supply / `204` Pile OTA） - `300`番台 Vacuum（清掃中） - `400`番台 Return / `500`番台 Dock Pile / `600`番台・`999` Unknown - **全文は `docs/handoff/TeamWorks回答_第2回_20260903.md` に転記した** - **`section_robot_statuses.robot_status` は、同一 `section_id` のロボットの status の最頻値** （一番多い値）が入る。P1 は「1清掃エリア = 1ロボット」（D-035）なので実質そのまま - **残る課題**: 画面に出す6状態（待機中 / 充電中 / ハンドルアップ / 緊急停止 / オフライン / セキュリティ有効）のうち、 **ハンドルアップ・緊急停止・オフラインは `robots.status` のコード表に無い**。 `robot_error_reports.error_type` から判定することになるが、**その値の一覧が未入手**（D-057 で 「列挙が未定義。プログラム側で分類する必要がある」とされている）。第3回で確認する #### Q3 `clean_schedules.weeks` の曜日順 - ★**左から順に「日・月・火・水・木・金・土」。`1` が実施、`0` が未実施**★ - `lib/dashboard/aggregate.ts` の `weekdayIndex()`（`getUTCDay()` は日曜=0）と**一致している**。 既存実装の変更は不要 #### Q4 ステータス系のコード値 - `robot_error_reports.status`: **0: 未対応 / 1: 対応中 / 2: 対応済**（`control_error_histories.status` と同じ体系） - 他は Q1 / Q2 で回答済み #### C 第1回回答を受けた追加確認 - **C-1 / C-2（contact 系の型・FK・インデックス・DEFAULT の修正）**: 「**本日中に反映し提示する**」 → ★**修正版DDLを受領したら `docs/handoff/指示書E_スキーマを実DDLに一致.md` の手順で `db pull` をやり直すこと**★（D-059） - **C-3-1**: `PrecheckItem.id` を `string` にして `error_id` を入れる方針で**問題なし** - **C-3-2**: 「**切り替える可能性はあるので、切り替えられる形で実装してください**」 → **ID の決定を1つの射影関数に閉じ込め、他のコードは ID の中身を知らない形にする**。 分岐が散らばると切替が現実的に不可能になる。テストはその関数に対して2パターン書く #### この回答で解消したもの - **B-α**（D-Sec のテーブル不明）→ `controls` / `control_reports` / `control_error_histories` / `security_statuses` の対応が確定。**F-06 / F-07 / ダッシュボードの `security_banner` の設計が可能に** - **B-β**（事前チェック時点の状態）→ `clean_timetables` + `clean_statuses` + `robot_error_reports` で判定可能と判明。**`cleanLogs()` の設計が可能に** - **Q3 曜日順** → 既存実装と一致を確認 #### この回答で新たに発生した確認事項（第3回へ） | # | 内容 | |---|---| | **D-1** | `link_schedules.intervals`（`VarChar(120)`）の**書式**。時間帯ごとの秒数をどう表現しているか | | **D-2** | `robot_error_reports.error_type` の**実際に入る値の一覧**（ハンドルアップ / 緊急停止 / オフラインの判定に必要） | | **D-3** | 「セキュリティ解除されたまま」を `security_statuses.status = 0` の継続から**DFA 側で導出**してよいか | | **D-4** | `PrecheckItem.id` の切替は「`id` と `error_id` のどちらを使うか」だけで、**型は varchar のまま**という理解でよいか（数値型に変わると API の破壊的変更になる） | ### D-066 `[確定]` 修正版DDL（clean_watch_20260907.sql）の照合結果 — 7件中2件のみ反映 - **受領**: 2026-09-07 10:54（`Downloads/clean_watch_20260907.sql` / 46,471 bytes / Dump completed on 2026-09-07 10:29:01） - **照合方法**: (1) 09-02版との全体 diff (2) 各 `CREATE TABLE` ブロックからの項目抽出 (3) 追加されるはずの制約名の全文検索。**3方法で一致** - **全体差分は14行のみ。テーブル数は 39 で変化なし**（テーブル名の集合も完全一致） | # | 約束された修正（D-061 / D-065） | 新DDLの実測 | 状態 | |---|---|---|---| | A-1 | `error_id` を主キーと位置付けて対応 | PRIMARY KEY 無し。UNIQUE KEY は `error_id` のみ。`id`/`error_id` とも varchar(50) | 未反映 | | A-2 | 履歴テーブルの id を auto_increment で採番 | `clean_status_histories.id` / `clean_timetable_histories.id` とも AUTO_INCREMENT 無し。**ファイル全体の AUTO_INCREMENT 数が 50 で09-02版と同数** | 未反映 | | A-3a | `contact_type` を両テーブルとも tinyint | `customer_contacts.contact_type` が **bigint unsigned → tinyint unsigned** に修正 | **反映** | | A-3b | `email` を両テーブルとも varchar(100) | `customer_contacts.email` = varchar(100)（元から一致）／**`facility_contacts.email` = varchar(255) のまま** | 未反映 | | B-1 | 外部キー3本を追加 | 3本とも無し。制約名（`clean_statuses_clean_timetable_id_foreign` 等）を全文検索しても不在。**CONSTRAINT 総数 48 で09-02版と同数** | 未反映 | | B-2 | `robot_task_versions.clean_schedule_id` にインデックス | KEY は `robot_id` のみ | 未反映 | | B-3a | `clean_task_reports` の created_at / updated_at に DEFAULT | **両方付与**（`DEFAULT CURRENT_TIMESTAMP` / `DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP`） | **反映** | | B-3b | `security_status_histories.reported_at` に DEFAULT | `timestamp NOT NULL` のまま | 未反映 | - **★結論: 7項目中2項目のみ反映。5項目が未反映★** - **`prisma/schema.prisma` に必要な変更は2箇所だけ**（`db pull` で機械的に入る） - `CustomerContact.contact_type`: `BigInt @db.UnsignedBigInt` → `Int @db.UnsignedTinyInt` - `CleanTaskReport.created_at` に `@default(now())`、`updated_at` に `@default(now()) @updatedAt` - **運用**: D-059 のとおり**受領したDDLを正とする**。`docs/handoff/指示書E_スキーマを実DDLに一致.md` の手順で `db pull` をやり直す。**残り5件が入った次のDDLで、もう一度やり直すことになる** - **★A-1 が未反映でも `PrecheckItem.id` の `string` 化は進めてよい★** D-065 C-3-1 で「`error_id` を使う方針で問題ない」と回答を得ており、 DDL に PRIMARY KEY が付くかどうかは API が返す値の選択に影響しないため ### D-067 `[一部破棄]` 2026-09-07 のDFA判断4件（D-3 / D-2 / 月跨ぎ週 / R3） > ★**このうち「月跨ぎ週の帰属」は D-071 で破棄した。**★ > TeamWorks のサマリ集計が「月境界で週を分割する」方式（D-070 の W-1）だったため、 > **本項の「1日を含む週がその月の第1週」は採用しない。D-071 を正とする。** > 残る3件（D-3 / D-2 / R3）は有効。 #### 1. セキュリティ解除は制御盤の生死報告とは別概念（第3回 D-3 の結論） - **制御盤の生死報告が来ない場合**は、サーバーから「制御盤異常」として**エラーが上がる** （＝ `control_error_histories` に入る） - **セキュリティが解除されたままの状態は、エラーにはならない。別の値として管理される** （＝ `security_statuses.status = 0`） - **決定**: 「セキュリティ解除されたまま」は **DFA 側で `security_statuses.status = 0` の継続から導出する**。 `control_error_histories` には入らないので、**二重検知の心配は無い** - **帰結**: `DsAlertType` の2値は取得元が完全に別。 - `disconnected` ← `control_error_histories`（制御盤異常のエラー） - `security_off` ← `security_statuses`（状態から導出。エラーではない） - ★**この2つを同じテーブルから取ろうとしないこと**★ #### 2. `robot_error_reports.error_type` は「その他」に寄せて先行実装する（第3回 D-2） - **決定**: 既知の値だけをマップし、**未知の値はすべて「その他」に寄せて実装を進める**。 TeamWorks からの値一覧を待たない - **並行して**: 値の一覧作成を TeamWorks へ依頼し、届いたらマップに追加する - **実装の形**: ★**分類を1つの純粋関数に閉じ込めること**★。 値が届いたときにその関数だけを直せば済む形にする（テストも同関数に対して書く） #### 3. 月跨ぎ週の帰属 — ★D-024 から変更★ - **決定**: **その月の1日を含む週が、その月の第1週**。 言い換えると「**1日でも翌月が混ざれば、その週は翌月の第1週**」 - **例**: `2026-08-30(日)〜09-05(土)` は **9月第1週**。8月の週は `08-23〜08-29` で終わる - **★旧 D-024（週の開始日が属する年月）とは逆です★** - **★TeamWorks との整合が未確認★**: 週次サマリを作るのは TeamWorks（D-023）。 帰属ルールが食い違うと、**同じ週が DFA の画面では9月、サマリテーブルでは8月**という ズレが起きる。**第4回で確認すること** - **実装**: 指示書F 段階1 の `weekOfMonth()` はこのルールで実装する。 月次・年次は暦月・暦年の日単位で締める（週とは独立）点は D-024 から変更なし #### 4. アドバイス規則 R3 に「出発失敗」を含む（第1回 C-1 の結論） - **決定**: R3 は「同一施設で**2日以上連続（出発失敗 or △以下）**」。**実装（`lib/config/advice-rules.ts:75`）が正しく、`CLAUDE.md` §4.5 の表が誤り**だった - **対応**: `CLAUDE.md` §4.5 の R3 の行を実装に合わせて修正した（2026-09-07） - **帰結**: R3 と R4 の違いは**連続日数だけ**になる（R3 = 2日以上 / R4 = 3日以上）。 3日連続時は R3 と R4 が両方出る（段階的対応を促すため意図的。D-038 と同じ考え方） - **指示書D の「やらないこと」から外れました。** 文言・条件を動かしてよくなりました ### D-068 `[確定]` F-04 レポート画面 段階0（`d-watch-api.yaml` 契約修正） 指示書F 段階0（0-1〜0-9）を実施。詳細は指示書F本文、実装は `d-watch-api.yaml`。 - **`ContinuousProblem`**: 名前付きスキーマに切り出し、`facility_id` を追加、`consecutive_days`→ `consecutive_problem_days` に統一（`CleanLogItem`/`FacilityPerformance` と表記を揃える）。 **`completion_rate` を削除し `summary`（自由文の説明）を返す形に変更 — ★モックからの逸脱★**。 モックの「完了率{n}%」より、`lib/fixtures/reports.ts` が持つ「スケジュール存在日ベースで3日連続」等の 自由文のほうが D-026（連続日数はスケジュール存在日で数える）の説明として有用と判断した - **`ErrorBreakdownItem`**: `error_type`（日本語string、enum定義なし）→ `type`（`ErrorType` 英字enum7種）+ `label` + `rate` の構成に統一。`/dashboard` の `failure_breakdown` と同じ3点セット構成に揃えた。 日本語文字列をキーにすると i18n・比較・DB保存で破綻するため - **`ReportKpi`** を名前付きスキーマに切り出し（`PrecheckListResponse` 等と同様の前例に揃える） - **`KpiValue.value` を `nullable: true` に。** `lib/judge/kpi.ts` の4関数が分母0のとき `null` を返す （「予定が1件もない期間」と「予定はあったが全部失敗」を区別するため）契約を型で表現できていなかった - **`/reports/error-breakdown` は `meta` を返さない。** 7分類固定でページングの余地が無いための、 「一覧APIは必ずmetaを返す」（CLAUDE.md §9.3）の例外として description に明記 - `FacilityPerformance` に `serial_number` を追加（絞り込みキーが結果に出ていなかった不整合の解消） - レポート4本すべてに `422`（`ValidationError`）を追加。`Period` の description に「P1は週次/月次のみ、 年次は範囲外」を追記（enum に `yearly` は追加しない） #### `week` パラメータの上限は 5 のまま（★指示書F の誤りを訂正★） 指示書F 段階1 は当初「日〜土の切り方だと月によっては第6週が発生する（1日が土曜の31日月など）ので `maximum` を`5`→`6`に直す」としていたが、**これは誤りだった。** - D-067 の月跨ぎ週の帰属ルール（その月の1日を含む週がその月の第1週）の下では、 1か月に属する週数は `floor((offset+日数)/7)`（offset=1日の曜日番号0〜6、日数28〜31）で決まり、 最大でも **5**（`floor((6+31)/7)=5`）。第6週は発生しない - `lib/format/__tests__/period.test.ts` で2020〜2040年の全日を総当たりして確認済み - **対応**: `d-watch-api.yaml` の `Week.maximum` は `6` にせず `5` のまま。指示書F本文（段階1・3-1・3-5・ 完了条件テーブルの4箇所）も訂正した #### `judgeFacilityStatus` に `null` を渡したときの判定 `KpiValue.value` が nullable になったことで、`FacilityPerformance.status` を出す `judgeFacilityStatus(operation_rate.value)` が `number | null` を受け取る必要が生じた。 - **決定**: `null`（清掃予定が1件もない期間）は **「要改善(bad)」に寄せる** - **理由**: `judgeGrade()` が「未実施」を`×`（最悪判定）に寄せているのと同じ考え方（CLAUDE.md 4.1）。 予定が無い＝良好とは言えないため、既存の判定ロジックの流儀に揃えた - `lib/judge/kpi.ts` の `judgeFacilityStatus` の引数型を `number | null` に変更し、テストに境界値を追加した ### D-069 `[確定]` F-04 レポート画面 段階1〜5（画面実装まで完了） 指示書F の残り（段階1〜5）を実施。実行コミットは develop ブランチの一連のコミット （`234987e` 段階1 / `daf3788` 段階2 / `787f143`・`4c47412` 段階3 / `7afe055` 段階4 / `6ecfc2b`・`368e185` 段階5）。実行環境: Claude Code（サブエージェントに委譲。指示書D と同じ経路）。 #### 1. 期間指定・当期・年次・連続問題施設の絞り込み（指示書F「先に決まっていること」1/2/3/6を実施） - **期間指定は `period`+`year`+`month`+`week` のみ。モックの日付範囲input・グループ/会社selectは作らない** （既に決定済みの方針どおり実装。`ReportsScreen.tsx` に理由をコメントで残している） - **当期は「器だけ」。** `lib/reports/query.ts` の `selectKpiRow` は当期かどうかを判定するが、 分岐しても null を返すだけで実集計はしない（`prismaSource` 実装時に差し替える） - **年次は範囲外。** `Period` 型に `yearly` を追加していない - **連続問題施設は2日以上（`consecutive_problem_days >= 2`）で絞り込み。** `docs/spec.md:58` の 「L1〜L3」は誤記だったため本文を修正した（後述） #### 2. `week` の上限は 5 のまま（D-068 の訂正を段階1〜3全体に反映） D-068 で「当初『第6週が発生する』としたのは誤りで、D-067下では最大5」と訂正済み。 `lib/format/period.ts`（`weekOfMonth`が1〜5のみ返すことを2020〜2040年で全数検証）・ `lib/reports/query.ts`（`WEEK_MAX = 5`）・`d-watch-api.yaml`（`Week.maximum: 5`）が一貫して5である ことを確認した。指示書F本文の該当4箇所も訂正済み。 #### 3. 施設別パフォーマンス表のセル色分けは `FACILITY_STATUS_THRESHOLDS` を流用する（★モックからの逸脱★） `d-watch-mock.jsx:802,804` は稼働率・出発成功率のセル色を `<80→ng / <90→wn / それ以外` と **80/90をハードコード**しているが、実装では既存の `FACILITY_STATUS_THRESHOLDS`（good=90/warning=75。 `judgeFacilityStatus`が稼働率をこの閾値で「良好/注意/要改善」に判定し、同じ表の「ステータス」列に 出ている）を流用した。 - **理由**: セルだけ別の閾値で色分けすると、同じ行で「ステータス=良好」なのに 「稼働率セル=警告色」という矛盾が起きる（例: 稼働率76%はstatus=warningだがモック基準ではng）。 また CLAUDE.md §7「閾値のハードコード禁止」に対し、80という数値に対応する設定値が存在しなかった - 良好側の色は稼働率=`ok`（緑）/出発成功率=`pr`（青）とモックのとおり2列で異なる値を維持した - 実装: `components/features/reports/FacilityPerformanceTable.tsx` の `rateTone()` #### 4. エラー率セルの色分け用に `FACILITY_TABLE_THRESHOLDS`（`lib/config`）を新設 モック（`:807`）の `エラー率 > 8 → ng` に対応する設定値が既存に無かったため、 `lib/config/index.ts` に `FACILITY_TABLE_THRESHOLDS = { errorRateWarning: 8 }` を新設した。 判定ロジック（◎○△×・L1〜L3）の閾値とは別物である旨をコメントで明記している （表の色分けは判定基準ではない。CLAUDE.md §7 のハードコード禁止に従うための外出し）。 #### 5. 「変化」列（稼働率diffと完了率diffの合成値）は、どちらかがnullなら中立表示 `overallDiff = Math.round((operation_rate.diff + completion_rate.diff) / 2)` を算出する際、 `diff`のどちらかが`null`（新規施設・予定0件で prev/value のどちらかが取れない）なら 合成せず `→`（中立色）を出す。指示書F 5-7 の推奨どおり。 #### 6. エラー種別内訳の空データ時の文言は「該当なし」（指示書F 5-6） 連続問題施設の「該当施設なし」とは対象が違う（施設の一覧ではなくエラー種別の一覧）ため、 モックが持たない空データ文言として「該当なし」を新規に採用した。 #### 7. `facilityPerformance` / `continuousProblems` の `consecutive_problem_days` 不整合を修正 fixtures の施設3・4で、`facilityPerformance`（0日・2日）と `continuousProblems`（2日・3日）が 同一施設・同一フィールド名で異なる値を持っていた（段階2実装時に発覚した既存不整合）。 `continuousProblems` 側の値（narrative summary を伴う「正」）に `facilityPerformance` 側を合わせた。 `status`（施設別パフォーマンスの良好/注意/要改善）は稼働率ベースで別の指標なので変更していない。 #### 8. その他の実装判断 - **CSVエクスポートボタンは押しても何もしない仮実装。** `/reports/*` にexportエンドポイントが 契約上存在しないため、エンドポイントを新設せずボタンのみ置いた（指示書F「やらないこと」どおり） - **検索欄（施設名・シリアル・ステータス）は「検索」ボタン押下時のみAPIに反映する。** 入力ごとにAPIを叩かないための設計（`ReportsScreen.tsx` の draft/確定ステートの分離） - **エラー種別のバー色（`ProgressBar`のtone）は7種を3段（ng/wn/ac・pr）に寄せた。** `ProgressBar`はF-01と共用の完成済み部品でtoneが5つしかなく、モックの7色に厳密な意味づけの 仕様も無いため、増設せず既存の5toneに収めた - **`FacilityPerformanceTable`はフッタ（全N件表示→/上位10件に戻す）まで内包する設計にした。** 表の状態（showAll）と直結し他画面で使い回さないため `docs/spec.md:58`「連続問題施設（L1〜L3）」は「2日以上連続」に修正済み（本コミットで対応）。 ### D-071 `[確定]` 月跨ぎ週は TeamWorks 方式（月境界で分割）に統一する（2026-09-07） **W-1 の回答（D-070）を正とする。ユーザー判断。D-067 の月跨ぎ週の項は破棄。** #### ルール 週は日曜〜土曜。ただし**月をまたぐ週は月境界で切り、それぞれの月の別々の週として数える。** - 各月の**第1週は必ず1日から**始まり、**最終週は必ず末日で**終わる - ★**週の長さは1〜7日で変わる**★ - ★**月の週番号は1〜6**★（第6週は「1日が金曜または土曜の30日/31日月」で発生） #### 実装式（★総当たりで検証済み★） `dowOfFirst` はその月の1日の曜日（0=日）。 ``` weekOfMonth(date) = { year, month, week: 1 + floor((day - 1 + dowOfFirst) / 7) } weeksInMonth(y, m) = 1 + floor((lastDay - 1 + dowOfFirst) / 7) periodRange 開始日 = week === 1 ? 1 : (week - 1) * 7 - dowOfFirst + 1 periodRange 終了日 = min(開始日 + (6 - 開始日の曜日), lastDay) shiftPeriod(-1) = weekOfMonth(その週の開始日 - 1日) shiftPeriod(+1) = weekOfMonth(その週の終了日 + 1日) ``` **`year` / `month` は日付からそのまま取る**（D-067 のように週末の属する月へずらさない）。 これにより `firstWeekStartMs()` は `weekOfMonth()` から不要になる。 #### 検証内容（2020〜2040 の全252か月を総当たり） | 検証 | 結果 | |---|---| | TeamWorks の回答例7件（08-01 / 08-30 / 08-31 / 09-01 / 09-05 / 09-06 / 09-12） | **全件一致** | | 各月の週が、その月の全日をちょうど1回ずつ覆うか | **違反0件** | | 週の開始は「1日 or 日曜」、終了は「末日 or 土曜」か | **違反0件** | | 週の全日について `weekOfMonth()` が元の (年,月,週) を返すか（往復） | **違反0件** | | 存在しない週番号で `periodRange()` が null になるか | **違反0件** | | 週番号の最大値 | ★**6**★（2020-05 / 2025-03,08,11 / 2026-05,08 / 2027-01,05,10 …） | | 週の長さの分布（252か月・全1313週） | 7日=879 / 1日=73 / 3日=73 / 6日=73 / 2日=71 / 4日=74 / 5日=70 | ★**1日しかない週が年に2〜3回発生する**★（2026年は 08-01 がそれ）。 TeamWorks も「**その分集計結果に差が出ますが、そこは運用後の課題になります**」と承知している。 #### この判断の理由 ★**週次サマリを作るのは TeamWorks（D-023）で、DFA はそれを読むだけ。**★ DFA が別ルールを持つと、**確定週（サマリ由来）と当期（DFA がその場集計）で週の定義が変わり、 同じ画面の中で数字の意味が変わる。** 合わせる以外の選択肢がない。 #### 影響（★`d-watch-api.yaml` の `Week` の上限が変わる★） - `d-watch-api.yaml` の `Week.schema.maximum` を **5 → 6** に変更する。 これは **D-069 の「2. `week` の上限は 5 のまま」を上書きする** - `lib/format/period.ts` の `weekOfMonth()` / `periodRange()` / `shiftPeriod()` を差し替える - `lib/format/__tests__/period.test.ts` の「2020〜2040 総当たりで週番号は1〜5」という 不変条件が**崩れる**ので、期待値表ごと差し替える - ★**実装は指示書H（`docs/handoff/指示書H_月跨ぎ週をTeamWorks方式に統一.md`）で行う**★ #### ★このルールを採用して見つかった矛盾（第5回で照会）★ **TeamWorks 自身のテーブル定義書と、TeamWorks の W-1 回答が食い違っている。** | # | 内容 | |---|---| | **X-1** | ★**定義書のサマリ4テーブルの `week` は「第1週 1 〜 第5週 5」で、第6週を表現できない**★（`docs/handoff/analysis/table-definitions-03-schedule-summary.md:321-322`）。W-1 の回答は8月第6週を認めているので矛盾する。**定義書が古いのか、第6週を別扱いするのかを照会**（`docs/handoff/TeamWorks確認事項_第5回_20260907.md`）
★**ユーザー判断: 第6週はカレンダー上実際に発生するので、`week` の上限は 6 として実装する（X-1 の回答を待たない）**★ | | **X-2** | 同じ備考から **`week=0` が月の集計値、`month=0` が年の集計値**と読める。★**`week=0` は予約値なので API の `week` は 1 以上のみ受け付ける（`WEEK_MIN=1` を下げないこと）**★ | | **X-3** | 週次バッチの「前週」が月をまたぐと**2行になる**はず（例: 2026-09-06 のバッチで `2026/8/6週` と `2026/9/1週`）。1行に寄せると片方の期間の数字が欠ける | #### ★第5回の共有文書に、エラー情報の確認3件（Y-1〜Y-3）を追加した（2026-09-07）★ **テーブル定義書を確認したところ、`error_level` / `error_type` / `error_detail` の 備考欄がいずれも空欄**だった（`docs/handoff/analysis/table-definitions-02-clean-error.md:28-29` ほか）。 **格納される値が分からないと対応表のキーが決まらない。** | # | 内容 | なぜ必要か | |---|---|---| | ★**Y-1**★ | `robot_error_reports.error_type`（`varchar(100)`）に入る値の**形**（PUDU のコード番号か / コード名（英字）か / 日本語か / 組み合わせか）。**実例1〜2件**。空文字や NULL になるか | ★**清掃詳細ログの状態表示（ハンドルアップ / 緊急停止 / オフライン）が作れない**★。D-2 の回答は「PUDU のドキュメント参照」だが、**当方が作る対応表のキーは「先方が何を格納するか」で決まる** | | **Y-2** | `robot_error_reports.error_level`（`varchar(20)`）の値一覧と、**どちらが重いか** | 重要度表示と並び順に使う | | **Y-3** | サマリ側（`customer_error_summaries` / `facility_error_summaries`）の `error_type` が明細と**同じ値域か**。`error_detail`（`text`）に何が入るか | ★**レポートのエラー内訳はサマリから読む設計**★。明細とサマリで分類が違うと**同じ画面で数字が突き合わせられない** | ★**第5回は「新規に第6回を作る」のではなく、未送付の第5回に統合した。**★ **送付が1回で済み、優先順も1つの表で伝えられるため。** 構成は ①解決した件の共有3件（回答不要）②最新のDDLのお願い ③週の帰属3件（X-1〜X-3） ④エラー情報3件（Y-1〜Y-3）⑤継続と保留。 **B-1 / B-2（外部キー3本とインデックス）は「後で登録する」との回答どおり保留で了解** （ユーザー判断。2026-09-07）。**当方の開発は止まっていない。** ★**X-1 が「B: 週は1〜5のまま」だった場合、指示書H の実装をやり直すことになる。**★ ただし**指示書H の作業は止めない**（DFA 側の暦計算は W-1 の回答が正で、 矛盾しているのは「先方がサマリに第6週をどう格納するか」＝ `prismaSource` 実装時に必要な情報。 サマリ読み込みは未実装で、いまは fixtures で開発している）。 #### この判断で発生した副作用（記録） - **`week=6` を保持したまま週数の少ない月へ移動できる穴**が `ReportsScreen` の `navigatePeriod` にある（`setWeek(next.week ?? week)`。移動先の月に週が存在するか検証していない）。 ★**旧ルールでも起きる既存の穴で、`WEEK_MAX` を 6 にしても 422 にはならない**★ （`week=6` は上限内を通り、期間キーが一致せず**空KPI**になるだけ）。 **モックに「存在しない週を選んだときの表示」の仕様が無いため、指示書H では直さない** ### D-072 `[確定]` 2026-09-07 のユーザー判断3件（HTTPS終端 / 第1週 / 週番号クランプ） #### 1. HTTPS はロードバランサで終端する。★アプリは HTTP で受ける★ **ユーザー回答**: 「HTTPSはロードバランサがあるのでそこで終端します、そこからHTTPでこちらに来ます」 **これで「HTTPS の終端場所」の未決（D-047 以来の継続）は解消。** 帰結: | 項目 | 決まったこと | |---|---| | アプリ側の TLS | ★**扱わない**★。自前で証明書を持たない | | ★**IP制限**★ | ★**`X-Forwarded-For` を見る**★。LB 経由なので接続元アドレスは**LBのもの**になり、素の接続元IPでは絞れない。**信頼できるのは LB が付けた最後の1ホップだけ**なので、クライアントが偽装したヘッダを信じない実装にすること | | cookie の `Secure` | ★**付ける**★。ブラウザ〜LB 間は HTTPS なので、アプリが HTTP で応答しても**ブラウザは受け入れる** | | リダイレクト・絶対URL生成 | LB が HTTPS を終端するため、アプリが自分で組み立てると `http://` になる。**`X-Forwarded-Proto` を見るか、相対URLで済ませる** | ★**未実装のまま**★: `app/login/` / `middleware.ts` はいずれも存在しない（実測）。 **認証は未着手で、現状は URL を知っていれば全画面が開く。** 社外や社内ネットの外に出す前に必須。 #### 2. ★第1週が1日しかなくても第1週。表示に特別な注記は入れない★ **ユーザー回答**: 「第1週が1日しかなくても第1週です」 - `periodLabel()` は `2026年8月 第1週` のまま。**1日であることを示す注記や but 表示は入れない** - ★**指示書H 段階2-6 の「要判断」はこれで閉じる。**★ 画面に from〜to を出す変更も**しない** - 同じ理由で、**2日しかない第6週**（2026-08-30〜08-31）も `第6週` とだけ表示する #### 3. ★存在しない週番号は、その月の最大週へクランプする★ **ユーザー回答**: 「ReportsScreen に週番号のクランプが無いこれはnullの場合は最大値を返すように変更できないですか」 **採用。** `lib/format/period.ts` に次を追加し、画面から使う。 ```ts /** * 指定年月に存在しない週番号を、その月の最大週へ丸める（D-072）。 * 月次→週次の切替や月移動で、移動先の月に無い週番号が残るのを防ぐ。 */ export function clampWeek(year: number, month: number, week: number): number { return Math.min(Math.max(week, 1), weeksInMonth(year, month)); } ``` `ReportsScreen` の `navigatePeriod`: ```ts // 変更前: setWeek(next.week ?? week); setWeek(next.week ?? clampWeek(next.year, next.month, week)); ``` **具体例**: `2026年8月 第6週` を表示中に月次へ切替 → `9月` へ移動 → 週次へ戻す。 - **変更前**: `week=6` のまま要求 → 9月は5週しかないので**KPIが4指標すべて null の空表示** - **変更後**: `9月 第5週`（09-27〜09-30）にクランプされ、**数字が出る** ★**`shiftPeriod` 内部の `week ?? 1`（週が未選択のときは第1週から動かす）は変えない。**★ 「週が選ばれていない」と「選ばれた週が移動先の月に無い」は別の状況で、 後者だけをクランプする。前者は既存テスト（`weekly` で `week` が無いときは第1週から動かす）が固定している。 #### 4. ★`week=0` / `month=0` は DB 側の規約を正とする（X-2 の回答を待たない）★ **ユーザー回答**: 「week=0の処理はDB側を正として処理してください」 **テーブル定義書の規約をそのまま採用する。** 第5回 X-2 は**確認のみ**とし、回答を待たずに実装する。 | 粒度 | `year` | `month` | `week` | DFA が読むか | |---|---|---|---|---| | 週次 | 年 | 月 | **1〜6** | ★読む★ | | 月次 | 年 | 月 | ★**0**★ | ★読む★ | | 年次 | 年 | ★**0**★ | ★**0**★ | ★**読まない**★（`d-watch-api.yaml` の `Period` に「P1 は週次/月次のみ。enum に yearly を追加しないこと」と明記） | ★**調査結果: `week=0` の扱いは、リポジトリ内のどの設計文書にも書かれていなかった。**★ 書かれていたのは**テーブル定義書の備考の転記だけ** （`docs/handoff/analysis/table-definitions-03-schedule-summary.md:115-116` ほかサマリ4テーブル）。 `docs/spec.md` / `d-watch-api.yaml` / `lib/reports/query.ts` には一切登場しない。 #### ★DFA 内部表現と DB 表現の食い違い（`prismaSource` 実装時の要点）★ | 層 | 月次の表し方 | 根拠 | |---|---|---| | API のクエリ | `period=monthly` + **`week` は無視** | `d-watch-api.yaml` の `Week` の description | | バリデーション | monthly のとき `week` を読み捨てて `null` にする。weekly では `week=0` を **422** | `lib/reports/query.ts:135-147` | | 内部の行キー | ★**`week: number \| null`（月次は `null`）**★ | `lib/types/index.ts:223`、`matchesPeriod`（`lib/reports/query.ts:274-282`）は**完全一致**で判定 | | DBスキーマ | ★**`week` は `Int`（NOT NULL）→ 月次は `0`**★ | `prisma/schema.prisma:626-628` ほか | **決定**: ★**内部表現も `0` に統一する**★（ユーザー判断。当初「`null` のまま境界で変換」と 記録したが、**撤回してこちらを正とする**）。 | 層 | 月次の表し方 | 変更 | |---|---|---| | API のクエリ（`d-watch-api.yaml`） | `period=monthly` + **`week` は無視**（送られてきても読み捨てる） | ★**変更しない**★。API 契約は現状のまま | | バリデーション（`parseReportQuery`） | monthly のとき `week` を読み捨てて ★**`0`**★ にする | `null` → **`0`** | | 内部の行キー・関数引数 | ★**`week: number`（月次は `0`）**★ | `number \| null` → **`number`** | | DB | `week = 0` | 変更なし（元から 0） | ★**これで「月次＝`week` が 0」が API 境界から DB まで一直線になり、変換が消える。**★ `matchesPeriod` は条件分岐が不要になる（`row.week === query.week` の単純比較）。 - 月次を読む: `WHERE year=? AND month=? AND week=0` - 週次を読む: `WHERE year=? AND month=? AND week=?`（1〜6） - **年次（`month=0 AND week=0`）は読まない。** 誤って拾わないよう ★**`month >= 1` を条件に入れる**★ - ★**API の `WEEK_MIN=1` は下げない**★。`week=0` は「月次」を意味する予約値であり、 **`period=weekly` で `week=0` は 422 のまま**。読み捨てて 0 にするのは monthly のときだけ ★**実装は指示書H の段階5で行う**★（週の帰属変更が緑になった後、別コミットで）。 #### 6. ★認証は A案（`middleware.ts` + cookie + `X-Forwarded-For` 許可リスト）★ **ユーザー回答**: 「A案でお願いします」 `docs/architecture.md:50` の「認証方式は cookie 方式と決まっている」と一致。 **待っていたのは HTTPS の終端場所だけで、それが本項1で解決したので着手できる。** | 項目 | 決めたこと | |---|---| | 保護のかけ方 | ★**`proxy.ts` で全ルートを保護**★（**`middleware.ts` ではない。下の訂正を読むこと**） | | ログイン | `app/login/` で共有トークンを入力 → 検証して cookie を発行。`app/api/auth/login` / `logout` | | cookie | ★**`httpOnly` + `Secure` + `SameSite=Lax`**★。ブラウザ〜LB 間は HTTPS なので `Secure` は有効 | | IP制限 | ★**`X-Forwarded-For` の「LB が付けた最後の1ホップ」だけを信じる**★ | | トークンの期限 | ★**実装しない**★（`CLAUDE.md` §7「トークン期限/残日数の実装」は禁止） | ★**踏んではいけない地雷**★ - ★**`X-Forwarded-For` の先頭を信じてはいけない。**★ クライアントが自分で `X-Forwarded-For: 10.0.0.1` を付けて送れるため、**先頭を見ると IP制限を素通りできる** - **リダイレクトや絶対URLを自前で組むと `http://` になる**（LB が HTTPS を終端するため）。 `X-Forwarded-Proto` を見るか**相対URLで済ませる** - **許可IPは `lib/config/` から読む**（`CLAUDE.md` §7 のハードコード禁止） - **トークンは `.env.local`。絶対にコミットしない**（`CLAUDE.md` §9.3） #### ★訂正: ファイル名は `proxy.ts`。`middleware.ts` は Next 16 で非推奨★ **本項を当初「`middleware.ts` で保護する。`proxy.ts` は不要」と記録したのは誤り。** `node_modules/next/dist/docs/` の現行ガイドを読んで確認した（`CLAUDE.md` 末尾の 「This is NOT the Next.js you know」に従った調査）。 - **`next` のバージョンは 16.3.3**（`node_modules/next/package.json`） - `middleware.md` の deprecation notice 原文: > The `middleware.js` file convention has been **deprecated** in Next.js 16 and renamed to `proxy.js`. > All functionality remains the same — only the file and export names have changed. > 自動移行: `npx @next/codemod@canary middleware-to-proxy .` - ★**`middleware.ts` を置くと dev で警告が出る**★ （`node_modules/next/dist/server/lib/router-utils/setup-dev-bundler.js`: `The "middleware" file convention is deprecated. Please use "proxy" instead.`） ★**「proxy」という語を2つの意味で使っていたのが混乱の元だった。**★ | 語 | 意味 | 状態 | |---|---|---| | **TLS を終端するリバースプロキシ** | nginx / ロードバランサ | ★**LB が担当。アプリ側では不要**★（本項1） | | ★**Next.js の `proxy.ts`**★ | フレームワークのファイル規約。全リクエストの前段で走る | ★**必要。ここに認証と相関IDを置く**★ | `docs/architecture.md:39` と `docs/logging-design.md:26,43,76` は**最初から正しく `proxy.ts`** と 書いていた。**当方の記録だけが `middleware.ts` になっていた。** #### 実装の要点（★ガイドを読んで確認済み★） | # | 項目 | 確認できたこと | |---|---|---| | 1 | ファイルと関数 | `proxy.ts` をプロジェクトルート（`app` と同階層）に置き、★**named export `proxy`**★（default も可だがガイドが named を推奨）。型は `NextProxy` | | 2 | ランタイム | ★**Node.js 固定。`runtime` を指定するとエラーになる**★。Edge は `proxy` では非対応。**`fs` は使える** | | 3 | 1ファイル制約 | ★**公式推奨は「機能ごとに別モジュールへ分け、`proxy.ts` から import する」**★。→ `architecture.md:39` の懸念は解ける。**相関IDの発行を先、認証を後**に置く（`logging-design.md:408`。認証失敗もログで追える） | | 4 | `matcher` | ★**`/login` は matcher で除外せず、関数内で分岐する**★（公式の認証例がその形）。`matcher` に変数は使えない（ビルド時に静的解析されるため）→ **許可IPリストは matcher に書けない** | | 5 | cookie | `NextResponse` の `cookies.set()`。`httpOnly` / `secure` / `sameSite: 'lax'` / `path` を指定。★**`expires` / `maxAge` は入れない**★（`CLAUDE.md` §7「トークン期限/残日数の実装」は禁止。公式例との差分） | | 6 | `X-Forwarded-For` | ★**ガイドに記述が無い**★。しかも **`request.ip` は Next 15 で削除済み**なので、**ヘッダを読む以外に手段が無い**。「最後の1ホップだけを信じる」ロジックは**自前で書く** | #### ★踏むと痛い地雷（調査で判明）★ | # | 内容 | |---|---| | 1 | ★**`matcher` を書かないと静的ファイルにも全部かかる**★。ガイドの警告: 除外しないと「auth logic or redirects can unintentionally block CSS, JS, or images from loading」 | | 2 | ★**`_next/data` は matcher で除外しても必ず `proxy` が走る**★。「ページを保護したのに対応するデータルートを保護し忘れる」事故を防ぐための意図的な挙動 | | 3 | ★**Server Functions は matcher の除外を受けても実行される**★（使用ページへの POST として扱われる）。ガイドは「**各 Server Function の中で認証・認可を検証せよ。`proxy` だけに頼るな**」と明記。**P1 では Server Actions を使っていないので `proxy` 単独で足りるが、その前提を明文化すること** | | 4 | ★**`redact.ts` に cookie 名を追加すると既存テストが2件落ちる**★。`lib/logger/__tests__/redact.test.ts` が認証8キーの**配列を順序込みで完全一致**させ、さらに `toHaveLength(21)` で件数を固定している。**同時に更新すること** | | 5 | `redact.ts` のコメントが「cookie 名そのもの（`dwatch_session` 等）は未決なので入れない。**認証実装時に決まった名前をここへ追加すること**」と申し送っている。テストデータにも `dwatch_session=abc123` が使われており、★**cookie 名は `dwatch_session` が既定路線**★ | | 6 | ★**`AUTH_TOKEN` は `.env.example` と `.env.local` に既にあるが、コードから一度も読まれていない**★。新しい環境変数を増やす必要はない | | 7 | **LB 配下では `serverActions.allowedOrigins` の設定が必要になる可能性**（`next.config.ts` は現在未設定）。Server Actions を使い始めるときに要検討 | | 8 | 許可IPリストは ★**`lib/config/` の独立ファイル**★ に置く（`lib/config/allowed-ips.ts` 等）。`lib/config/index.ts` は `lib/judge/` から広く import されており、`proxy` のバンドルに judge 系を引き込む恐れがある。ガイドも「proxy は shared modules に依存すべきでない」と警告 | #### あわせて更新が必要な文書 | 文書 | 内容 | |---|---| | `docs/architecture.md:39` | `proxy.ts` の状態「未着手（認証方式の決定待ち）」→ **方式は決定済み** | | `docs/architecture.md:49-52` | `d-watch-api.yaml` の `securitySchemes` が **`bearerAuth` / Laravel Sanctum の残骸**。★**cookie 方式に書き直す**★。「HTTPS の終端場所が回答待ち」という保留理由は**解消済み** | | `docs/architecture.md:184-195` | 未確定表の「リバースプロキシの有無」「HTTPS の終端場所」が**解決済み**。`lib/auth/` という置き場所が既に予告されている | | `docs/logging-design.md:437` | 「フェーズ2 は認証との共存方針を確認してから着手」→ ★**本項で解除**★ | ★**指示書I（認証）は本項を根拠に作成する。**★ #### 7. 点検記録（`inspections`）は最後に回す **ユーザー回答**: 「これはあとまわしていいので、全ての実装が終わった後で構いません」 **理由**: DFA 独自ストア（SQLite + オブジェクトストレージ。D-004）が未着手で、 **写真の置き場所・バケット・期限付き署名URLが未決**のため。 先に画面を作ると**写真が表示できない画面ができる。** → `facilities` / `schedules` / `system` を先に作る。 #### 8. ★JSON ストアを共通部品にし、`advice.ts` の3欠陥を潰す（指示書G の「やらないこと」を上書き）★ **`lib/settings/advice.ts` は、このリポジトリで唯一ファイルを書くコード** （`node:fs` の import はリポジトリ全体でこの1ファイルだけ。ビルド成果物でも確認済み）。 **欠陥が3つあり、指示書G がこれを「ひな型にする」と指示しているため、放置すると複製される。** | # | 欠陥 | 具体的な壊れ方 | |---|---|---| | 1 | `readOverrides`（`advice.ts:26-34`）が `catch` で**「無い」と「壊れている」を区別せず `{}` を返す** | 壊れた状態で画面を開くと既定値だけが出る → 運用担当が1件だけ直して保存すると ★**残り全件が本当に消える**★（`saveAdviceRule:70-72` が read→merge→write のため） | | 2 | `fs.writeFile`（`advice.ts:38`）が**非アトミック**（既存ファイルを切り詰めてから書く） | 保存中にプロセスが落ちるとファイルが空か途中になる → 欠陥1 の入口。★**`/data` は `.gitignore` されており git のバックアップが無い**★ | | 3 | `advice.ts:22` が `process.cwd()` 起点のパスを**モジュール先頭の定数で固定** | ★**テストから保存先を差し替えられない**★ → `lib/settings/__tests__/` が存在せずテスト0件。`mkdtemp` を使うテストの前例もリポジトリに0件 | **決定**: ★**`lib/settings/json-store.ts` を作り、`advice.ts` と `ds-device-notes.ts` の両方から使う。**★ 指示書G の「やらないこと」にある「`advice.ts` のリファクタ」は**撤回する**。 | 設計 | 決めたこと | 理由 | |---|---|---| | パス | ★**引数で受ける**★（モジュール先頭で固定しない） | 欠陥3 の直接の原因。テストできない部品は作らない | | 書き込み | ★**`.tmp` に書いて `fs.rename`**★ | rename はアトミック。落ちても旧ファイルが無傷で残る | | 破損時 | ★**`.bak` に退避 → 警告 → 空の値で継続**★ | 黙って捨てない。運用担当が書いた文章だから | | `.bak` の名前 | ★**タイムスタンプ付き**★ | **固定名だと2回目の破損で1回目の証拠が消える** | | ★`.bak` の作成に失敗したとき★ | ★**例外を投げる。空の値を返さない**★ | 空を返すと**次の保存で壊れたファイルが上書きされ復旧不能**になる。★**データが消えるより 500 のほうがまし**★ | | プロトタイプ汚染 | `Object.create(null)` + `hasOwnProperty` で移し替え | `ds-device-notes` はキーが `serial_number`（任意文字列）で `__proto__` が飛んでくる。`advice` は閉じた union なので問題が無かった | | ロック | ★**入れない**★ | 施設20件・実質1人。rename で「壊れたファイルが残る」ことは防げる。**利用者が増えたら部品側に入れる**（呼び出し側は無変更で済む） | | 警告の出し方 | ★**コールバックで注入**★。`json-store.ts` から `lib/logger` を import しない | `lib/logger/index.ts` は `@/lib/db` 経由で **fixtures 全体を引き込む**。`emitTo`（出力先を引数で受ける版）が同じ流儀の前例 | ★**ログの地雷**★ - ★**`logEvent("warn", ...)` は現状そのままでは呼べない**★。`lib/logger/events.ts:217-226` の `LogEvent` は**閉じた union で9種類しかなく**、「設定ストアの JSON が壊れた」に相当する型が無い。 **新イベント型の追加と `docs/logging-design.md:108-114` の一覧表の更新が必要** - ★**`note` / `notes` / `comment` / `memo` / `detail` はログのフィールド名に使えない**★。 `lib/logger/redact.ts:12-26` の禁止キーで、`enforceForbiddenFieldsPolicy`（`redact.ts:161-173`）が ★**非本番環境では例外を throw する**★。キー名は大文字小文字を無視した完全一致で、**ネストも再帰的に検査**される → 載せるのは**パスと理由だけ**。**壊れたファイルの中身は絶対に出さない** ★**実装は指示書J（`docs/handoff/指示書J_JSONストアの共通化と安全化.md`）で行う。指示書G より先に実行する。**★ **あわせて D-065 の「保存先の具体（SQLite か JSON か）は未決」を解消**: ★**JSON（`data/settings/ds-device-notes.json`）で確定**★。決定が指示書G と `docs/handoff.md` にしか 無い状態だったので、指示書J の段階4 で D-065 に追記させる。 #### 5. ★X-3 は「矛盾」ではなく「バッチの単位とサマリの単位の不一致」★ **ユーザーの問い**: 「8月の6週と9月の1週ができる形だと先程の月跨ぎルールと矛盾しますか？」 ★**矛盾しません。2行できるのが D-071 の当然の帰結です。**★ 月境界で週を分割するのだから、`08-30〜09-05` は 8月分と9月分の2つに割れる。 **矛盾するのは「1行しか作らない」場合**で、そのとき片方の期間が丸ごと欠ける。 ただし**定義の不一致は残る**ので、第5回 X-3 はその形に書き直した: > **バッチの対象定義**（`CLAUDE.md` §4.7「毎週日曜 6:00 に前週＝日曜〜土曜」）と > **サマリの格納単位**（月境界で分割した週）が**一致しない。** > 「前週」は7日でも、格納先は2行になる。 ### D-070 `[確定]` TeamWorks 第3回・第4回回答の反映（2026-09-07） > ★**この項は当初 D-068 として記録したが、D-068 / D-069 は F-04 レポート画面の実装が > 先に取得していたため D-070 に振り直した（2026-09-07）。**★ > `CLAUDE.md` の「追記直前に最終番号を確認する」を守らなかったために起きた衝突。 > **本ファイルは追記位置が時系列順でない**（D-070 が D-069 の後ろにある）ので、 > 番号を取るときは `grep -n "^### D-0" docs/decisions.md | sort` で確認すること。 #### 解決した項目 | # | 回答 | 帰結 | |---|---|---| | **1-1** | `control_error_histories.comment` は**アラート毎** | 当方の理解どおり。デバイス単位の備考とは別物（指示書G の前提が確定） | | **1-2 / D-4** | **`id` / `error_id` の型は、メーカーの仕様変更が無い限り変更しない。両方とも varchar のまま。現状は `error_id` を使う** | ★**`PrecheckItem.id` の `string` 化を安心して進められる**★。数値型への破壊的変更のリスクは当面なし | | **D-1** | `link_schedules.intervals` の書式が判明（下記） | 通信断のしきい値を当方でも再現できる | | **D-2** | 待機中・充電中は `robots.status`。**セキュリティ有効は `robots.status` とは無関係**。**ハンドルアップ以降は `robot_error_reports` から**。値は PUDU の「Common Open Interface Error Codes」が想定される | 6状態の取得元が確定。分類表は PUDU のエラーコード一覧から作る | | **D-3** | **`security_statuses.status = 0` の継続から当方で導出してよい** | D-067 の判断が追認された | | **A-2** | **histories テーブルは元テーブルの id を引き継ぐので AUTO_INCREMENT は不要** | ★**A-2 はクローズ**★。第1回の「auto_increment で採番」は「誰が採番するか＝DB」という趣旨で、histories は元テーブルの id を継承する設計 | #### `link_schedules.intervals` の書式（★確定★） ★**2026-09-07 訂正: 区切り文字は `,`（カンマ）です。当初この節に `|` と記録したのは誤りでした。**★ - **`,`（カンマ）区切りで24個の値。先頭が0時、最後尾が23時。値は報告間隔の秒数で 1〜3599** - 例: `10,10,10,10,10,10,10,30,30,30,30,30,30,30,30,30,30,30,30,15,15,15,15,15` → 0〜6時が10秒 / 7〜18時が30秒 / 19〜23時が15秒（**実際に分解して一致を確認**） - 文字列長は71字。**4桁×24＋カンマ23＝119字**なので `VarChar(120)` は この書式の最大長ぴったりに設計されている（桁数の裏付けにもなる） - **パースは純粋関数に閉じ込め、要素数が24でない場合の扱いをテストで固定すること** ★**この書式は最初から手元にありました。D-1 は問う必要がありませんでした。**★ `docs/handoff/analysis/table-definitions-03-schedule-summary.md:87` （テーブル定義書からの転記）に、次のとおり明記されています。 > 報告間隔を秒で指定(設定)する。1～3599で時間毎に設定する。先頭は0時、最後尾は23時を表す。 > 時間の区切りは,(カンマ)とする。 > 例) 毎時1分毎に報告する場合 60,60,…（24個） **教訓: TeamWorks に書式・型・値域を問う前に、まず `docs/handoff/analysis/table-definitions-*.md` を全文検索すること。** `CLAUDE.md` §5 のとおりテーブル定義書は**DBスキーマの正**であり、 その転記は既にリポジトリ内にあります。第3回・第4回の2往復は、この検索を省いたために発生しました。 #### ★通信断判定についての訂正★ 第3回・第4回の共有文書で「**D-1 が分からないと通信断の判定が実装できない**」と書いたが、 **これは過大評価だった。** 第2回 Q1-2 の回答のとおり、 **判定結果は TeamWorks 側のサーバーが `controls.status`（0:正常 / 1:異常）に格納する。** 当方は `controls.status` を読むだけでよく、`intervals` は **しきい値を画面に出したり、当方で判定を再現したりするための補助情報**である。 #### ★W-1 月跨ぎ週 — TeamWorks のルールが D-067 と食い違う（要判断）★ **TeamWorks の回答**: > 8/30, 8/31は8月第6週, 9/1〜9/5は9月第1週, 9/6〜9/12は9月第2週です. > ちなみに2026/8/1は1日だけですが8月第1週です. > 週の回数と月は明確に区分けします. その分集計結果に差が出ますが, そこは運用後の課題になります. **TeamWorks のルール = 週を月境界で分割する**（暦を実測して確認）: - 各月の**第1週は1日から始まり、最初の土曜日で終わる**（2026-08-01 は土曜なので1日だけで第1週） - 以降は日曜〜土曜 - **最終週は月末で切れる**（2026-08-30(日)〜08-31(月) が8月第6週） - ★**週の長さが1〜7日で変わる**★ **D-067 で決めたDFAのルール**（その月の1日を含む週がその月の第1週）と**食い違う**。 D-067 なら `2026-08-30〜09-05` は**まるごと9月第1週**だが、TeamWorks は**8月第6週と9月第1週に分割**する。 - ★**週次サマリを作るのは TeamWorks（D-023）で、DFA はそれを読む。**★ ルールが違うと、**確定週（サマリ由来）と当期（DFA集計）で週の定義が変わり、同じ画面で破綻する** - **→ TeamWorks のルールに合わせるのが必然**（要ユーザー判断。判断後に D-067 の該当項と `CLAUDE.md` §4.7、指示書F 段階1 を書き換えること） #### ★共有文書の送付・回答の記録（第1回〜第4回。すべて送付済み・回答済み）★ | 回 | 原稿 | 状態 | |---|---|---| | 第1回 | `TeamWorks実DDL照合結果_第1回_20260903.md` | **送付済み・回答済み**（D-061） | | 第2回 | `TeamWorks確認事項_第2回_20260903.md` | **送付済み・回答済み**（回答は `TeamWorks回答_第2回_20260903.md`。D-065） | | 第3回 | `TeamWorks確認事項_第3回_20260903.md` | **送付済み・回答済み**（1-1 / 1-2 / D-1〜D-4 の回答。本項） | | 第4回 | `TeamWorks確認事項_第4回_20260907.md` | **送付済み・回答済み**（A-1/A-3/B-3b 対応済み・A-2 不要・B-1/B-2 後日・**W-1**。本項） | ★**引き継ぎ文書は第4回を「完成済み・送付待ち」と書いていたが、実際には送付済み・回答済みだった。**★ **W-1 は第4回の文書にしか無い質問で、その回答が届いている**ことが証拠。 **D-061 と同じ記録漏れを繰り返している。** `CLAUDE.md` の運用どおり、 **送付時と回答受領時の両方で本台帳に記録すること。** なお **W-2（`error_type` の値一覧の作成依頼）は「PUDU の Common Open Interface Error Codes を参照」 という回答**なので、**一覧は先方が作らず、当方が PUDU の公開ドキュメントから作る**。 #### 継続（TeamWorks 待ち） | # | 内容 | 状態 | |---|---|---| | **A-1 / A-3 / B-3b** | 「**対応済み**」との回答 | ★**受領済みの `clean_watch_20260907.sql` には入っていない**（D-066 で照合済み）。**より新しいDDLを受領する必要がある**★ | | **B-1 / B-2** | 外部キー3本とインデックス。「**後で登録する**」 | 継続。当方の開発は止まらない | | **DB更新用アカウント** | 第1回から継続 | 継続 | ### D-073 `[確定]` 指示書H（月跨ぎ週をTeamWorks方式に統一）を実行した D-071（週は月境界で分割する。週番号1〜6）の実装。実行コミットは develop ブランチの一連のコミット （`85978b3` 段階0 / `8a00ed0` 段階1〜2 / `b09dc5f` 段階3 / `75804ef` 段階5）。 実行環境: Claude Code（Opusが監督、サブエージェント opus に段階ごと委譲。指示書F・指示書Dと同じ経路）。 #### 1. 段階0（`d-watch-api.yaml` / `lib/reports/query.ts` の週上限） - `d-watch-api.yaml` の `Week.maximum` を `5`→`6` に、`description` をD-071の説明に差し替え - `lib/reports/query.ts` の `WEEK_MAX` を `6` に。**`WEEK_MIN` は `1` のまま**（`week=0` は 「月の集計値」を表す予約値のため。`period=weekly` で `week=0` は引き続き422） これは **D-069 の「`week` の上限は5のまま」を上書きする。** D-069時点は「D-067ルールでは第6週は 発生しない」という前提での判断だったが、D-071では2020〜2040年の252か月中55か月で第6週が発生する （2026年は5月・8月）。 #### 2. 段階1〜2（`lib/format/period.ts` の帰属アルゴリズム） `weekOfMonth()` / `periodRange()` / `shiftPeriod()` を、週を月境界で分割する方式（D-071本文の実装式）に 差し替えた。`firstWeekStartMs()` を削除し、`firstDayOfWeek` / `lastDayOfMonth` / `weeksInMonth` / `addDays` を新設。`clampWeek()`（D-072。範囲外の週番号をその月の最大週へ丸める）を追加。 - `lib/format/__tests__/period.test.ts` と `lib/reports/__tests__/query.test.ts` の期待値表を、 指示書H本文が2020〜2040年の全252か月を総当たりして検証済みの新ルールに合わせて差し替えた （サブエージェントが実装前に独立したスクリプトで再検証し、指示書の数値と全件一致を確認済み） - **反映漏れなし**: 期待値が変わる6件（`2026-08-30`/`08-31`/`07-26`/`12-27`/`12-31`/`2025-12-28`）、 意図コメントが嘘になる3件、H-1〜H-6の追加テスト、`isCurrentPeriod`の書き換え必須2件、 すべて反映済み #### 3. 段階3（呼び出し側の影響確認） 事前調査エージェントがコードベース全体を監査し、影響箇所を確定した。 - ★**要修正は `components/features/reports/ReportsScreen.tsx` の3箇所のみ**★: 初期期間コメント（D-067→D-071）、週番号保持コメント（1〜5→1〜6）、`navigatePeriod`への `clampWeek()`導入（移動先の月に存在しない週番号を丸める。D-072） - **是正不要と確認したもの**（指示書H「影響範囲」表は6ファイル目として`ReportsScreen.tsx`が 抜けていたため、監査で表自体の不備も指摘済み）: - 「7」を使った日数算術は`lib/format/period.ts`内の4箇所のみで、すべて段階2の差し替え対象。 「合計÷7で1日あたり平均」を出している箇所はコードベース全体で0件 - 週番号5のハードコード（union型・UI列挙・追加バリデーション）は存在しない - `lib/judge/kpi.ts`のKPI4指標はすべて分母が実データ由来（清掃予定回数・面積・実施回数）で、 日数由来の分母は0件。週の長さが変わっても壊れない - `lib/i18n.ts`に`第N週`/`Week N`の対訳は0件（`periodLabel()`は意図的に`t()`を通さない設計。 6件目を足す必要なし） - `weekStart()`はproduction呼び出し元が0件（テストのみ）だが、月を見ない純粋関数なので 新ルールでも無関係。`periodRange('monthly',…)`と`periodLabel()`は無変更 #### 4. 段階5（`week` の内部表現を `number` に統一。月次は`0`） `ReportPeriodKey.week` / `ReportQuery.week` を `number | null` → `number` に変更した。 `parseReportQuery`は`period=monthly`のとき`week`を`null`ではなく`0`にする。 `lib/reports/query.ts`の`matchesPeriod`は`row.week === query.week`の単純比較に簡略化された （period分岐が不要になった）。`lib/format/period.ts`の4関数は`week ?? 1`→`week < 1 ? 1 : week`、 `week === null`→`week < 1`に統一。`lib/fixtures/reports.ts`の月次行2箇所を`week: 0`に。 - **`ReportsScreen.tsx`の`navigatePeriod`**: `setWeek(next.week ?? clampWeek(...))`は`??`が 常に発火しなくなる（`next.week`が必ずnumber）ため、`next.week === 0`（monthly）のときだけ `clampWeek(next.year, next.month, week)`、それ以外（weeklyの実週番号）は`next.week`をそのまま 使う形に修正した - **守った制約**: `WEEK_MIN=1`は不変（`period=weekly`で`week=0`は422のまま）。`d-watch-api.yaml`は 変更していない（API契約は「monthlyではweekを無視」のまま。`week=0`をクエリで要求する形にしない）。 `periodLabel("weekly", y, m, 0)`が「第0週」を出さず月だけのラベルに落ちることをテストで固定した - `prismaSource`実装時の注意（指示書H段階4の記録指示）: 月次を読むときは`WHERE week=0`、週次は `WHERE week=(1〜6)`。年次（`month=0 AND week=0`）はP1では読まないため、誤って拾わないよう **`month >= 1`を条件に入れること** #### 5. 実測値 - `npx tsc --noEmit`: エラー0 - `npm test -- --reporter=dot`: **19ファイル / 424テスト 全パス**（基準389から+35。指示書H着手前は 段階0完了時点で389→段階1-2で422→段階5で424） - `npm run lint`: 0 - `USE_FIXTURES=true npm run dev`で`/reports`・レポートAPI4本が200、`week=7`が422、`week=6`が200を 実測確認。★**完了条件7の「期間ナビ`‹`で2026年9月第1週→2026年8月第6週」はブラウザでの目視確認は 行っていない**（本セッションにGUIブラウザ操作手段が無いため）。かわりに `shiftPeriod("weekly",2026,9,1,-1)`が`{year:2026,month:8,week:6}`を返すことを `lib/format/__tests__/period.test.ts`の期待値表4で固定し、`curl`で`/api/reports/kpi`が `period=weekly&year=2026&month=8&week=6`で200を返すことを確認した★ #### 6. 前期比の性質に関する既知の注意（記録のみ。対処不要） 前期比`diff`は「今週(1〜2日のことがある) vs 先週(通常7日)」のように長さの違う期間の率を比較する ことになる。率（比）同士の比較なので計算は壊れないが、統計的には分母が小さい期間ほど振れやすい。 D-071を採る以上避けられず、TeamWorksのサマリ側も同じ性質を持つため実装での対処は不要と判断した。 `docs/handoff.md`・`.claude/commands/d-watch.md`の更新は本コミットとあわせて行った。 ### D-074 `[確定]` TeamWorks 追加回答（`error_type` の値一覧・`error_level`・当方の前提の承認）2026-09-08 #### 1. ★`robot_error_reports.error_type` に入る値（★原文のまま。改変しないこと★）★ Y-1 の回答。★**PascalCase の英字識別子**★で、コード番号でも日本語でもない。**24個**。 ``` MobileStationCleanWaterEmpty MobileStationNotConnected MobileStationNotPaired MobileStationSewageFull MobileStationWaterError PlanFailOverTime ReplanError TrashFull CanNotReach DockingPileFail EmergencyStop LostLocalization LowBatteryLevel MobileStationBaseError CleanWaterEmpty CleanSewageFull CleanAgentEmpty SecondaryPollutionNotify SecondaryPollutionCleaning SecondaryPollutionAbort NoticeElevatorError SkipTaskWhenStuckToAdmin NeedHelpWhenStuckToAdmin RobotHardwareErrorToAdmin ``` **`varchar(100)` の長さはこれで説明がつく**（最長 `SecondaryPollutionCleaning` = 26字だが余裕を持たせた形）。 #### 2. `robot_error_reports.error_level` に入る値（Y-2 の回答） `Fatal` / `Error` / `Warning` / `Event` の**4値**。ただし先方の注記: > ※Warning, Event はファイルに記録するけど, データベースに情報として格納しない予定. > 内容をみて後から判断するかもしれないけど. ★**DB で実際に見えるのは `Fatal` と `Error` の2つだけ**★（現時点の予定）。 **「後から判断するかもしれない」ので、コードは4値すべてを受け付ける形にすること。** **画面の重要度表示は Fatal / Error の2段階を前提に設計する。** #### 3. 当方が「この前提で実装します」と書いた項目は承認された > 上記以外で claude がそうする前提ですが, としているやつはそのままで OK です. | # | 承認された当方の前提 | |---|---| | ★**X-1**★ | ★**A案。`week` の上限は 6 として実装する**★ → **指示書H（D-073）の実装はやり直し不要。そのまま有効** | | **X-2** | `week=0` が月次 / `month=0 AND week=0` が年次。年次は P1 では読まない | | **X-3** | 週次バッチの「前週」は月をまたぐと2行になる | | **Y-3** | サマリ側の `error_type` は明細と同じ値域 | ★**X-1 が A で確定したので、指示書H の手戻りリスクは消えた。**★ #### 4. ★突き合わせ結果: 7分類のうち3つに対応する `error_type` が無い★ 当方の「エラー種別の内訳」は**7分類**だった（`d-watch-api.yaml:527` の説明文 / `:1205` の enum。★`:1160` は誤記で、`FacilityPerformance.status` の enum であり本件とは無関係。 D-088 で訂正★）。★この enum 自体が D-088（指示書K）で撤去され、以後は生値方針（D-077）に従う★。 受領した24値と突き合わせた結果: | 当方の分類 | 対応する `error_type` | 判定 | |---|---|---| | 緊急停止 | `EmergencyStop` | ✅ 一意に決まる | | LostLocation | `LostLocalization` | ✅ 一意に決まる | | 充電不足 | `LowBatteryLevel` | ✅ 一意に決まる | | ★**ハンドルアップ**★ | — | ❌ ★**24値のどれにも該当しない**★ | | ★**オフライン**★ | — | ❌ ★**該当しない**★（`MobileStationNotConnected` は集塵/給水ステーションの未接続でロボット自体ではない） | | ★**ブラシエラー**★ | — | ❌ ★**該当しない**★（`RobotHardwareErrorToAdmin` に含まれる可能性はあるが確認が要る） | | その他 | 残り21値 | ✅ | ★**ハンドルアップとオフラインは、7分類の中で最も件数が多い2つ**★ （`lib/fixtures/reports.ts:456-462` のモック値で 18件 と 12件。**合計56件中30件＝54%**）。 **この2つが「その他」に落ちると、エラー内訳の画面は半分が「その他」になる。** #### 5. ★ハンドルアップは二重に取れない恐れがある★ - **6状態**（`lib/types/index.ts:59` / `d-watch-api.yaml:988`）に「ハンドルアップ」がある - **アドバイス規則 B2「ハンドルアップ検知」**（`d-watch-api.yaml:274`）が依存している - D-2 の回答は「**ハンドルアップ以降は `robot_error_reports` から取得**」だった - ★**しかし 24値に該当が無く、さらに `Warning` は DB に格納されない予定**★ → ハンドルアップが Warning 相当なら、**そもそも DB に行が作られない** **この2点が重なると B2 は成立しない。次の照会で最優先に確認すること。** #### 6. オフラインは `error_type` ではなく別経路の可能性が高い **「オフライン」は「エラーが報告された」ではなく「報告が来ない」状態**なので、 `robot_error_reports` に行が立つ性質のものではない。 **`robots.status` か、最終報告時刻からの経過時間で導出するのが自然**。 第2回で受領した `robots.status` のコード表に該当があるかを先に確認し、 無ければ「どこから取るか」を照会すること。 #### ★第5回は送付済み・回答受領済みです（記録）★ **Y-1 / Y-2 は第5回の文書にしか無い質問で、その回答が返ってきました。** また「上記以外で claude がそうする前提ですが, としているやつはそのままで OK です」という回答は、 **第5回に書いた当方の前提（X-1 / X-2 / Y-1 / Y-3）を読んだうえでのもの**です。 → ★**第5回は送付され、回答を受領した**★（回答受領: **2026-09-08**。★**送付日は未確認**★）。 **`CLAUDE.md` の運用は「送付時と回答受領時の両方で記録する」です。** ★**第1回・第4回に続いて3回目の記録漏れ**★（いずれも送付側の記録が抜けた）。 **送付日が分かれば本項に追記すること。** #### ★第5回で「まだ残っている」もの（2026-09-08 時点）★ | # | 内容 | 状態 | |---|---|---| | X-1 / X-2 / X-3 / Y-3 | 当方の前提 | ★**承認済み**★ | | Y-1 / Y-2 | `error_type` / `error_level` の値 | ★**回答済み**★ | | **最新のDDL** | A-1 / A-3 / B-3b が受領済みDDLに無い | ★**未受領**★ | | **DB更新用アカウント** | 第1回から継続 | ★**未発行**★ | | **Z-1〜Z-4** | 下記。**まだ送っていない** | ★**未送付**★ | ★**指示書G / I はこのどれにも依存しません。**★ 依存するのは **`prismaSource`（最新DDL・参照用アカウント）** と **`error_type` の判定実装（Z-1 / Z-2）** だけです。 ★**そして `error_type` を参照している本番コードは現時点で0件です**★（`lib/` `app/` `components/` を 全文検索して確認）。**いま何も壊れていません。** 影響が実際に出るのは `prismaSource` で 実DBに繋いだときで、**それ自体が最新DDL・参照用アカウント待ち**です。 **この件を「ブロッカー」として扱わないこと。照会に1問足すだけで足ります。** #### ★8. PUDU の公開ドキュメントを実際に読んだ結果（2026-09-08）★ **ユーザー指摘「ここの清掃ロボットのステータス一覧は確認していますか」を受けて実際に閲覧した。** （`WebFetch` は SPA のシェルしか返さず、ブラウザでも1度目は `Application error`。 **2度目に読み込めた。** URL: `https://open.pudutech.com/en/cloud-api/rbhe3bagh5ecqb9zre45810t`） **このページには節が4つある。** | 節 | 中身 | 当方との関係 | |---|---|---| | Common Authentication Error Messages | HMAC / OAuth の認証エラー | 無関係 | | ★**Common Open Interface Error Codes**★ | ★**API 呼び出しの戻り値**★（`SUCCESS` / `PARAM_ERROR` / `CLEANBOT_ROBOT_OFFLINE` / `CLEANBOT_DB_ERROR` …） | ★**ロボットの故障種別ではない**★ | | ★**Cleaning Robot Status Codes**★ | ★**ロボットの状態コード**★（`Normal`=0 / `ChargingPile`=202 / `LostLoaction`=-200 / `Error`=-100 / `Notice`=-300 …） | ★**`robots.status` の正体**★ | | Data Center Error Codes | — | 未調査 | ##### ★発見1: いただいた24値は、このページに1件も存在しない★ `EmergencyStop` / `TrashFull` / `CanNotReach` / `LowBatteryLevel` / `RobotHardwareErrorToAdmin` など **11個を抽出して全文検索したが、ヒット0件。** ★**D-2 の「値は PUDU の『Common Open Interface Error Codes』が想定される」は、 節の指し先が違う。**★ その節は **API の戻り値**であって、`robot_error_reports.error_type` に 入るような故障種別ではない。**24値の出典は別のドキュメント**（ロボット側の通知/エラー列挙）と思われる。 ##### ★発見2: 「Handle」はページ全体で0件★ **ハンドルアップに当たる語が、状態コードにもエラーコードにも存在しない。** 近いのは **状態コード側**の次の3つ: | コード | 値 | 説明 | |---|---|---| | `ManualVacuuming` | **710** | Manual cleaning in progress（手押し清掃中） | | `ManualDockPile` | **505** | Manual docking | | `Exemption` | **770** | Manual exemption/guided exemption | ##### ~~★発見3: TeamWorks の `robots.status` 表は PUDU の現行仕様より古い★~~ ★**取り下げ**★ > ★**2026-09-08 訂正: この発見は誤りだった。**★ ユーザー回答: > 「**700番台は使用しないので欠落していて正しいです**」「**ハンドルアップは7xxでこないです**」 > → **表は古いのではなく、使わないコードを載せていないだけ。** > **`ManualVacuuming`(710) / `Exemption`(770) / `HandShiftBrush`(730) は候補にならない。** > **「表を最新にしてもらう」という照会案も取り下げる。** 以下は取り下げた内容（記録として残す）。 第2回でいただいた表（`TeamWorks回答_第2回_20260903.md:50-98`）は ★**46件**★ で、 - ★**7xx が丸ごと無い**★（`ManualVacuuming`=710 / `HandDrainSwedge`=720 / ★`HandShiftBrush`=730（手動ローラーブラシ交換）★ / `AppOTA`=740 / `Mapping`=750 / `Testing`=760 / `Exemption`=770） - ★**600〜604 を `Unknown.` としている**★が、PUDU では `PileLeave*`（離桩）と定義済み - `ManualDockPile`=505 / `QuickTest*`=800番台 / `VacuumHeatCleaning`=316,317 なども無い ★**ハンドルアップやブラシエラーに当たりそうなコードが、まさに欠けている 7xx にある。**★ ##### ★発見4: LostLocation は状態コード側にもある★ `LostLoaction`（-200。**PUDU 側のスペルミスもそのまま**）が状態コードに存在し、 **第2回の表にも `'-200'=>'Lost Loaction.'` として入っている。** → 当方の7分類「LostLocation」は ★**`robots.status = -200` から取れる**★可能性が高い。 `error_type` の `LostLocalization` と**二重に取れる**ので、どちらを正とするか決めが要る。 ##### ★発見5: 整合的な仮説（要確認）★ 状態コードの `Error`(-100) の説明は「**Error; see detail field for specifics**」、 `Notice`(-300) は「**Notice/warning**」。ここから次の対応が読める。 | `robots.status` | 意味 | 詳細の在り処 | DB 格納 | |---|---|---|---| | `-100` Error | 異常 | ★`robot_error_reports.error_type`（24値）★ | `Fatal` / `Error` → **格納される** | | `-300` Notice | 通知/警告 | 同上? | ★`Warning` / `Event` → **格納しない予定**★ | ★**ハンドルアップが `Notice`(-300) 相当なら、そもそも DB に行が作られない。**★ D-074 の「Warning 非格納」と符合し、24値に無いことも説明がつく。 ##### 照会の内容を、この発見にもとづいて差し替えること ★**2026-09-08 のユーザー回答で 1・2・3 は不要になった。残る照会は2件。**★ | # | 照会内容 | |---|---| | ★**質問1**★ | **LostLocation は `robots.status = -200`（`LostLoaction`）と `error_type = LostLocalization` の両方から取れる。どちらを正とするか** | | ★**質問2**★ | **オフラインは24値にも `robots.status` にも無い。`CLEANBOT_ROBOT_OFFLINE` は API の戻り値で用途が違う。★最終報告時刻からの導出という理解でよいか★** | **取り下げた照会案**: ①表の更新依頼（7xx は未使用で正しい）②ハンドルアップは 7xx か （7xx では来ないと確認済み）③24値の出典（表を受領したので不要）。 ★**ハンドルアップの取得元は未解明のまま。**★ 24値にも 7xx にも無い。 **次の照会に含めるかはユーザー判断を仰ぐこと。** #### 9. ★24値の対応表を作成した★ `docs/handoff/analysis/error-type-mapping.md`（2026-09-08）。 **24値すべてを当方の7分類に割り当てた表。実装の下敷きにすること。** | 区分 | 件数 | 内訳 | |---|---|---| | **対応が確定** | **3** | `EmergencyStop`→緊急停止 / `LostLocalization`→LostLocation / `LowBatteryLevel`→充電不足 | | **要確認** | **1** | `RobotHardwareErrorToAdmin`→ブラシエラー？ | | **「その他」へ** | **20** | ステーション系6 / タンク・消耗品系4 / 走行・経路系4 / 二次汚染系3 / 管理者通知系3 | | ★**対応値が無い分類**★ | **2** | ★**ハンドルアップ**（取得元未解明）/ **オフライン**（導出と思われる）★ | ★**注意した点**★ - `MobileStationNotConnected` を「オフライン」に**割り当てない**（ステーションの未接続であって ロボットのオフラインではない） - `DockingPileFail` を「充電不足」に**寄せない**（ドッキング失敗であって残量低下ではない） - ★**`Notice` / `Notify` / `*ToAdmin` は「通知」寄りなので、`Warning`/`Event` 非格納の方針により DB に来ない可能性がある**★。「その他」20件のうち実際に来る値はもっと少ないかもしれない - ★**24値の「意味」は当方が識別子名から推測したもの**★。PUDU の公開ドキュメントに この24値は載っておらず、正式な説明は未確認 #### ★10. 2026-09-08 のユーザー回答2件（ハードウェア異常 / ハンドルアップ）★ | # | 回答 | 帰結 | |---|---|---| | **1** | ★**「ブラシエラーなどのハードウェアエラーは全て同じエラーメッセージやコードで返ってきます」**★ | **Z-2 は解決。`RobotHardwareErrorToAdmin` に含まれるが、内訳は区別できない。**★**7分類の「ブラシエラー」がそのままでは埋められない**★ | | **2** | ★**「ハンドルアップは Handrail Lifted がそうだと思いますが、一旦その他として丸め込んでください」**★ | ★**ハンドルアップは当面「その他」へ。実装を止めない**★ | ##### ★「ブラシエラー」分類の扱いが未判断★ | 案 | 内容 | |---|---| | ★**A（推奨）**★ | 分類名を**「ブラシエラー」→「ハードウェア異常」**に変える。`d-watch-api.yaml:527` / `:1160` とモックの文言変更が要る | | **B** | 「その他」に寄せ、分類を出さない | | ★**C（採らない）**★ | `RobotHardwareErrorToAdmin` を「ブラシエラー」と表示する。★**モーター異常を「ブラシエラー」と出すことになり、現場に誤った指示を出す**★ | **ユーザー判断を仰ぐこと。C だけは選ばない。** ##### ★`Handrail Lifted` には空白が入っている★ 24値はすべて PascalCase（`EmergencyStop` など）だが、`Handrail Lifted` は**空白入り**。 → ★**`error_type` の値の形が1種類ではない可能性がある**★。 **完全一致で対応表を引く実装だと、空白入りの値を取りこぼす。** 当面は「その他」なので実害は無いが、**将来ハンドルアップを分類するときに効く。** ##### 残る照会は2件だけになった | # | 内容 | |---|---| | ★**質問1**★ | LostLocation は `robots.status = -200` と `error_type = LostLocalization` のどちらを正とするか | | ★**質問2**★ | オフラインは最終報告時刻からの導出という理解でよいか | **Z-2（ブラシエラーの区別）は回答済みのため取り下げ。** **ハンドルアップの取得元も、当面「その他」とするため照会不要。** #### ★11. 要件定義書の所在と位置づけ（2026-09-08）★ ##### 共有された URL は別文書だった ユーザーから共有された Google Docs は ★**「DIGILOG_要件定義書_v2.1」**★ （Salesforce・Googleカレンダー連携の**営業判断支援システム**。2026-07-23 作成）で、 **清掃ロボット・D-Watch・PUDU・TeamWorks への言及は1件も無い。別プロダクトの文書。** ##### ★祖先文書を発見した（`P1 v2.2` ではない）★ Drive を検索して ★**「清掃ロボット（CC1）稼働監視システム 要件定義書」**★ を発見。 （`13nG-Wj8O-zbaFv9nwyD-s1BIKnXZwYdc6Ztlq-z1edw` / daigo@dfarobotics.com / **最終更新 2025-12-01**）。**`CLAUDE.md` §5 が指す `要件定義書 P1 v2.2` とは別で、その前身。** ★**D-Watch 開発（2026-09）の9か月前、TeamWorks の DB が存在する前の文書。**★ ##### ★この文書が、いま議論している論点の由来だった★ | 現在の仕様 | 祖先文書の記述 | |---|---| | **事前チェック（60分前 / 30分前）** | 「第1回ステータスチェック（稼働開始60分前）」「第2回（30分前）」**そのもの** | | **完了率の閾値** | 「タスク完了率 **70%未満** の機体に『要改善』フラグ」← **現在の 90/70/10 の祖先** | | **R4（3日以上連続 → オンサイト）** | 「3日連続で経路ブロックが5回以上 → 要検討（マップ修正提案）」 | | ★**ハンドルアップ**★ | ★**「ハンドルが下までしっかりと下がっていること」**★ が60分前の「正常な待機状態」の条件。**つまりハンドルアップは、PUDU のエラーコードではなく「現場の準備状態のチェック項目」として生まれた概念** | | ★**ブラシエラー**★ | ★**「『ブラシチャンバー（ブラシ室）』に関連するエラー警告」は「通知対象外」として実装することを推奨**★／「ただし、『ブラシチャンバー』のエラーは無視してよい」 | ##### ★★ブラシエラーは「無視してよい」と要件に書かれていた★★ **7分類の「ブラシエラー」を独立分類として出すのは、祖先文書の方針と逆である。** 祖先文書は**過剰な通知を防ぐため除外対象**として明示していた。 → ★**「ブラシエラー」分類は落とす方向が、要件の意図に沿う。**★ D-074 の項10 で挙げた3案のうち、★**B（その他へ寄せ、分類を出さない）が要件と整合する**★。 **A（ハードウェア異常へ改称）も可**だが、**C（ブラシエラーとして表示）は要件にも反する。** ##### ハンドルアップが `error_type` に無いことの説明がついた **ハンドルアップは「PUDU が報告するエラー」ではなく「人が目視で確認する準備状態」**として 定義されていた。**24値に無いのは自然。** → **取得できないなら、6状態から落とすか、事前チェックの目視項目として残すかの判断になる。** ##### ★`要件定義書 P1 v2.2` は依然として見つかっていない★ Drive を `title contains '要件定義'` で検索した結果は4件で、D-Watch のものは上記の祖先文書のみ。 ★**`CLAUDE.md` §5 が「全体要件・Phase A/B/C の線引きの正」としている文書に、当方は到達できていない。**★ **ユーザーに正しい所在を確認すること。** ##### ★ユーザーからの位置づけの指示（重要）★ > **「これはあくまで DFA 側の想定なので teamwork 側の DB との整合性が取れていない可能性があります。 > 取得する数値の型などは DB を正としています」** ★**要件定義書は「何を作るか」の正であって、「型・値・DB整合」の正ではない。**★ **型・値域・カラム名は実DDL（`prisma db pull` の結果）が正**（D-057 の 「今後は定義書ではなく実際のスキーマ文（DDL）を正とする」と同じ方針）。 **`CLAUDE.md` §5 の資料一覧を読むときはこの但し書きを併せて適用すること。** #### ★12. 要件定義書 P1 v2.2 を入手・閲覧した（2026-09-08）★ ★**「D-Watch / D-Security 要件定義書 (P1) 版数 2.2（ドラフト）」**★ （Drive: `1thSYHk-ODCht-K4WqFlCP-Es2OyAz4Wj` / 作成 2026-03-17 / DFA Robotics）。 **`CLAUDE.md` §5 が指す文書。ようやく到達できた。** ##### ★問い「ブラシエラーやモーターエラーが DB から返却されると要件定義にあるか」→ 無い★ | 事実 | 出典 | |---|---| | ★**ブラシエラーは Phase B の例示としてのみ登場**★ | 5.1.6「**Phase B（P1後半〜P2）**: エラーコード別ルール追加（ハンドルアップ/**ブラシエラー**/LostLocation/オフライン等）」 | | ~~**Phase A（P1）に含まれるのは R1〜R4 だけ**~~ ★**訂正**★ | 5.1.6 は「Phase A（P1）: …最低限ルール4本（R1〜R4）」と書くが、★**D-039 で B1〜B3 も P1 に含めると決定済み。実装も従っている。要件定義書ではなく D-039 が正**★ | | **「エラー種別の内訳」は P1 にあるが、分類の中身は書かれていない** | 5.1.5「新セクション: …**エラー種別の内訳（種別ごとの件数＋プログレスバー）**」← ★**7分類の列挙は無い**★ | | ★**「モーターエラー」は要件定義書に一度も出てこない**★ | 全文検索。**当方が推測で持ち出した語だった** | ★**結論: ブラシエラーを P1 の分類として出す根拠は無い。**★ D-074 項10 の3案は ★**B（その他へ寄せ、P1 では分類を出さない）が整合**★。 ★**ただし B1〜B3 とは別の話なので混同しないこと（2026-09-08 訂正）。**★ **D-039 が P1 に入れたのは B1（マップ更新）/ B2（ハンドルアップ検知）/ B3（オフライン検知）の 3ルールだけ**で、**ブラシエラーは含まれない**。D-039 自身が 「**エラーコード別ルールの本格展開は引き続き Phase B**」と書いており、 ブラシエラーはそちら側に残る。 ##### ★確認事項#2 が「確認済み」で、質問1 の答えになっている★ > **異常(-100)＝エラー全般、異常(-200)＝LostLocation（位置喪失）。 > 出典: PUDU Open Platform の清掃ロボット状態コード** — 状態: ★**確認済み**★ ★**LostLocation は `robots.status = -200` が正。**★ 項8 の発見4（PUDU の状態コードに `LostLoaction`(-200) がある）と一致する。**質問1（-200 と `LostLocalization` のどちら）は 要件定義書で既に決着していた。照会不要。** ##### ★確認事項#7 に オフライン・緊急停止の取得元が書かれている（調査中）★ > **事前チェック用ST: Callback Notification（AbnormalRealtimeNotification、 > ★RobotOnlineOfflineStatusChange★、★EmergencyStopRecover★、RobotWorkStatus） > + GetCleaningRobotStatusDetail で取得見込み。PUDUサポートへ問合せ中、検証待ち** — 状態: **調査中** - ★**オフラインは `RobotOnlineOfflineStatusChange`（コールバック通知）**★。 `error_type` ではない。**質問2 の方向性が裏付けられた** - **緊急停止は `EmergencyStopRecover`** - ★**ただし「PUDUサポートへ問合せ中、検証待ち」のまま**★ ##### ★要件定義書自身が「未確認」と書いている（これが今の宿題の正体）★ 5.1.7 の要確認: > **上記の清掃開始不可状態がそれぞれ Pudu Cloud API のどのフィールドに対応するか未確認。 > 取得可能な状態種別の一覧をエンジニアが確認の上、検知対象を確定させること（確認事項#7）** ★**「6状態がどこから取れるか」は、要件定義の時点から未解決の宿題だった。**★ **当方が新たに見つけた問題ではなく、要件定義書が積み残したものを今引き当てている。** ##### 6状態の出典が判明した（5.1.7 の「清掃開始不可状態の例」） > **充電中 / ハンドルアップ（物理的にハンドルが上がったまま放置）/ 緊急停止ボタン / > ロスト / オフライン / デバステ（ホーム画面以外の状態でスタート不可）** ★**要件定義書の6つと、実装の6状態（待機中/充電中/ハンドルアップ/緊急停止/オフライン/ セキュリティ有効）は一致していない。**★ 要件側には**ロスト**と**デバステ**があり、 実装側には**待機中**と**セキュリティ有効**がある。**この差異は未整理。** ##### その他、実装と突き合わせるべき記述 | 要件定義書 | 実装の状況 | |---|---| | 3.2「開発言語: **PHP 8系 / Laravel 12系**」 | ★**実装は Next.js + TypeScript**★（D-046）。**要件定義書が古い**。※本書は DFA 側の想定で、DB・実装の正ではない（ユーザー指示） | | 6.3「アクセス制限（**IP制限**、アプリケーション権限）」 | 指示書I の方針（`proxy.ts` + cookie + IP制限）と整合 | | 5.1.6「閾値（90%/70%/10%）は**システム設定で変更可能**」 | `lib/config/` で外出し済み。整合 | | 5.3.1「D-Sデバイスの**トークン有効期限の表示**」／5.3.2「トークン期限に**残日数列**」 | ★**`CLAUDE.md` §7 で「トークン期限/残日数の実装」は禁止**★。**要件定義書と現行方針が食い違う**（仕様から除外済みとの整理） | | 6.2 データ保持ポリシー（清掃結果2年 / 操作ログ3年 等） | ★**後回し（2026-09-08 ユーザー判断）**★。未実装だが **P1 の完成を妨げない**ので、実装が一巡してから着手する | #### 7. 次の照会に載せること | # | 内容 | |---|---| > ★**2026-09-08 訂正**★: 当初 Z-1 を「ハンドルアップの取得元は何か」と書いたのは**誤り**。 > **取得元は D-2 で回答済み**（「**ハンドルアップ以降は `robot_error_reports` から**」）。 > 残っているのは「**その `error_type` の値一覧に該当が無い**」という1点だけなので、 > **Z-1 と Z-3 を1問に統合し、聞く内容を絞った。** | ★**Z-1**★ | ★**ハンドルアップとオフラインは `error_type` に現れますか。24値は網羅ですか。**★
現れない場合、この2つは**どこから判定するか**（`robots.status` / 最終報告時刻からの導出 など）。
**背景**: D-2 で「ハンドルアップ以降は `robot_error_reports` から」とご回答いただきましたが、**いただいた24値に該当が見当たりません**。
★**なお「ハンドルアップ」は状態、「オフライン」は報告が来ないこと**なので、そもそもエラー行にならない設計であっても不自然ではありません。矛盾の指摘ではなく確認です★ | | **Z-2** | **ブラシエラー**は `RobotHardwareErrorToAdmin` に含まれるか。含まれるなら**内訳を区別する手段があるか**（`error_detail`?） | | ★**Z-4**★ | ★**参照用アカウント（全テーブル SELECT のみ）の発行**★。`CLAUDE.md:82` にある2種類のうち、**第1回〜第5回で一度も依頼していない**。これがあれば値の確認を当方で行える | **Y-1 / Y-2 は解決。第5回の4節は Z-1〜Z-3 に置き換えること。** --- ### D-075 `[確定]` 指示書J（JSONストアの共通化と安全化）を実行した **設計そのものは D-072 #8 で決定済み**（`.bak` のタイムスタンプ命名 / `.bak` 退避失敗時に例外を 投げる判断 / ロックを入れない理由 / `lib/logger` を import しない理由は、いずれも D-072 を参照）。 本項は**実行結果の記録**。 #### 経緯: 指示書G の「やらないこと」を上書きした `docs/handoff/指示書G_D-Secログの備考入力と2状態化.md` は当初「`advice.ts` のリファクタは 備考の実装とは別件」としていたが、**指示書G自身が `advice.ts` を「ひな型にする」と指示**していたため、 放置すると `advice.ts` の3欠陥（壊れたJSONを黙って捨てる／非アトミック書き込み／パス固定でテスト不可）が 2つ目のストア（`ds-device-notes.ts`）へそのまま複製される。**この判断を撤回し、指示書J で先に `lib/settings/json-store.ts` を作って `advice.ts` をそこへ載せ替えた**（D-072 #8 のとおり）。 #### 実装した内容 | ファイル | 内容 | |---|---| | `lib/logger/events.ts` | `settings.store_corrupt` イベント（`SettingsStoreCorruptLogEvent`）を追加。フィールドは `file_path` / `backup_path` / `reason` のみ（`route` / `method` は任意。`advice.ts` は複数ルートから共有され、呼び出し元を公開シグネチャを変えずには特定できないため） | | `docs/logging-design.md` | イベント一覧表（§3）に `settings.store_corrupt` の行を追記 | | `lib/settings/json-store.ts`（新規） | `createJsonStore({filePath, empty, onWarn})` を実装。`read()` は ENOENT のみ空値・それ以外の読み取りエラーは再送出（「読めないのに未編集」と誤認して次の保存で消さないため）。JSON破損時は `.bak`（タイムスタンプ付き）へ `rename` 退避 → `onWarn` → 空値を返す。**退避自体が失敗したら例外を投げる**（空値を返すと次の `write()` で壊れたファイルが上書きされ復旧不能になるため。「データが消えるより例外の方がまし」）。`write()` は `.tmp` に書いてから `rename` でアトミックに差し替え、失敗時は `.tmp` を後始末する。プロトタイプ汚染はパース結果を直接返さず `empty()`（`Object.create(null)` 契約）へ1キーずつ複製することで防ぐ。`lib/logger` は import しない（`onWarn` コールバックで注入） | | `lib/settings/advice.ts` | `readOverrides` / `writeOverrides`（自前 `fs` 呼び出し）を `createJsonStore` に置き換え。保存先パスはモジュール先頭の `const` ではなく遅延生成 + `__setAdviceStoreForTesting()`（テスト専用の差し替え口）に変更。`loadAdviceRules` / `saveAdviceRule` / `resetAdviceRule` の公開シグネチャは無変更（呼び出し元2箇所も無変更で通ることを確認済み）。`resetAdviceRule` に `saveAdviceRule` と同じ未知ID検査（`assertKnownRule`）を追加し非対称を解消。破損検知は `logEvent("warn", settingsStoreCorruptEvent)` に配線 | | `lib/settings/__tests__/json-store.test.ts`（新規） | **このリポジトリ初の「実際にファイルを読み書きするテスト」**（`fs.mkdtemp` 使用、`fs` はモックしない）。`.bak` 退避失敗の再現は `vi.useFakeTimers` で時計を固定し、`.bak` と同名のディレクトリを事前に作ることで `rename` を実際に失敗させている（モックではなく実際の OS 挙動） | | `lib/settings/__tests__/advice.test.ts`（新規） | `@/lib/logger` のみモックし、`fs` は実ファイルで検証。破損直後に保存しても `.bak` の中身が失われないことを固定 | #### ログの禁止フィールドについて（実装時に確認した事実） `lib/logger/redact.ts` の `FORBIDDEN_PII_FIELDS` は `note` / `notes` / `comment` / `memo` / `detail` を 含み、`enforceForbiddenFieldsPolicy` は非本番環境でこれらのキー名（大文字小文字を無視した完全一致、 ネストも再帰検査）をログに渡すと例外を投げる。`settings.store_corrupt` のフィールド名 （`file_path` / `backup_path` / `reason`）はいずれにも該当しないことを確認済み。 #### 実測値（このメモを書いた時点。段階0〜3完了、段階4着手前） - `npx tsc --noEmit`: エラー0 - `npm test`: **21ファイル / 447テスト 全パス**（段階前の424から、段階0で±0・段階1-2で+13・段階3で+10） - `npm run lint`: 0 #### 実行環境について 作業自体は Cursor の実装作業ではなく、Claude Code（Sonnet 5。監督役）が opus サブエージェントに 段階ごと（段階0・段階1-2・段階3）を委譲する形で実行した（指示書D/F/Hと同じ経路）。監督側は各段階の 成果物を自分で読み、`tsc --noEmit` / `npm test` を再実行してから commit している（サブエージェントの 報告を鵜呑みにしない運用）。ユーザーから `docs/handoff/指示書J_...md` の内容が直接メッセージとして 渡されており、`.claude/commands/d-watch.md` の「指示書*.md を指して実行してと言われたら実装者」に該当する。 ★**着手時点で `docs/handoff.md` 追記15（第5回回答待ちで停止）は D-074（2026-09-08）により 解消済みだった**★（X-1〜X-3・Y-1〜Y-3 すべて回答済み。X-1 はA案で確定し指示書Hのやり直し不要）。 ただし `docs/handoff.md` に追記16としてまだ記録されておらず、次のセッションが古い「停止中」の 記述だけを見て混乱しないよう、段階4で追記する。 --- ### D-076 `[確定]` 指示書G（D-Secログの備考入力と2状態化）を実行した **保存先（JSON）・共通部品（`json-store.ts`）の設計自体は D-072 #8 / D-075 で決定・実装済み**。 本項は**指示書Gの実行結果の記録**（段階0〜6）。 #### 実装した内容 | 段階 | 内容 | |---|---| | 段階0 | `DsConnectionStatus` を `"ok" \| "disconnected" \| "error"` → **`"ok" \| "error"`** に変更（D-065: `controls.status` は0/1の2値で、異常＝生死報告なし＝通信断と同一）。型変更を起点に、YAML・一覧のフィルタ/ソート/サマリ・画面表示・fixtures・テストを2状態に統一。F-07 `DsAlertType`（`"security_off" \| "disconnected"`。別概念）は無変更 | | 段階1 | `d-watch-api.yaml` に `PATCH /ds-devices/{serial_number}/note` を追加。200は保存後の値をエコーバック、404は`NotFound`、422は`ValidationError`を`$ref`。`DsDevice.note`の`example`を検知側文言に見えていた`"セキュリティ復帰失敗"`から運用メモらしい例に差し替え | | 段階2 | `lib/settings/ds-device-notes.ts`（新規）。`json-store.ts`を薄く包み、`serial_number → 備考`を保存。`advice.ts`と同じパターン（遅延生成ストア＋テスト専用差し替え関数）でパスをテストから差し替え可能にする。空文字・前後空白のみの入力はトリム後にキーごと削除しnullを返す | | 段階3 | `app/api/ds-devices/[serial_number]/note/route.ts`（新規）。`db.dsDevices()`で実在確認（無ければ404）、文字数上限（`DEVICE_NOTE_MAX_LENGTH=200`。`lib/config`に外出し）超過は422+`details`、保存失敗は500（`errorPayload`を`logApiError`とレスポンスの両方に同一オブジェクトで渡す） | | 段階4 | `app/api/ds-devices/route.ts`のGETで、`db.dsDevices()`の`note`を独自ストアの値で上書き（ストアに値があれば優先、無ければ元の値）。`readDeviceNotes()`の失敗は`db.dsDevices()`と同じtry節に含め、一覧全体を500にする（縮退させて備考なしで返すと、運用担当が保存済みの文言を空欄と誤認し上書き＝実質削除しかねないため） | | 段階5 | `DsLogScreen.tsx`の「備考」列をセル内インライン編集に。クリックで`textarea`→`onBlur`で確定→`PATCH`。保存後は全件再取得（`fetchDevices()`）ではなく該当1行のみ`setItems`で差し替え（全件再取得は`loading`状態を経由し編集位置を見失うため）。値が変わっていなければPATCHを送らない。`textarea`に`font-family: inherit`を明示（`globals.css`の`inherit`は`button/input/select`のみでtextareaは対象外のため、指定しないと日本語がブラウザ既定フォントに落ちる） | | 段階6 | `lib/fixtures/ds-devices.ts`の`note`（`"セキュリティ復帰失敗"`等、検知側の文言に見えるもの）を運用担当が書きそうな文言に差し替え。`null`/非`null`の比率は維持 | #### ★追記（2026-09-08）: ブラウザでの目視確認を実施した★ **申し送られていた「次にブラウザ操作が可能なセッションで実施」を完了した。** | 完了条件 | 結果 | |---|---| | **4. 画面から備考を入力・保存し、リロード後も残る** | ★**確認済み**★。`/ds-logs` で備考セルをクリック → 入力欄が開く → 文字入力 → **blur で `PATCH /api/ds-devices/DS-001/note` → 200 OK** → **フルリロード後も残存**。★**別タブを新規に開いても残存**★（二重確認） | | **4. `data/settings/ds-device-notes.json` が生成される** | ★**確認済み**★。`{"DS-001": "…"}` が実際に書かれた | | **5. 空文字で保存して消える** | ★**API 実装とソースで確認。ブラウザのクリック操作は未完**★（下記） | | **段階0 の2状態化** | ★**確認済み**★。一覧のフィルタが **全て / 異常 / 正常** の3ボタンで、「通信断」が消えている | ★**完了条件5 について（正直な記録）**★ **ブラウザペインの viewport が 0×0 に落ちる不具合が3回発生し、クリックが届かなくなったため、 「空にする」操作の目視クリック確認だけ完了できなかった。** 代わりに次の2点で確認した。 1. ★**ソース確認**★: `DsLogScreen.tsx` の `commitNote` は `if (note === (device.note ?? "")) return;` で**値が変わっていないときだけ**送信を省く。 **空にする操作は「変更あり」なので PATCH は必ず飛ぶ** 2. **API 確認**（前セッションの curl）: 空文字 → `note: null` が返り、ファイルからキーが消える **当初「空にしても PATCH が飛ばない」ように見えたのは、ペインが壊れていて入力欄が 開いていなかったためで、実装の問題ではない。** **後始末**: テストで投入した備考は削除し、`data/settings/ds-device-notes.json` を `{}` に戻した （`/data` は `.gitignore` 対象でコミットされない）。 #### 実機確認（`npm run dev` + `curl`。★このセッションではブラウザ目視確認も追加実施★） このセッションにはブラウザ操作手段（`chromium-cli`等）が無かったため、`USE_FIXTURES=true`で 開発サーバーを起動し、実際のHTTPリクエストで確認した。 - `GET /ds-logs` → 200 - `PATCH /ds-devices/DS-001/note`（UTF-8ファイル経由。シェルの日本語インライン引数はgit-bash側の 文字化けで正しく送れなかったため、`--data-binary @file`で確認した）→ 200、 `data/settings/ds-device-notes.json`が新規生成され、保存した文言がそのまま入ることを確認 - 2件目（DS-002）を保存 → 1件目（DS-001）が消えないこと（部分更新）を確認 - 空文字で保存 → `note: null`が返り、ファイルからキーが消えることを確認 - 存在しないシリアル番号 → 404、`note`が数値 → 422 `validation_failed`、 201文字 → 422 `validation_failed`（`details.note`にメッセージ）をそれぞれ確認 - サーバーログにエラー・例外なし - ★次にブラウザ操作が可能なセッションで、実際にクリック→入力→blurの一連の目視確認を 一度行うことを推奨する★（指示書H完了時と同じ制約） #### 実測値（このメモを書いた時点） - `npx tsc --noEmit`: エラー0 - `npm test`: **22ファイル / 461テスト 全パス**（指示書J完了時447 → 段階6で+2 → 段階2で+14。 基準値461は指示書Gの完了条件が求める「447から減っていない」を満たす） - `npm run lint`: 0 #### 実行環境について 指示書Jと同じく、Claude Code（Sonnet 5。監督役）が opus サブエージェントに段階ごと （段階0単独 → 段階1/2/6並列 → 段階3/4並列 → 段階5）で委譲する形で実行した。 監督側は各段階の成果物を自分で読み、`tsc --noEmit` / `npm test` を再実行してから commit している。 ★**並行して別セッション（`Co-Authored-By: Claude Opus 5`。TeamWorksのerror_type関連のdocs作業）が 同じ作業ディレクトリで動いており、段階3・段階4の未コミット分がそのセッションの `docs: Z-1を訂正して...`（`b564574`）というコミットに巻き込まれた。**★ ユーザーに確認したところ「段階3・4はコミット済み」で問題ないとの回答を得たため、 コミットの分割・メッセージ訂正は行っていない。ファイルの中身自体に欠落・破損は無い （`tsc`/`test`で確認済み）。**同一作業ディレクトリを2セッションが同時に触ると こうした巻き込みが起きる**ことの実例として記録する。 --- ### D-077 `[確定]` 2026-09-08 のユーザー判断4件（エラー値の非変換 / D-Sec 2状態 / XFF追記） **ユーザー指示（原文）**: > ロボットのエラーについては現状PuduAPIから何が返ってくるのか不明なので、DBから来た文字列をそのまま変換せずに記載する形で実装してください > LostLocation等の-200で想定しているものについても同様です > D-security制御盤のエラーについては正常か正常でないか、をいったん判断するだけで良いです > ★ロードバランサが X-Forwarded-For を追記するか上書きするか★はnginxで追記して各サービスに割り振ります #### 1. ★ロボットのエラー種別は変換せず、DBの値をそのまま表示する★ **理由**: Pudu API から実際に何が返るか不明なため、推測でマッピングしない （`CLAUDE.md` §7「仕様が不明な箇所を推測で実装すること」の禁止に合致）。 ★**D-057 / D-067 で決めていた「サーバ側で7分類に寄せる／未知の値は `other` に寄せる」方針は破棄**★。 `docs/handoff/analysis/error-type-mapping.md` の24値→7分類の対応表は **実装の下敷きではなくなり、参考資料に降格**する。 **影響箇所（調査済みの実測）**: | 箇所 | 内容 | |---|---| | `lib/types/index.ts:177-185` | `ErrorType` union（7値）を廃止するか `string` に緩める。★**すべての起点**★ | | `lib/types/index.ts:187-189` | `ErrorBreakdownItem.type: ErrorType` | | `d-watch-api.yaml:1192` | ★**唯一の実 enum**★ `[handle_up, lost_location, offline, brush_error, emergency_stop, low_battery, other]`。enum を外す | | `d-watch-api.yaml:1194-1197` | description が「サーバ側で本7分類に寄せる。未知の値は other(D-057)」と**方針の逆**を明記している | | `d-watch-api.yaml:527` | `/reports/error-breakdown` の description の「7分類」文言 | | ★`d-watch-api.yaml:531`★ | 「7分類固定でページングの余地がなく常に7件または0件」が ★**`meta` を返さない根拠**★ になっている。生値なら件数が固定されないため ★**この根拠が崩れる**★（0〜N件）。`app/api/reports/error-breakdown/route.ts:2, 31-32` にも同じコメント | | `lib/reports/query.ts:41-49, 270-277` | `ERROR_TYPE_ORDER` による同値時の安定ソート。生値では `indexOf` が全て `-1` になり ★**ソートが無意味化**★ | | `components/features/reports/ReportsScreen.tsx:56-64, 439-441` | `Record` が型エラー。未知キーで `undefined` が `ProgressBar` に渡る | | `lib/fixtures/reports.ts:455-463` | `errorCounts` の7件 | | `lib/fixtures/__tests__/reports.test.ts:60-73, 292-300` | `satisfies Record` によるコンパイル時の7種網羅強制が崩れる | | `lib/reports/__tests__/query.test.ts:504-516` | 「件数同値なら `ErrorType` の定義順」の期待値 | | ★`lib/db/index.ts:174-175`★ | `prismaSource.errorBreakdown()` は `notImplemented` のまま＝★**変換ロジックはまだ1行も書かれていない。手戻りが最小のタイミング**★ | | `d-watch-api.yaml:1198` | `label`（自由文字列）は**影響なし**。★**生値の受け皿がすでにある**★ | ★**既知の行番号の誤り**★: `docs/decisions.md:1350` と `docs/handoff/analysis/error-type-mapping.md:11` が enum の位置を `d-watch-api.yaml:1160` と 書いているが、★**実体は `:1192`**★（`:1160` は `ContinuousProblem.consecutive_problem_days`）。 この2箇所も併せて直すこと。 #### 2. `robots.status` の -200 等も同様に変換しない - ★**D-070 で「異常(-200)＝LostLocation」と確定していたが、この変換は実装しない**★。 該当は `docs/decisions.md:1643-1647`: > ★**LostLocation は `robots.status = -200` が正。**★ 項8 の発見4（PUDU の状態コードに > `LostLoaction`(-200) がある）と一致する。 **「-200 が LostLocation である」という事実認識は取り下げない。取り下げるのは「画面に出す前に 日本語やコード名へ変換する」実装方針だけ**である。 - 実装コードに `-200` を扱う分岐は ★**1つも存在しない**★（`lib/` `app/` `components/` を `grep -- "-200"` で調査済み。ヒット0件）。したがって**取り下げのコストはゼロ** - `docs/handoff/TeamWorks回答_第2回_20260903.md:50-97` の `robots.status` コード表による 日本語変換も**行わない** - ★**併せて訂正**★: 同コード表は ★**46件**★（`-300` 〜 `999`。★`103` が欠番★で `102` の次が `104`）。 本決定の起票時に「47件」と数えていたが、実測は46件 #### 3. ★帰結 — B2 / B3 が実データで発火しなくなる（★要判断★）★ - `lib/judge/advice.ts:80-82, 83-85` が ★**日本語文字列の完全一致**★ で発火する: `status1h === "ハンドルアップ"` → **B2**、`status1h === "オフライン"` → **B3** - `status_1h` / `status_30m` の生成元は ★**`lib/fixtures/clean-logs.ts:53-54` の1箇所のみ**★。 `?? "待機中"` という日本語のデフォルト値まで埋め込まれている。 `prismaSource.cleanLogs()`（`lib/db/index.ts:141-142`）は `notImplemented` で、 ★**実データ由来の値は一度も流れたことがない**★ - したがって現在の値は「DBの生値」ではなく ★**当方が fixtures に書いた日本語**★ - 生値方針にすると B2/B3 は ★**例外もテスト失敗も出さずに永久に発火しなくなる**★。しかも `lib/judge/__tests__/advice.test.ts:133-176` は日本語リテラルを**直接渡している**ため ★**テストは緑のまま**★ という最悪の組み合わせになる - そもそも元の値が存在しない: `robots.status` の46値は移動・充電・清掃・帰還の**動作フェーズのみ**で ★**ハンドルアップも通信断も表現していない**★ （`docs/handoff/TeamWorks回答_第2回_20260903.md:107-108` が自ら明記）。`error_type` 24値にも該当なし - ★**D-039 は「B1〜B3 を P1 に含める」と確定している**★ため、これは Phase B の先送りではなく ★**P1 の欠落**★ - **副次的影響**: `lib/theme-status.ts:3-12` と `components/features/alerts/AlertsScreen.tsx:30-38`（★**同一ロジックの重複2実装**★）の 色分けが全て `c.txD`（グレー）にフォールバックする。例外もテスト失敗も出ない ★**当方の推奨案（未承認。ユーザー判断待ち）**★: - B2/B3 の発火条件を `lib/config/` の**設定値**（マッチする文字列の配列）に外出しし、 ★**既定は空＝発火しない**★ とする - 実データで値が判明した時点で**設定値に足すだけで復活**する - `CLAUDE.md` §7 のハードコード禁止にも合致し、★**「静かに壊れる」を「明示的に空」に変えられる**★ - **B1（完了率ベース）は影響を受けず生き残る** #### 4. D-Security 制御盤のエラーは「正常 / 異常」の2状態のみ ★**調査の結果、この決定は現状の実装でほぼ満たされている**★。 | 対象 | 状況 | |---|---| | `DsDevice.connection_status` | ★**すでに2状態 `ok` / `error`**★（指示書G 段階0 / D-065 で3状態から縮小済み）。`lib/types/index.ts:267-273`、`d-watch-api.yaml:1261-1264`、`lib/fixtures/ds-devices.ts` の実データも2値のみ。★**作業不要**★ | | `DsAlert.alert_type` | `security_off` / `disconnected` の2値だが、★**D-067 のとおり `security_off` は `security_statuses` 由来でありエラーではない**★。制御盤エラーは `disconnected` の ★**1種類のみ**★（`docs/decisions.md:486` が「D-S制御盤で発生するアラートは『生死報告がない』の1種類だけ」と既に確定）。★**制御盤エラー側はすでに細分化されていない**★ | **残る作業は ★`DsAlert.detail`（自由記述の詳細文）の削除★ のみ。** TeamWorks 回答（D-065 Q1-3）で「詳細文は**存在しない**」と確定済みだが未実施 （`docs/handoff.md:652-653`）。該当: - `d-watch-api.yaml:1306` - `lib/types/index.ts:295-312` - `lib/fixtures/ds-alerts.ts` の12件 - `components/features/ds-alerts/DsAlertsScreen.tsx:160` ★**`DsAlert.resolution_status`（`pending` / `in_progress` / `done` の3値）は対象外と解釈する**★。 これは「エラーの**種別**」ではなく ★**運用の対応状況**★ であり、実DB `control_error_histories.status`（0/1/2、`docs/decisions.md:484`）に直結し、 **書き込み許可4カラムの1つ**でもある。2値化すると DB と不整合になる。 ★**この解釈でよいかはユーザーに確認する（未確認）**★ #### 5. ロードバランサは nginx で `X-Forwarded-For` に★追記★する ★**指示書I が唯一保留していた着手前確認事項が解決**★（`docs/handoff/指示書I_認証とproxy.md:59-68`）。 - **追記（append）**なので `X-Forwarded-For` は `<自称>, <実際の接続元>` のように**複数要素**になる。 ★**「末尾を取る」が唯一の正解として確定**★ - 指示書I の期待値表（`指示書I:159-160`）で「LB が上書きした場合」としていた**単一要素**のケースは、 ★**追記が確定した以上「nginx を経由していない = 直接アクセス」の異常系**★に意味が変わる ★**新たに判明した論点（すべて未確認）**★: | # | 論点 | |---|---| | 1 | ★**LB と nginx が同一か、LB → nginx の2段か**★。両方が追記すると `XFF = <自称>, <本当のクライアント>, ` となり ★**末尾は LB の内部IPになって全リクエストが同一IPに見え、IP制限が完全に無意味化する**★。正しい一般則は「**末尾から N 番目**」（N = 前段の信頼済みプロキシ数）だが、指示書I には**ホップ数の概念も設定値もない** | | 2 | ★**指示書I の内部矛盾**★: `指示書I:72` は「ヘッダが1つも無い場合は拒否」と指示するが、`指示書I:130, 176` の `ALLOW_ALL_WHEN_EMPTY` の既定が `true` のため ★**初期状態では nginx を経由しない直接アクセスがそのまま通る**★。「XFF の有無」と「allowlist が空か」の判定を**分離する**必要がある | | 3 | `指示書I:73` が要求する「開発時だけ通す設定値」が段階1のコード例（`指示書I:119-131`）に ★**存在しない**★。実装者が `ALLOW_ALL_WHEN_EMPTY` で代用し、**穴が本番に残る**リスク | | 4 | **IPv6・ポート付き・IPv4射影**（`::ffff:203.0.113.10`）の正規化が未定義。`isAllowedIp` は**完全一致の文字列比較のみ** | | 5 | **CIDR / レンジ非対応**（単一IPの列挙のみ） | **正しく押さえられている点**: `指示書I:356-357` の完了条件7 「**先頭に許可IPを書いた偽装ヘッダを送って 403 になること**」は ★**追記確定後に最も重要な検証**★。**維持する**。 ★**Next.js 16 のドキュメントには `X-Forwarded-For` / クライアントIP取得に関する記述が1件も無い**★ ことを再確認した（`node_modules/next/dist/docs/` 全体を調査。`request.ip` もヒット0件）。 `docs/decisions.md:1026` の調査結果と一致する。 #### 影響を受ける文書 | 文書 | 必要な更新 | |---|---| | `d-watch-api.yaml` | `:1192` の enum 撤去、`:1194-1197` / `:527` の「7分類」文言、★`:531` の `meta` 非返却の根拠★、`:1306` の `DsAlert.detail` | | `docs/handoff/analysis/error-type-mapping.md` | ★**参考資料へ降格**★の明記。`:11` の `d-watch-api.yaml:1160` → `:1192` の訂正 | | `docs/handoff/指示書I_認証とproxy.md` | 着手前確認の解決（追記で確定）、`:159-160` の期待値表の意味づけ、論点1〜5の追記 | | `CLAUDE.md` | エラー種別を変換しない方針（§4 相当）の反映 | | `.claude/commands/d-watch.md` | 引き継ぎ時に D-077 を読ませる導線 | | `docs/handoff.md` | 未実施タスク（`DsAlert.detail` 削除）と ★項3 の要判断★ の申し送り | | `docs/decisions.md` | 本項の `:1350` の `d-watch-api.yaml:1160` → `:1192` の訂正 | ### D-078 `[確定]` 2026-09-08 のユーザー判断2件（参照用アカウント受領 / B2 の暫定マッチ値） #### 1. ★TeamWorks の参照用アカウントを受領した（Z-4 解決）★ 2026-09-08、ユーザー経由で受領。★第5回までの5通の確認書で一度も依頼できていなかった項目★で、 第6回の最優先事項として起票する予定だったもの。★これで第6回から Z-4 が落ちる★。 - **アカウント**: 参照用アカウント（ユーザー名・パスワードは `.env.local` に格納。台帳には書かない） - **権限**: `GRANT SELECT ON clean_watch.*` — ★全テーブルの SELECT のみ★。 `CLAUDE.md` §3 の「参照用: 全テーブル SELECT のみ」と一致する - ★**DB名は `clean_watch`**★ - ★**更新用アカウントは後日付与予定**★（`robot_error_reports` / `control_error_histories` の `status`, `comment`, `responded_at`, `resolved_at` の**4カラムのみ** UPDATE）。 ユーザー原文「※後で必要なテーブルに更新権限を付与する」「後々更新も付与する予定です」。 ★**したがって現時点では書き込み系の実装は検証できない**★ （D-Sec アラートの対応状況更新、エラー報告の備考など） - **取り扱い**: ★認証情報は `.env.local`（`.gitignore:34` の `.env*` で追跡外）にのみ格納した。 git 管理下の文書には一切書かない★（`CLAUDE.md` §9.3「認証情報を絶対にコミットしない」） **★接続前に解決が必要な2点（未解決）★** | # | 内容 | |---|---| | 1 | ★**ホスト名とポートが未受領**★。`.env.local` には `` のプレースホルダを入れた状態で待機させている。★**これが来ないと接続できない**★ | | 2 | ★**パスワードに `%` と `@` が含まれるため、MySQL 接続 URL では URL エンコードが必須**★。`%` はパーセントエンコードの開始記号、`@` はホスト区切りとして解釈される。★**生のまま書くと Prisma は `@` 以降をホスト名と解釈して必ず失敗する**★。`%` → `%25`、`@` → `%40` に置換すること。★実際のエンコード済み値は `.env.local` にコメントで併記した（台帳には書かない）★ | **★セキュリティ上の申し送り★** - ★**この認証情報は平文でチャットに貼られた**★。会話ログに残っている。 ★**本番接続に使う前にローテーション（パスワード再発行）を TeamWorks に依頼することを推奨する**★ - P1 は社内利用のみだが、参照用でも `clean_watch` **全テーブル**が読める権限であることに留意 **★接続後にすぐ確認すべきこと（D-077 の未解決項目がまとめて片付く）★** 参照用アカウントで `SELECT` できれば、TeamWorks への照会を待たずに実データで確定できる項目がある。 ★**接続できたら最初にこれを数えること**★: - ★`robot_error_reports.error_type` に実際に出現する値と件数分布★ — 受領した24値リストが実態と 合っているか。「Handrail Lifted」のように**空白入り**の値が本当に存在するか（項2 / D-077 項1） - ★`robots.status` に実際に出現する値★ — 46値のコード表 （`docs/handoff/TeamWorks回答_第2回_20260903.md:53-98`。★**起票時に47件と数えたのは誤りで実測46件。 103が欠番**★）のうち何が使われているか。`-200` が実在するか - ★**オフラインを表す値が存在するか**★ — 存在しなければ最終報告時刻からの導出が必要（D-077 項3 の B3） - ★週次サマリに `week=6` の行が存在するか★（第5回 X-1 の照会内容。D-071） - ★サマリの `week=0` / `month=0 AND week=0` が実際に月次・年次を表しているか★（第5回 X-2） - ★月跨ぎ週が2行に分かれて格納されているか★（第5回 X-3） - ★`error_level` に `Warning` / `Event` が実際に格納されていないか★（D-074 で「格納しない予定」との回答） - **最新DDLの照合** — ★`prisma db pull` で取り込めば、DDL の再受領を待たずに A-1 / A-3 / B-3b の反映状況を確認できる★（D-066 で未反映と判明していた3件） ★**ただし `prisma db pull` はスキーマの取り込みのみ。マイグレーション作成・スキーマ変更は禁止**★ （`CLAUDE.md` §7 / D-056）。 ★**`lib/generated/prisma` は未生成**★（`prisma/schema.prisma:3` の `output` 先だがディレクトリ自体が 存在しない）ため、接続作業は `npx prisma generate` から始まる。 #### 2. ★B2（ハンドルアップ検知）の暫定マッチ値を `Handrail Lifted` とする★ **ユーザー指示（原文）**: > status1h === "ハンドルアップ" > となっている部分も、先程のhandrail ltedで変更してください、ただし暫定で変更のおそれはあります - D-077 項3 で「B2/B3 は生値方針では実データで永久に発火しなくなる」と記録し、当方の推奨案として ★「発火条件を `lib/config/` の設定値に外出しし、既定は空」★ を提示していた。 ★**この推奨が承認された形で、値まで指定された**★ - **決定**: `lib/judge/advice.ts:80-82` の `status1h === "ハンドルアップ"` を ★`Handrail Lifted` とのマッチに変更する★ - ★**「暫定で変更のおそれがある」とユーザーが明言している**★。したがって ★**値をコードに直書きせず、`lib/config/` の設定値（マッチ文字列の配列）として持つ**★。 `CLAUDE.md` §7 のハードコード禁止にも合致し、値が変わったときに1箇所の差し替えで済む - ★`Handrail Lifted` は**空白入り**★。`error_type` の他24値はすべて PascalCase（`EmergencyStop` 等） なので、★**`error_type` の値の形が1種類ではない可能性がある**★ （D-074 / `docs/handoff/analysis/error-type-mapping.md` の指摘）。 完全一致で引く実装では表記ゆれを取りこぼす。 ★**前後の空白を trim し、大小文字を無視した比較にすることを推奨**★ - ★**この値は24値の受領リストに含まれていない**★。ユーザーも「〜だと思いますが」と述べており確定ではない。 ★**参照用アカウントで接続したら、実際に `Handrail Lifted` が `error_type` に存在するかを 最優先で確認する**★（項1参照） - ★**B3（オフライン）は依然として値が不明**★。24値にも `robots.status` の46値にも該当がない。 ★**B3 のマッチ文字列は空（＝発火しない）のままとし、実データで値が判明するまで保留する**★ - ★**B1 は完了率ベース（`judgeGrade(completionRate) === "△"`）なので影響を受けず、そのまま動く**★ - ★**D-039 が「B1〜B3を P1 に含める」と確定しているため、これは Phase B の先送りではなく P1 の作業**★ **影響ファイル**: | 箇所 | 内容 | |---|---| | `lib/judge/advice.ts:80-85` | B2/B3 の発火条件。日本語リテラルの完全一致を設定値経由に差し替える | | `lib/config/advice-rules.ts:110-129` | B2/B3 の定義（`condition` の文言も「ハンドルアップ」「オフライン」のまま） | | `lib/judge/__tests__/advice.test.ts:133-176` | ★**日本語リテラルを直接渡しているため期待値の書き換えが必要**★ | | `lib/fixtures/clean-logs.ts:53-54, 109, 116-118` | ★**`status_1h` / `status_30m` の唯一の生成元。日本語がハードコードされている**★ | 作業は `docs/handoff/指示書K_エラー値を変換せず生値で表示する.md` に段階として追加する（別途更新）。 #### 帰結 D-077 で「★ユーザー判断待ち★」としていた3件のうち、 ★**1件（項3 の B2/B3 の扱い）が本決定で解決した**★。 ★**残る未確認は次の2件**★: | # | 未確認事項 | 出所 | |---|---|---| | 1 | ★**LB と nginx は同一か、LB → nginx の2段か**★（2段で両方が追記すると末尾が LB の内部IPになり IP制限が無意味化する） | D-077 項5 の論点1 | | 2 | ★**`DsAlert.resolution_status` の3値（`pending` / `in_progress` / `done`）は2状態化の対象外という解釈でよいか**★（`control_error_histories.status` の 0/1/2 に直結し、書き込み許可4カラムの1つ） | D-077 項4 | ### D-079 `[確定]` 2026-09-08 のユーザー判断2件（プロキシ段数 / resolution_status）と他メンバーとの合意事項 #### 1. ★ロードバランサと nginx は同一。プロキシは1段★ **ユーザー回答（原文）**: > ★1★は同一です D-077 項5 の「★新たに判明した論点★」の論点1（★**LB と nginx が同一か、LB → nginx の2段か**★）への回答。 - **決定**: ★`TRUSTED_PROXY_HOPS = 1`★ で確定する。すなわち ★**`X-Forwarded-For` の末尾を取る**★（D-077 項5 で「末尾を取るが唯一の正解」としていた前提が成立する） - ★**これで指示書I の着手前確認事項はすべて解決した**★ **★もし実装後に「同一でない」と発覚した場合どうなるか（ユーザーからの追加質問への当方の回答）★** ユーザー質問: 「もし実装後に同一でないと発覚した場合は問題ありますか？」 - ★**fail-closed（安全側）に倒れる**★。2段だった場合、`X-Forwarded-For` の末尾は LB の内部IPになり、★**全リクエストが同一IPに見える**★。 allowlist は社内IPの列挙なので ★**全員が403になり、即座に気づく**★。 ★**「気づかずに素通りする」逆パターンにはならない**★ - **例外**: ★allowlist に LB の内部IPが偶然入っていた場合のみ全員素通りになる★。 社内IPの列挙では通常起きない - ★**修正コストはほぼゼロ**★。`TRUSTED_PROXY_HOPS` は**設定値**なので `1` → `2` に 変えるだけでよい。★コード変更は不要★ （`CLAUDE.md` §7 のハードコード禁止に沿って設定値として持つ理由がここにある） - ★**対策**: 接続確認時に `X-Forwarded-For` の生値を1回だけログに出して要素数を数える手順を 指示書I に追加する★。実測で段数を確定できる（指示書I 側は別途更新中） #### 2. ★`DsAlert.resolution_status`（3値）は2状態化の対象外で確定★ **ユーザー回答（原文）**: > 2は対象外で問題ないです D-077 項4 で「★この解釈でよいかはユーザーに確認する（未確認）★」としていた論点が解決した。 - **決定**: ★`pending` / `in_progress` / `done` の3値をそのまま維持する★ - 理由: これは「エラーの**種別**」ではなく ★**運用の対応状況**★ であり、実DB `control_error_histories.status`（0/1/2、`docs/decisions.md:484`）に直結し、 ★**書き込み許可4カラムの1つ**★でもある。2値化すると DB と不整合になる - ★**D-077 の「ユーザー判断待ち3件」はこれで全件解決**★ （B2/B3 → D-078 項2、LB段数 → 本決定 項1、`resolution_status` → 本決定 項2） #### 3. 他メンバーとの合意事項 ★これは決定ではなく合意の記録★（2026-09-08、他メンバーとのやり取りより）。 **作業順序・スケジュール** - ★**第6回の確認書を最優先で作る**★。 メンバーの言: 「参照用アカウントは、依頼から発行までのリードタイムがこちらでコントロールできません。 今日出すか明日出すかで結果が変わります。プレースホルダ画面の指示書は、いつ作っても同じです」 - ★**注: この判断が出た後に参照用アカウントが届いた**★（D-078 項1）。 したがって★第6回の最優先事項は「接続先（ホスト名・ポート）」に変わった★ - ★**デモの目標は9月中に PPIH 向け**★。「開発ができ次第。可能なら今月中」 - ★**第6回の Z-4 の理由書きに「実データでデモしたい」「9月中に PPIH 向けデモの可能性がある」と 明記してよい**★。★社外に出す話ではないため記載して問題ない、とメンバーが明言★ - ★**第6回は daichi から送付する**★（二重送付を避けるため）。 文書ができたらメンバーに知らせ、同じタイミングで口頭でも押す - ★**質問4件への圧縮に賛成**★。LostLocation とオフラインを落とす判断も妥当。 「質問が少ないほど回答は早く返ります」 **実装上の申し送り** - ★**B2/B3 が日本語文字列の完全一致で判定している件は `prismaSource` の必須確認項目として 確実に残すこと**★（D-077 項3 / D-078 項2）。 メンバーの言: 「実データ接続後に『エラーも出さずに発火しなくなる』は、 テストでも気づけないタイプの事故です」 - ★**`schedules` の fixtures 地雷は、プレースホルダ画面の指示書に必ず入れる**★ （有効なスケジュールを1件足すとダッシュボードの既定表示が異常系になる） - ★**`inspections` は「デモまで一時的に隠す」で正しい。D-031 のスコープは変えない**★ - `system` 画面が D-032 で小さいスコープに絞られている件も了解済み **デモ運用** - ★**fixtures でデモする場合、冒頭で「これはサンプルデータです」と明示する**★。 店舗名が架空のため、説明せずに見せると混乱を招く。★説明はメンバーが行う★ **資料間の優先順位ルールが機能した事例** - ★D-039 の訂正（B1〜B3 は P1）について、メンバーも同じ勘違いをしていたと表明。 「`decisions.md` を正とするルールが効いた形」★ - ★`CLAUDE.md` §5 の「資料間で矛盾があったら『正』に従う」ルールが実際に事故を防いだ事例として 記録に残す価値がある★ #### 帰結 ★**D-077 / D-078 で挙げた未確認事項はすべて解決した**★。 これにより ★**指示書I と指示書K は着手前確認なしで実行可能**★ になった。 ただし実行可能性には次の差がある: | 指示書 | 実データ接続の要否 | |---|---| | ★指示書I（認証と proxy）★ | ★**接続先（ホスト名）はまだ不要**★。設定値と判定ロジックのみで完結するため、そのまま実行できる | | ★指示書K（エラー値を変換せず生値で表示する）★ | 大半は接続不要だが、★**段階7-B の `Handrail Lifted` の実在確認には実データ接続が要る**★（D-078 項2）。ホスト名・ポートの受領待ち | --- ### D-080 `[確定]` `facilities.contract` は10桁の文字列。D-010 の記述を訂正する **決定日**: 2026-09-08。★TeamWorks への照会は不要★（テーブル定義書に答えが書かれていた）。 #### 1. 正しい仕様 ★`facilities.contract` は `varchar(10)` の**文字列**であり、**数値ではない**★。 ★**桁位置**がサービスに対応し、契約済み（有効）なサービスの桁を `1` にする★。 | 桁 | サービス | 備考 | |---|---|---| | 1桁目 | ★D-Security★ | | | 2桁目 | ★D-Watch★ | | | 3桁目以降 | ★将来のサービス用の予備と読める★ | ★定義書に明記なし★（後述） | | 値 | 意味 | |---|---| | `0000000000` | 未設定（既定値） | | `1000000000` | D-Security のみ | | `0100000000` | D-Watch のみ | | `1100000000` | 両方 | #### 2. ★D-010 の記述の訂正★ - ★**D-010（`docs/decisions.md:47-51`）の「0:未設定 / 1:D-Security / 2:D-Watch / 3:両方」という 値の表現は誤り**★。本決定の10桁文字列が正 - ★**D-010 の本体は正しい**★。すなわち ★「`facilities.contract` のみを正とする」「`customers.contract` は参照しない」★は そのまま有効で、★訂正されるのは値の表現だけ★ - `CLAUDE.md` §4.6 の同じ記述も本決定に合わせて訂正した（`CLAUDE.md:158`） - `CLAUDE.md` §7 の「`customers.contract` の参照禁止」は★変更なし★ #### 3. ★出典★ | 出典 | 内容 | |---|---| | `docs/handoff/analysis/table-definitions-01-master.md:122` | `facilities` の `contract`。「各サービス毎にフラグとして機能する. D-Securityを1桁目, D-Watchを2桁目とし, 契約済(有効)なサービスを1とする. 例) 1100000000」 | | `docs/handoff/analysis/table-definitions-02-clean-error.md:280` | ★`clean_schedules` の `contract`★。同一の備考文（★当初「`facility_summaries` 側」と認識していたが、実際は `clean_schedules`★） | | `prisma/schema.prisma:113` | `Facility.contract` — `String @default("0000000000") @db.VarChar(10)` | | `prisma/schema.prisma:511` | `CleanSchedule.contract` — 同上 | ★定義書・実DDL・Prisma スキーマの3者は一致している★。食い違っていたのは ★`CLAUDE.md` と `decisions.md` の記述だけ★だった。 #### 4. ★実装への影響はゼロ（手戻りなしで直せるタイミング）★ - ★`contract` を読むコードは1行も存在しない★（実測）。変換コードが未実装のため、 ★**いま直せば手戻りが発生しない**★ - 言及しているのは `lib/types/index.ts:333` の★コメントだけ★（本決定に合わせて訂正済み） - `lib/fixtures/facilities.ts` は `monitoring_enabled` / `d_security_enabled` の ★boolean を直接持っている★ため、fixtures 経由の画面は影響を受けない #### 5. ★危険性 — 誤った仕様のまま実装した場合★ ★これは「静かに壊れる」種類の事故になる★: - `Number("0000000000") === 0` は ★**例外を出さない**★ - `contract === 3` のような比較は ★**絶対に真にならない**★（`Number("1100000000")` は `1100000000`） - 結果として ★**全施設が「契約なし」と判定され、メニューが全部消える**★ - ★**例外もテスト失敗も出ない**★。fixtures は boolean を直接持つのでテストは緑のまま通る `docs/handoff/analysis/prismaSource実装前チェックリスト.md` §B に本決定を反映した。 #### 6. ★教訓★ - ★**これは `intervals` の区切り文字（カンマかパイプか）を TeamWorks に聞いてしまったのと 同じ種類の失敗である**★。★答えは最初からテーブル定義書の備考欄に書かれていた★ - ★**違いは、今回は照会の前に気づけたこと**★。 ★`docs/handoff/analysis/table-definitions-*.md` を先に検索する運用が機能し、 第6回の確認書に載せる前に自力で解決できた★ - ★**運用として定着させること**★: 「TeamWorks に聞く」前に、必ず ★`docs/handoff/analysis/table-definitions-*.md` の**備考欄**を全文検索する★。 備考欄は表の右端で折り返しも効かないため見落としやすいが、 ★値域・フォーマット・桁の意味はほぼここに書かれている★ #### 7. ★第6回の確認書には載せない★ ★定義書に答えがあるため照会不要★。第6回の質問数を増やさない （D-079 項3「質問が少ないほど回答は早く返る」）。 #### 8. 未確定として残すこと **(a) ★10桁文字列 → boolean への変換規則をどこに置くか★** `Facility.monitoring_enabled` / `d_security_enabled`（`lib/types/index.ts:334-336`）は `boolean` なので、10桁文字列からの導出が必要になる。 - ★**推奨: `lib/format/` または `lib/config/` の純粋関数1箇所に閉じ込める**★ - ★**桁位置をハードコードしないこと**★。桁 → サービスの対応表を設定値として持ち、 ★その関数だけが対応表を知っている状態にする★ - これは `CLAUDE.md` §4.7 の ★「帰属ルールを知っているのは `lib/format/period.ts` の `weekOfMonth()` だけにする」★ と同じ設計方針（`CLAUDE.md` §7 のハードコード禁止にも沿う） - ★どちらのディレクトリに置くかは実装時に決めてよい★（本決定では固定しない） **(b) ★3桁目以降の意味★** ★定義書に明記がない★。10桁ある以上、将来のサービス用の予備と読むのが自然だが、 ★将来サービスが増えたときには TeamWorks への確認が必要★。 ★P1 では1桁目・2桁目以外を読まないこと★。 **(c) `clean_schedules.contract` の用途** `facilities` と同じ形式のカラムが `clean_schedules` にも存在する（出典表の2行目）。 ★P1 で参照する予定はない★が、施設側と食い違う値が入りうるかは未確認。 ★参照する必要が出たら、どちらを正とするかを先に決めること★（`facilities.contract` が正の想定）。 --- ### D-081 `[確定]` エラー種別の照会を取り下げ、第6回の質問を2件に絞る **決定日**: 2026-09-08。★ユーザーの指摘により、送付前に止まった★。 #### 0. 背景 — ユーザーからの指摘 **ユーザー指摘（原文）**: > 質問4のエラーに関しては、現状どのようにロボットから返ってくるか不明のため > 飛んできた文字列を格納する形での実装と言ったはずですが、それとは別の話ですか ★**指摘は正しい。当方の誤りだった。**★ 第6回の原稿（`docs/handoff/TeamWorks確認事項_第6回_20260908.md`）には 「エラー情報についての確認（2件）」として次の2問を載せていた: | 原稿の質問 | 内容 | |---|---| | 質問1 | ★ハンドルアップは `error_type` に現れるか（`Handrail Lifted` か）★ | | 質問2 | ★ブラシエラーは `RobotHardwareErrorToAdmin` に含まれるか★ | #### 1. ★質問2（ブラシエラー）は、D-077 で消えていた質問だった★ - ★生値方針では `RobotHardwareErrorToAdmin` をそのまま画面に出す。ブラシが含まれるかを 知る必要がない★（D-077 項1「エラー種別は変換せず、DBの値をそのまま表示する」） - この質問は ★7分類の「ブラシエラー」という枠を埋めるためのものだった★が、 ★その枠自体が D-077 項1 で消えている★（`d-watch-api.yaml:1192` の enum は撤去対象） - ★**当方が7分類時代の問いをそのまま持ち越した**★。方針変更に文書が追随していなかった #### 2. ★質問1（ハンドルアップ）は別軸だが、それでも今は聞かない★ ★この2問を同じ理由で消すと記録が誤る。区別して残すこと。★ - これは ★表示の変換ではなく、アドバイス B2 の判定条件★ の話である （`lib/judge/advice.ts:80-82`）。★D-078 項2 で暫定値 `Handrail Lifted` を 設定値として持つと決めた★もの - ★**したがって「生値方針で消える」質問ではない**★。質問2 とは性質が違う - ★**しかし今聞く理由が弱い**★: - ★参照用アカウント（D-078 項1）で `robot_error_reports.error_type` を数えれば 実在を確認できる★（`prismaSource実装前チェックリスト.md` §C-1） - ★データに出てこなかった場合、「1か月分見たがこの値が無い。ハンドルアップはどこから 判定するのか」という、より鋭い質問として聞ける★。件数を添えられるので先方も答えやすい - 他メンバーの言「★質問が少ないほど回答は早く返ります★」（D-079 項3）に沿う - ★最優先の「接続先（ホスト名・ポート）」に先方の注意を集めたい★（D-078 項1 の未解決2点の1件目） #### 3. 決定 - ★**第6回の第4部（エラー情報についての確認）を丸ごと削除し、質問を2件 （接続先・最新DDL）に絞る**★ - ★**第1部に「照会を取り下げた」旨を1項目として書く**★。 「聞くのをやめた」ではなく ★「当方で確認できるようになったので照会を減らした」という趣旨★ で。 ★実データを見て疑問が残ったら、具体的な件数や値を添えてあらためて聞く★ とも書く - ★**4部構成・質問2件に作り直し、PDF も再生成する**★ #### 4. ★保留にした質問（消えたのではなく延期した）★ ★これを明確に記録すること。忘れると B2 が静かに死ぬ。★ | # | 保留にした質問 | いつ聞くか | |---|---|---| | ★1★ | ★ハンドルアップは `error_type` のどの値で来るか（`Handrail Lifted` か）★ | ★実データで `error_type` を数え、該当値が見つからなかったとき★ | | 2 | ハンドルアップが `error_type` に来ない場合、どのテーブル・カラムから判定するか | 同上 | - ★**「データに出てこないこと」は「存在しないこと」の証明にならない**★。 1か月分見て無かったとしても、★単に発生していないだけの可能性がある★。 ★**だから確認は必要で、取り下げではなく延期である**★ - ★**B2 は D-039 により P1 スコープ内**★。Phase B の先送りではない - ★`docs/handoff/analysis/prismaSource実装前チェックリスト.md` に保留質問として記載する★ （本決定に合わせて別途更新） #### 5. ★教訓★ - ★**方針を変えたら、送付前の文書も追随させること**★。 D-077 でエラー種別の方針を変えたのに、第6回の原稿は ★7分類時代の質問を残していた★ - ★**「この質問は、今の方針でも必要か」を送付前に1問ずつ確認する**★ - ★**D-080（`facilities.contract`）と同じ構図**★ — どちらも ★「すでに答え／方針があるのに聞こうとした」★。 ★D-080 は定義書を先に見て回避でき、本件はユーザーの指摘で止まった★ ### D-082 `[確定]` B2 / B3 は暫定値のまま進め、実データ確定後に修正する **決定日**: 2026-09-08。★ユーザー判断。D-078 項2 / D-081 項4 の位置づけを確定させるもの★。 #### 1. ユーザー判断 **ユーザー指示（原文）**: > アドバイスは連続で清掃失敗したときのものですね、それなら一旦そのままの文字列で出して、後々修正する形にします - ★**B2（ハンドルアップ検知）/ B3（オフライン検知）は、当面「生値をそのまま表示するだけ」とし、 実データで値が確定してから直す**★ - ★**急がない**★。これがユーザー判断の核心である - ★**これは D-078 項2（B2 の暫定値を `Handrail Lifted` とし `lib/config/` の設定値に置く）を 否定するものではない**★。★その「暫定」の位置づけを明確にし、優先度を下げるもの★である。 ★実装方針そのものは D-078 項2 / 指示書K 段階7-B のまま変更しない★（→ 項4） #### 2. ★アドバイスの発火条件の整理（当方の補足）★ ★**ユーザーの原文には「アドバイスは連続で清掃失敗したときのもの」とあるが、これは正確ではない。 当方から補足した。記録に残す。**★ ★`CLAUDE.md` §4.5 を実際に読んで確認した R1〜R4★: | # | 条件 | アドバイス | ★連続を見るか★ | |---|---|---|---| | ★R1★ | ★**出発失敗（初回）**★ | 事前チェックのアラート内容を確認 | ★**見ない（単日で発火）**★ | | ★R2★ | ★**完了率×（10%未満）**★ | 現場の通路状況＋ロボット状態を確認 | ★**見ない（単日で発火）**★ | | R3 | 同一施設で2日以上連続（出発失敗 or △以下） | 現場責任者に状況をヒアリング | ★見る★ | | R4 | 同一施設で3日以上連続（出発失敗 or △以下） | DFAオンサイト訪問を検討 | ★見る★ | - ★**連続を見るのは R3 / R4 だけ**★。★R1 は初回の出発失敗で発火し、R2 は単日の完了率×で発火する★ - ★**したがって B2/B3 が黙っていても、アドバイス機能の主軸（R1〜R4）は全部動く**★。 ★R1〜R4 は事前チェック由来のロボット状態文字列に一切依存しない★ - ★**B1（完了率△でマップ更新を疑う）も完了率ベースなので影響を受けない**★ （`judgeGrade(completionRate) === "△"`。D-077 項3 / D-078 項2） - なお「連続」は ★**カレンダー日ではなくスケジュール存在日の連続**★ で数える（`CLAUDE.md` §4.5）。 ★清掃予定がない日は連続を途切れさせない★ #### 3. ★帰結 — B2/B3 の優先度を「中」に下げる★ - D-077 項3 では B2/B3 の不発火を ★**「P1 の欠落」**★ と記録した。 ★**D-039 により B1〜B3 は P1 スコープ内なので、スコープの扱いは変わらない**★。 ★Phase B への先送りではない★ - ★**しかし実務上の優先度は下がる**★。理由: - ★R1〜R4 が動くので、アドバイス機能そのものは使える★ - B2/B3 は「ハンドルアップです」「オフラインです」という ★**原因の補足**★ にあたる。 ★主軸ではない★ - ★**値が確定しないまま推測でマッチさせるほうが危険**★ — ★誤った原因を現場に伝えることになる★ （`CLAUDE.md` §7「仕様が不明な箇所を推測で実装すること」の禁止） - ★**ただし「静かに発火しなくなる」性質は変わらない**★。★例外もテスト失敗も出ない★ので、 ★忘れると誰も気づけない★。したがって: - ★**`docs/handoff/analysis/prismaSource実装前チェックリスト.md` §H の保留質問と §B の一覧に残し続けること**★ - ★**優先度が中だからといって、これらの記載を消さないこと**★ #### 4. 実装方針（★変更なし。指示書K 段階7-B のまま★） - ★**`lib/config/robot-status-match.ts` に B2/B3 のマッチ文字列を配列で持つ**★（独立ファイル） - B2 = `["Handrail Lifted"]`（★暫定★）、B3 = `[]`（★空＝発火しない★） - ★**trim + 大小文字無視で比較する**★（`Handrail Lifted` は空白入りで、他24値の PascalCase と 形が違う。★`error_type` の値の形が1種類ではない可能性★。D-074 / D-078 項2） - ★**後で直すときは、この設定値1箇所の差し替えで済む**★。★これが設定値にした理由★である。 ★優先度を下げられるのも、差し替えコストが1箇所で済むからである★ - ★**`status_1h` / `status_30m` は生値をそのまま表示する**★（D-077 項1）。 ★画面に英語識別子が出るのが正しい★。★表示側で日本語へ変換しないこと★ #### 5. ★いつ修正するか★ - ★**参照用アカウント（D-078 項1）で実データに接続し、`robot_error_reports.error_type` の値を 数えた後**★（`prismaSource実装前チェックリスト.md` §C-1）。 ★ホスト名・ポートが未受領のため現時点ではまだ接続できない★（D-078 項1 の未解決1件目） - ★**該当値が見つからなければ、件数と期間を添えて TeamWorks に照会する**★ （D-081 項4 の保留質問1・2。`prismaSource実装前チェックリスト.md` §H-2 の書き方に従う） - ★**見つかれば設定値を差し替えるだけ**★ - ★**「データに出てこないこと」は「存在しないこと」の証明にならない**★（D-081 項4 / §H-1）。 ★0件でも実装を確定させず、照会すること★ --- ### D-083 `[確定]` マスタ画面3枚の実装方針と、調査で見つかった契約の不整合 **決定日**: 2026-09-08。★指示書L（`docs/handoff/指示書L_マスタ画面3枚とinspectionsの一時非表示.md`）の 作成にあたって行った調査の結果★。以下の行番号はすべて実測値。 #### 1. ★4画面はすでにプレースホルダだった★ - 他メンバーの提案（D-079 項3、`docs/decisions.md:2154`）は 「プレースホルダ画面（`facilities` / `schedules` / `system`）を作る」だったが、 ★調査の結果、4画面はすでに `PlaceholderScreen` を返すだけの5行のページになっていた★ | ファイル | 行数 | 内容 | |---|---|---| | `app/(dashboard)/facilities/page.tsx:4` | 5行 | `` | | `app/(dashboard)/schedules/page.tsx:4` | 5行 | `` | | `app/(dashboard)/system/page.tsx:4` | 5行 | `` | | `app/(dashboard)/inspections/page.tsx:4` | 5行 | `` | - ★したがって作業の実体は「プレースホルダを実装済み画面に置き換える」★。 メンバーの意図（メニューを開いて空画面が出るのはデモで印象を損なう）にはそのまま沿う - ★`PlaceholderScreen` を使っているページはこの4本だけである（実測）★。 他の画面（`dashboard` / `detail-log` / `alerts` / `reports` / `ds-logs` / `ds-alerts`）は実装済み - ★材料はほぼ揃っていた（実測）★: | 材料 | 状態 | |---|---| | API契約 | ★`d-watch-api.yaml:731` に `/facilities`、`:768` に `/schedules` が定義済み★（`/inspections` も `:796` / `:878` にある） | | TS型 | ★`lib/types/index.ts:317` `RobotSummary` / `:324` `Facility` / `:349` `Schedule` が定義済み★ | | fixtures | ★`lib/fixtures/facilities.ts` 12件 / `lib/fixtures/schedules.ts` 13件★ | | `db.facilities()` / `db.schedules()` | ★fixtures 実装あり（`lib/db/index.ts:99-104`。全件返すだけ）★ | | ★不足していたもの★ | ★API ルート2本と画面3枚だけ★ | - ★`app/api/` に `facilities` / `schedules` / `inspections` のルートは存在しない★（実測）。 `app/api/settings/advice/route.ts` だけは実装済み（`d-watch-api.yaml:554`） - ★`db.facilities()` と `db.inspections()` / `db.inspectionDetail()` は現状どこからも呼ばれていない（dead）★。 `db.schedules()` だけは `app/api/dashboard/route.ts:58` がダッシュボードの `planned` 算出のために呼んでいる - ★注意: `prismaSource` 側（`lib/db/index.ts:153-164`）は `facilities` / `schedules` / `inspections` / `inspectionDetail` のいずれも `notImplemented()` である★。 ★API ルートを2本作っても、実DB接続時にはここの実装が別途必要になる★ #### 2. ★着手前確認事項（2件）★ ★どちらも「YAML に無いものを画面に出すか / YAML を足すか」という契約の話であり、 先に決めないと指示書L の段階1（API契約の修正）の内容が変わる。★ ★指示書L の冒頭（`docs/handoff/指示書L_マスタ画面3枚とinspectionsの一時非表示.md:23-76`。 `:28` が確認1、`:55` が確認2）に同じ2件が「着手前にユーザーへ確認すること（2件）」として書かれている。★ ##### 2-A. ★`system` 画面の実装スコープ（推奨）★ - ★D-032（`docs/decisions.md:198-201`）は「表示設定」と「運用設定」を実装対象としている★ （★`docs/spec.md:103` の F-10「システム管理（P1限定スコープ）」のサブタブ表も同じ★） - しかし ★`d-watch-api.yaml` に表示設定・運用設定のエンドポイントは無い★。 あるのは `/settings/advice`（`:554`）だけ - ★「表示設定」（ダッシュボードの表示項目 ON/OFF）は永続化とダッシュボード側の対応が必要★で、範囲が大きい - ★推奨スコープ★: - ★「運用設定」タブのみ、読み取り専用★ - 閾値は ★`lib/config/index.ts` から読んで表示★（`GRADE_THRESHOLDS:11` / `ESCALATION_THRESHOLDS:20` / `LAUNCH_GRACE_MINUTES:31` / `PRECHECK_MINUTES_BEFORE:34`）。 ★ハードコード禁止★（`CLAUDE.md` §7） - アドバイス文言は ★`GET /api/settings/advice`（実装済み）★ から取得して表示 - ★画面に「編集は P1 後半で対応」と明示する★ - ★「表示設定」タブは作らない★ - ★理由★: ★D-053「機能しない絞り込みUIを画面に出さない」（`docs/decisions.md:330`）★に 抵触しないため。動かないトグルを並べるのは抵触するが、 ★読み取り専用と明示した表示は抵触しない★ - ★これは未承認の推奨である★。編集まで作るなら ★先に `d-watch-api.yaml` にエンドポイントを追加する必要がある★（`CLAUDE.md` §6-1） - ★「表示設定」タブは P1 後半の宿題として残る★ ##### 2-B. ★施設マスタの検索パラメータの設計（推奨）★ ★モックの検索ボックスは1つだが、YAML のクエリパラメータは3つに分かれていて、そのままでは繋がらない。★ | 側 | 実際の姿 | |---|---| | ★モック（`d-watch-mock.jsx:977`）★ | ★入力欄は**1つ**★（placeholder = `施設名 / シリアル / 住所`）。★`:998-1002` のフィルタは 施設名 / 都道府県 / 住所 / シリアル / メーカー / 機種 の**6項目を OR** で部分一致させている★ | | ★YAML（`d-watch-api.yaml:739-751` の `/facilities`）★ | ★`facility_name` / `serial` / `address` の**3つの独立したパラメータ**★。一覧APIのパラメータは通常 ★**AND**★ で組む | - ★1つの入力欄の値を3パラメータに同時に流すと AND になり、 「施設名にも住所にもシリアルにも同じ文字列が含まれる施設」しか残らない（＝ほぼ常に0件）★。 ★「検索が壊れている」ように見える挙動になる★ - ★推奨（指示書L はこれで書かれている）★: ★`/facilities` に `q` パラメータを追加し、 6項目を **OR** で部分一致させる★（モックの挙動そのまま） - ★既存の `facility_name` / `serial` / `address` は残す★。3つは互いに AND、`q` もそれらと AND （★`q` の内部だけが OR★）。★画面は `q` だけを使う★ - ★前例がある★ — ★`/ds-devices` の `q`（`d-watch-api.yaml:613-616`「施設名 or D-S制御盤シリアル番号(部分一致)」）★と ★`/inspections` の `q`（`d-watch-api.yaml:815-818`「記入者名 or シリアル番号(部分一致)」）★。 ★既存2本と同じ形なので新しい概念は増えない★ - ★`/schedules` も同じ問題を抱えている★（`facility_name` / `serial` の2つ。`d-watch-api.yaml:773-778`）。 ★同じ判断を適用する★ - ★代案★: 画面の入力欄を3つに分ける。★ただし `CLAUDE.md` §5「モックが画面レイアウトの正」から外れるため推奨しない★ - ★これは `d-watch-api.yaml` の変更なので、`CLAUDE.md` §6-1 「API契約を変えたくなったら、先に `d-watch-api.yaml` を直す」に従い、着手前の承認が要る★。 ★どちらを採るにせよ、採った理由を指示書L の段階11 で記録すること★ #### 3. ★調査で見つかった API契約と実装の不整合（4件）★ | # | 不整合 | 対応 | |---|---|---| | ★1★ | ★`d-watch-api.yaml:1361-1373` の `Schedule` スキーマに `facility_id` が無い★。しかし `lib/types/index.ts:352` の `Schedule` には `facility_id: number` があり、`lib/fixtures/schedules.ts` も値を持っている | ★指示書L 段階1 で YAML に追加する★ | | ★2★ | ★`InspectionDetail.photos` の項目名が食い違う★。YAML（`d-watch-api.yaml:1390` の `InspectionDetail`）は `item_type`（英語 enum: `brush` / `dust_box` / `filter` / `squeegee` / `suction_hose` / `waste_tank` / `brush_back`）、TS（`lib/types/index.ts:374` の `InspectionPhoto.item`）は `item`（日本語リテラル: `"ブラシ"` ほか） | ★未解決として残す★。`inspections` は D-072 項7（`docs/decisions.md:1052`）で最後に回す方針のため、今回は直さない | | ★3★ | ★モックの閾値ラベルが確定仕様と矛盾している★。★モック（`d-watch-mock.jsx:1660-1663`）は「◎ 90 **以上** / ○ 70 **以上**」★だが、★`CLAUDE.md` §4.1 と `lib/config/index.ts:11-18`（`GRADE_THRESHOLDS`）のコメントはいずれも「この値を**超える**と ◎」★（★90.0 は ○、70.0 は △ になる★） | ★指示書L は「90% 超」「70% 超」「10% 以上」と書くよう指示している（同 `:814-826` の段階6-5）★。★すなわち `CLAUDE.md` §5「モックが文言の正」を意図的に上書きしている★ — ★閾値は判定に直結するため、文言より §4.1 の確定仕様が優先される★。★モックの「以上」を写すと「90.0% が ◎」という誤った説明が画面に出る★。★`d-watch-mock.jsx` 側は書き換えない★（資料として保存する） | | ★4★ | ★`AdviceSetting` に対応する TS 型が存在しない★。★`d-watch-api.yaml:1229-1252` にスキーマはあるが `lib/types/index.ts` に型が無く★（実測。`grep -n "AdviceSetting" lib/types/index.ts` が0件）、★`app/api/settings/advice/route.ts` の `GET` がインラインのオブジェクトリテラルを返している★ | ★`CLAUDE.md` §9.3「APIレスポンスは必ず型を定義してから実装する」に反する★。★指示書L の段階1-4（同 `:295-317`）で型を起こす指示が入っている★（★`AdviceRuleId` は `lib/config/advice-rules.ts:16` に既にあるので、2箇所に別々の union を書かないこと★） | #### 4. ★モック `d-watch-mock.jsx` の既知の問題（3件）★ ★`CLAUDE.md` §5 はモックを「画面レイアウト・文言・遷移の正」と定めているが、 そのまま移植できない箇所がある。★ | # | 問題 | 対応 | |---|---|---| | ★1★ | ★施設マスタのデータ（`d-watch-mock.jsx:54-64` の `ROBOTS` 9件）が実在の店舗名・住所・電話番号・担当者名★（例 `MEGAドンキ渋谷本店` / `渋谷区宇田川町28-6` / `03-5428-4086`。`@donki.co.jp` のメールアドレスも入っている） | ★1文字もコピーしない★。★`lib/fixtures/facilities.ts` は架空値に置換済み（D-043）なのでこちらを使う★ | | ★2★ | ★システム管理の `ops`（運用設定）タブが2回定義されている★（`d-watch-mock.jsx:1158` と `:1164`。本文も `:1221` と `:1628` の2箇所）。React の key 重複が起きる | ★どちらかに寄せる。当方の推奨は後者（`:1628`）★ — カード1枚に3セクション統合、×グレードの「上記未満」表記（`:1670`）、「変更はDFAシステム管理者のみ」の注記（`:1633`）があり新しく見える。★どちらが正かはモックからは判断できない★ | | ★3★ | ★施設マスタに `📥 インポート`（`d-watch-mock.jsx:978`）と `+ 新規追加`（`:979`）ボタンがあるが `onClick` が無い飾り★ | ★実装しない★。`docs/spec.md:95`（F-08 の本文。★見出しは `docs/spec.md:90`★）が「登録・更新はD-Security側の画面で行うため、D-WatchはGETのみ」と定めている。★動かないボタンは D-053 に抵触する★ | ★追加（同種の問題）★: - ★点検記録のデータ（`d-watch-mock.jsx:81-89` の `INSPECTIONS` 7件）にも 実在の人名・店舗名・申し送り本文が入っている★。 点検者名は全件 `香原秀俊`、施設名は `MEGAUNY西大和店` / `アピタ大和郡山店` / `アピタ伊賀上野店` / `MEGAUNY名張店` / `アピタ松阪三雲店` / `MEGAUNY星川店` / `アピタ桑名店`、 ★`id: 3` の `notes` には副店長からの水漏れの申し送り本文がそのまま入っている★。 ★`inspections` を実装するときも1文字もコピーしないこと★ ##### ★★4-A. 同種の問題が API契約ファイル（`d-watch-api.yaml`）にもある★★ ★★モックだけの問題ではない。実在の個人名が**契約ファイル本体**にも残っていた★★（実測で確認済み。2箇所）: | 行 | 実際の記述 | |---|---| | ★`d-watch-api.yaml:861`★ | `inspector_name: { type: string, maxLength: 100, example: "香原秀俊" }`（`POST /inspections` のリクエストボディ） | | ★`d-watch-api.yaml:1383`★ | `inspector_name: { type: string, example: "香原秀俊" }`（`InspectionDetail` スキーマ） | - ★出所は `d-watch-mock.jsx:81-89` の `INSPECTIONS`★（点検者名が全件この名前） - ★これは `CLAUDE.md` §7「モックに残っている実在の住所・電話番号をそのまま使うこと」の禁止と**同種の問題**★。 ★住所・電話番号ではなく人名だが、実在の個人を指す点は同じで、D-043（架空値への置換）の趣旨に反する★ - ★禁止事項の文面が「住所・電話番号」しか挙げていないため見落とされていた★。 ★実在の**人名**も同じ扱いとする★ - ★指示書L の段階1-6（`docs/handoff/指示書L_マスタ画面3枚とinspectionsの一時非表示.md:332-347`）で、 段階1 が `d-watch-api.yaml` を開くついでにダミー名（例: `"点検 太郎"`）へ置換する指示が入っている★。 ★2行だけの変更で `inspections` の実装には踏み込まない★ - ★`d-watch-mock.jsx` 側は書き換えない★ — ★モックは「画面レイアウト・文言・遷移の正」として保存されている資料であり、 作業対象ではない★ - ★完了確認は `grep -n "香原" d-watch-api.yaml` が0件になること★ #### 5. ★契約フラグによるメニュー表示制御は未実装のまま残す★ - ★`CLAUDE.md` §4.6 は「メニューの表示制御もこのフラグに基づく（契約のないセクションは メニューごと非表示）」と定めている★ - ★しかし未実装★（実測）。`components/layout/AppShell.tsx` に `contract` / `monitoring_enabled` / `d_security_enabled` の参照は★1つも無く★、 3つのメニュー配列（`AppShell.tsx:8` `MENU_MONITORING` / `:15` `MENU_DS` / `:20` `MENU_SETTINGS`）を ★無条件に `.map()` している★（`:120` / `:129` / `:138`）。★モックにも入っていない★ - ★P1 では実装しない★。理由: ★メニューは施設横断のグローバルUIなので、 「どの施設の契約か」が決まらない★。 施設ごとに契約が異なる（`lib/fixtures/facilities.ts` は契約フラグ4パターンを網羅している）ため、 ★「1つでも D-Security 契約施設があれば出す」のか「選択中の施設で決める」のかが未定★ - ★この論点を未確定として記録する★。P1 は DFA 社内利用のみ（顧客アカウントは P2 以降）なので、 ★全メニューを表示したままでも実害は小さい★ - ★D-Watch 側の機能は「モニタリング」（`MENU_MONITORING`）と「設定」（`MENU_SETTINGS`）の 2セクションに分かれている★ので、 ★D-Watch 契約を切る場合に消すブロックは1つではない★。実装するときはこの点に注意すること #### 6. ★`inspections` を隠すのは一時対応★ - ★D-079 項3 の合意「デモまで一時的に隠す。D-031 のスコープは変えない」★ （`docs/decisions.md:2173`） - ★実装は `components/layout/AppShell.tsx:12` の `{ href: "/inspections", id: "inspection", label: "🔧 点検記録" }` を コメントアウトするだけ★（1行） - ★削除ではなくコメントアウトし、理由をコメントで残す★ - ★ルート（`app/(dashboard)/inspections/page.tsx`）は残す。直URLでは到達可能なまま★ - ★`lib/i18n.ts:14`（`"🔧 点検記録"`）と `:39`（`点検記録`）のエントリも残す★（復活時に要る） - ★根拠★: 点検記録は ★D-072 項7（`docs/decisions.md:1052`）で「最後に回す」と決まっている★。 理由は ★写真の置き場所・バケット・期限付き署名URLが未決★で、先に画面を作ると ★写真が表示できない画面ができる★ - ★`docs/architecture.md:129` に点検記録ストアの設計は1行しかない★ （`lib/inspections/` = SQLite + オブジェクトストレージ、「予定」）。 ★スキーマ・写真の保存先の具体はどこにも書かれていない★ #### 7. ★`docs/architecture.md` の記述が古い（発見）★ ★`docs/architecture.md:61-72` の「画面」の実装状況表のうち、`:66-70` の5行が古い★（実測。 ★起票時は `reports/`（`:67`）だけを挙げていたが、実際は3行が誤っていた★）。 | 行 | 記載 | 実態 | |---|---|---| | ★`:66`★ | `app/(dashboard)/alerts/`（F-03）= 「プレースホルダ」 | ★**実装済み**★ | | ★`:67`★ | `app/(dashboard)/reports/`（F-04）= 「プレースホルダ」 | ★**実装済み**★（D-069） | | ★`:68`★ | `app/(dashboard)/inspections/`（F-05）= 「プレースホルダ」 | ★プレースホルダで正しい★ | | ★`:69`★ | `app/(dashboard)/ds-logs/` `ds-alerts/`（F-06 / F-07）= 「プレースホルダ」 | ★**実装済み**★ | | ★`:70`★ | `app/(dashboard)/facilities/` `schedules/` `system/` = 「プレースホルダ」 | ★プレースホルダで正しい（本作業で実装済みになる）★ | - ★したがって本当にプレースホルダなのは `facilities` / `schedules` / `system` / `inspections` の**4画面**だけ★ （項1 の表と一致する）。★`alerts` / `reports` / `ds-logs` / `ds-alerts` はいずれも実装済み★ - ★指示書L の段階11（同 `:1092` / `:1099` / `:1147`）で `docs/architecture.md:66-70` をまとめて直すこと★。 ★本作業完了後にプレースホルダとして残るのは `:68` の `inspections/` だけになる★ #### ★`docs/spec.md` の参照行番号の訂正★ ★D-083 起票時に参照した `docs/spec.md:145-152`（F-08）/ `:154-158`（F-09）/ `:160-166`（F-10）は **誤り**だった★。★正しい行番号は以下（実測）★: | 対象 | 正しい行 | |---|---| | ★F-08 施設ロボットマスタ（参照のみ）★ | ★`docs/spec.md:90`★ | | ★F-09 スケジュール（参照のみ）★ | ★`docs/spec.md:98`★ | | ★F-10 システム管理（P1限定スコープ）★ | ★`docs/spec.md:103`★ | | ★「登録・更新は D-Security 側の画面で行うため、D-Watch は GET のみ」★ | ★`docs/spec.md:95`★ | | ★M5 マスタViewer のチェックリスト（F-08 / F-09 / F-10 の3項目）★ | ★`docs/spec.md:195-197`★ | ★**この種の「資料を開かずに書いた参照」の取り違えは繰り返し起きている**★ （★D-080 は `facilities.contract` の型を古い記述のまま引き継いでいた（D-010 の訂正）★、 ★D-068 は決定番号の二重採番（2026-09-07）★）。 ★file:line を書くときは、必ずそのファイルを開いて実測してから書くこと。★ #### 帰結 - ★**指示書L は作成済み（未実行）**★ — ★`docs/handoff/指示書L_マスタ画面3枚とinspectionsの一時非表示.md`（**1224行 / 91,173 bytes**。実測）★。 ★12段階（段階0〜段階11）★ - ★**次に取る決定番号は D-084**★（★指示書K / 指示書I が先に走ると繰り上がるので、 着手直前に `grep -n "^### D-0" docs/decisions.md` で最終番号を自分で確認すること★。 ★2026-09-07 に D-068 の二重採番が実際に起きている★） - ★**着手前確認は2件**★ — ★項2-A（`system` 画面のスコープ）★ と ★項2-B（施設マスタの検索パラメータ = `/facilities` への `q` 追加）★。 ★どちらも承認されないと指示書L の段階1 の内容が変わる★ - ★**fixtures と型と契約が揃っていたため、作業は API ルート2本と画面3枚に収まる**★ - ★**ただし段階1 で契約側の後始末が3件付く**★ — ★`Schedule.facility_id` の追加★ / ★`AdviceSetting` の TS 型起こし★ / ★`inspector_name` の実在人名の置換★ - ★**実データ接続を待たずに進められる**★（ホスト名・ポートの受領待ち = D-078 項1 に ブロックされない） --- ### D-084 `[確定]` 指示書L（マスタ画面3枚とinspectionsの一時非表示）を実行した 段階0〜11を実施。**着手前確認2件はどちらもユーザー承認により指示書の推奨どおり採用**した: ①`system`のスコープは運用設定のみ・読み取り専用、②`/facilities` `/schedules`に`q`パラメータを追加する。 #### 実装した内容 | 段階 | 内容 | |---|---| | 段階1 | `d-watch-api.yaml`の`Schedule`に`facility_id`を追加、`/facilities`と`/schedules`に`q`を追加（既存の個別パラメータとはAND、`q`の内部だけOR）。`inspector_name`の実在人名（香原秀俊）をダミー名に置換。`lib/types/index.ts`に`AdviceSetting`型を追加し、`app/api/settings/advice/route.ts`のGETに型注釈を付ける（ロジック無変更）。★あわせて、指示書G段階0で入っていた`DsDevice.connection_status.description`のYAML構文エラー（コロン+スペースを含む未クォートの値）を発見・修正した（`d-watch-api.yaml`はこれまでYAMLとしてパース不能だった）★ | | 段階2 | `GET /api/facilities`（`lib/facilities/query.ts`）。`db.facilities()`は全件返すだけでフィルタはルート側。`robots[]`を横断してシリアル検索（1台でも一致でヒット） | | 段階3 | `GET /api/schedules`（`lib/schedules/query.ts`）。`active`では絞り込まず有効・無効の両方を返す。★`lib/fixtures/schedules.ts`は一切変更していない★（ダッシュボードの`planned`集計と当日ログ10行を一致させる補完ペア設計を壊さないため）。実DB接続時の4つの罠（`inactive`の論理反転／`weeks`カラム名／`HHMM`の24〜29／`weekdays_label`はDB非存在）をdocstringに記録 | | 段階4 | 施設ロボットマスタ画面（F-08）。10列・ロボット1台1行・監視/D-Secの○/ー表示。フッタは`meta.total`を使用。実在の個人情報は使用していない | | 段階5 | スケジュール管理画面（F-09）。`weekdays`（7桁）は画面で解釈せず`weekdays_label`をそのまま表示、`end_time`もパースしない（D-060の整形済み文字列）。無効行は`opacity: 0.5`。完全な参照専用（クリック・遷移なし） | | 段階6 | システム管理画面（F-10）。運用設定タブのみ・読み取り専用。モックの`ops`タブ二重定義は`:1628`側を採用。閾値の文言はモックの「以上」ではなく`CLAUDE.md` §4.1の「超」を採用。「編集はP1後半で対応します」を明示し、動かない入力欄・保存ボタンは置かない | | 段階7 | `inspections`をメニューから一時的に隠す（`components/layout/AppShell.tsx`のコメントアウト。削除ではない） | | 段階8 | 3画面のi18n対訳を追加。SystemScreen.tsxが方式B（1文字キー`第`/`分前`/`日以上連続`）になっていたのを方式A（プレースホルダ+replace）に修正 | #### 記録すべき事項（指示書Lが指定した17項目） 1. 指示書Lを実行し、3画面（F-08/F-09/F-10）を`PlaceholderScreen`から差し替えた 2. `system`の実装スコープは運用設定のみ・読み取り専用（D-053に抵触しないため。「表示設定」は永続化とダッシュボード側対応が必要で本作業の範囲を超えるため） 3. ★**「表示設定」タブは作っていない。D-032では実装対象なので、P1後半に残る宿題である**★ 4. モックの`ops`タブ二重定義（`d-watch-mock.jsx:1158`/`:1164`、本文`:1221`/`:1628`）は`:1628`側を採用した（1カード3セクション統合・×に「上記未満」表記・「変更はDFAシステム管理者のみ」の注記があるため） 5. 閾値の文言はモックの「以上」ではなく確定仕様の「超」にした（`CLAUDE.md` §4.1が§5の「モックが文言の正」より上位のため） 6. モックの`📥 インポート`/`+ 新規追加`ボタンは実装していない（`docs/spec.md`でGETのみ・モックのボタンは`onClick`の無い飾り・D-053） 7. `inspections`を隠したのは一時対応で、D-031のP1スコープは変えていない（復活手順: `AppShell.tsx`のコメントを外すだけ） 8. `d-watch-api.yaml`の`Schedule`に`facility_id`を追加した（型とfixturesには既にあった） 9. `q`パラメータを追加した（確認2の結果）。個別パラメータ（`facility_name`/`serial`/`address`）とはAND、`q`の内部だけがOR 10. `lib/types/index.ts`に`AdviceSetting`を追加した（YAMLにはあったがTSに無かった） 11. ★**`InspectionDetail.photos`の`item_type`（YAML）vs `item`（TS）の不整合が未解決で残っている**★。点検記録に着手する前に解決が必要 12. ★★**契約フラグ（`facilities.contract`）によるメニュー表示制御は未実装のままである**★★。`CLAUDE.md` §4.6が「契約のないセクションはメニューごと非表示」と定めているが、メニューは施設横断のグローバルUIなので「どの施設の契約か」が決まらない。**P1では全メニューを表示したままにする**（P2で顧客アカウントが入ったときに顧客単位で判定できるようになる） 13. `lib/fixtures/schedules.ts`は一切変更していない（`planned`の補完ペア設計を壊さないため。D-079項3の申し送り） 14. `d-watch-api.yaml:861`/`:1383`の`inspector_name`のexampleにあった実在の人名「香原秀俊」をダミー名「点検 太郎」に置換した 15. 実DB接続時には`prismaSource`（`lib/db/index.ts`）の`facilities`/`schedules`の実装が別途必要。`lib/schedules/query.ts`のdocstringに書いた4つの罠（`inactive`の反転／`weeks`カラム名／`HHMM`の24〜29／`weekdays_label`がDBに無い）を申し送る 16. `docs/architecture.md`の実装状況表を最新化した（`alerts`/`reports`/`ds-logs`/`ds-alerts`/`facilities`/`schedules`/`system`はいずれも実装済み。プレースホルダとして残るのは`inspections`だけ） 17. 実測値（下記） #### ブラウザでの動作確認について ★**このセッションにはブラウザ操作手段（`chromium-cli`等）が無かった**★（Windows環境）ため、 `USE_FIXTURES=true`で開発サーバーを起動し、実際のHTTPリクエスト（`curl`）と、`GET`各APIの レスポンス内容で代替確認した。 - `/facilities` `/schedules` `/system` `/dashboard` `/inspections` すべて200 - `GET /api/facilities`: `meta.total=12`、id7（3台）・id12（0台）を確認、`q=8111r`（小文字）が 大文字混じりのシリアルにヒットすることを確認 - `GET /api/schedules`: `meta.total=13`、id24（`active=false`）・id27（`23:30 - 00:30`の日跨ぎ）を確認 - `GET /api/settings/advice`: 7件（R1〜R4/B1〜B3）を確認 - ★`GET /api/dashboard`: `{planned: 10, completed: 9}`を確認（段階3の地雷を踏んでいないことの 最重要確認）★ - メニューのHTMLに「🔧 点検記録」が含まれないことを確認 - サーバーログにエラー・`data.anomaly`のwarnが出ていないことを確認 - ★**ただし、`FacilitiesScreen`等はクライアントコンポーネント（`"use client"`）で データをuseEffectで取得するため、`curl`で見えるのはローディング中のシェルのみで、 実際にテーブルへ描画された内容・ダーク/ライト切替・JP/EN切替・横スクロールの 挙動・ブラウザコンソールのエラーは未確認**★。次にブラウザ操作が可能なセッションで 一度だけ目視確認することを推奨する（指示書G/H完了時と同じ制約） #### 実測値（このメモを書いた時点） - `npx tsc --noEmit`: エラー0 - `npm test`: **24ファイル / 530テスト 全パス**（指示書J/G完了時461 → 段階2で+41 → 段階3で+28 → 段階4〜8はテスト追加なし） - `npm run lint`: 0 #### 実行環境について 指示書J/Gと同じく、Claude Code（Sonnet 5。監督役）がopusサブエージェントに段階ごと （段階1単独 → 段階2/3/6/7並列 → 段階4/5並列 → 段階8）で委譲する形で実行した。 監督側は各段階の成果物を自分で読み、`tsc --noEmit` / `npm run lint` / `npm test`を 再実行してからcommitしている。段階8完了後、SystemScreen.tsxの方式B使用（サブエージェントが 自ら発見・報告した既知の制約）を監督側が直接修正した。 --- ### D-085 `[確定]` 指示書M（ローカルDBで動かす第1歩）着手前確認2件、いずれも推奨案で確定 指示書Mが「★着手前にユーザーへ確認すること（2件）★」として提示した2件を、ユーザーが どちらも指示書Mの推奨案どおりに承認した。 #### 確認1 — `devices.maker_id` の採番 ★**`1` = PUDU / `2` = Keenon`**★ で確定。★対応表は `lib/config/index.ts` に置き、 桁位置や番号をコードに直書きしない★。★未知の番号（受領済みの2つ以外）は `String(maker_id)` を そのまま返し、`"不明"` 等に潰さない★（D-077と同じ考え方。makersテーブルが提供されない前提は D-057 A-1）。★DFA側の暫定決定であり、実データのmaker_idを受領したら差し替える★。 #### 確認2 — 施設12（ロボット0台）のスケジュールの扱い ★**シードから除外する**★で確定。除外は`facility_id`を名指しするハードコードではなく、 ★「シリアルが`facilities` fixturesのロボット一覧に存在しない行はスキップする」という 構造的な規則★で行う。スキップ件数は標準出力に出し、★1件（id33・シリアル `8111R5628060166`）以外の件数になったら、そこで止めて報告する★。 #### 記録すべき事項 1. この2件はいずれも「DBに何を書くか」を決める話であり、指示書Mの段階2（シード作成）の 前提になる。指示書M自体は段階0の「未着手」のまま変わらない — この決定は着手前確認を 満たしただけで、実装（段階1以降）はまだ行っていない 2. 実装はCursor側の担当（`.claude/commands/d-watch.md`の役割分担）。この決定はClaude Code側 （調査・確認・記録）の作業として行った 3. `docs/handoff.md`にも同内容を追記2として反映する --- ### D-086 `[確定]` 指示書M（ローカルDBで動かす第1歩）を実行した 段階0〜6を実施。★**役割分担上は「実装はCursor側」だが、ユーザーが「このセッションが Cursorのターミナル上で動いているClaude」と明示したため、Claude Code側のセッションが そのまま実装を行った**★。着手前確認2件（D-085）は指示書Mの推奨案どおり確定済み。 #### 実装した内容 | 段階 | 内容 | コミット | |---|---|---| | 段階1 | `npx prisma generate` でPrismaクライアントを生成（コミットなし。`.gitignore`で追跡外） | — | | 段階2 | `scripts/seed-local-db.ts` を作成。`lib/fixtures/facilities.ts` / `schedules.ts` から `dwatch_local` へ冪等に投入 | `a5502ac` | | 段階3 | `prismaSource.facilities()` を実装 | `be01922` | | 段階4 | `prismaSource.schedules()` を実装 | `4999155` | | 段階5 | 動作確認（★Edge Runtimeバンドル破壊を発見・修正★） | `553b3cc`（修正のみ。段階5自体はコミットなし） | | 段階6 | 本記録 | 本コミット | #### 記録すべき事項（指示書Mが指定した16項目） 1. **ローカルDBで動かす方針にした理由**: `lib/fixtures/` は画面ごとに別ファイルで手書きされており、 ファイル間で辻褄が合わなくなる。型チェックもテストも通るため誰も気づかない。実際に2件見つかっている: ① 施設12「フレッシュタウン湖畔店」は`robots: []`（ロボット0台）なのに、 `lib/fixtures/schedules.ts`（id33）・`clean-logs.ts`・`reports.ts`がシリアル`8111R5628060166`を 割り当てている。② 「メガバリューマート緑野第二店」（`ds-alerts.ts` / `ds-devices.ts`）が 施設マスタ12件に存在しない（マスタにあるのは「緑野店」）。DB経由にすると、施設名もシリアルも 「結合して取ってくる」ものになるため、存在しない参照はINSERT時に外部キーが拒否し、 この種の矛盾が構造的に起きなくなる 2. **`dwatch_local`と`dwatch_ddl`の役割の違い**: 前者はシード投入先の書き込み可能な作業用DB （28テーブル・外部キー50本）。後者はTeamWorksから受領した実DDL（`clean_watch_20260902.sql`）を 投入した参照専用DB（39テーブル）。本作業で書き込むのは`dwatch_local`だけ 3. ★★**`dwatch_local`は現行の`prisma/schema.prisma`と一致していない**★★: `robots.task_id` / `version`（varchar(20) NULL）、`clean_schedules.started_at` / `ended_at` （datetime NULL）が`dwatch_local`側にだけ存在する。現行`schema.prisma`は2026-09-03に `dwatch_ddl`に対して`db pull`した生成物（D-056）であり、`dwatch_local`はそれ以前の 「テーブル定義書ベースの手書きスキーマ」から作られたものと読める。 ★**帰結: `dwatch_local`に対して`prisma db pull` / `db push` / `migrate`を実行してはいけない**★ （前者は実DDLの姿から乖離する。後者は余分な4列をDROPしようとする）。 余分な4列はすべてNULL許容または既定値付きなので、INSERTには影響しない（実測済み） 4. `customers`に`contract`列が存在しないことを実DDLで確認できた（`dwatch_local` / `dwatch_ddl`の 両方で0件）。D-010「`customers.contract`は削除依頼済み」が実際に反映されている 5. `dwatch_ddl.robot_error_reports`にPRIMARY KEYが無いことを確認できた（制約はUNIQUE 1本+外部キー3本 のみ）。D-066のA-1（PRIMARY KEY付与）が未反映であることの裏取り。ついでの発見として、 そのUNIQUEのインデックス名は`robot_error_reports_report_id_unique`なのに対象列は`error_id`で、 名前と列が食い違っている 6. **変換表**（`lib/db/index.ts`の`prismaSource.facilities()` / `schedules()`がそのまま実装）: 全`id`はBigInt→`Number()`変換必須（`JSON.stringify`はBigIntで例外を投げる）。 `Facility.address`は`addr1`+`addr2`を区切りなしで連結（`lib/format/address.ts`）。 `Facility.monitoring_enabled` / `d_security_enabled`は`contract`（10桁文字列）の2桁目/1桁目 （`lib/format/contract.ts`。桁位置は`lib/config/index.ts`の`CONTRACT_DIGITS`）。 `RobotSummary.maker`は`devices.maker_id`を`lib/config/index.ts`の`MAKER_NAMES`で変換。 `Schedule.weekdays`は`weeks`列（カラム名が違う）。`Schedule.weekdays_label`はDBに無くサーバ生成 （`lib/format/schedule.ts`の`weekdaysLabel`）。`Schedule.start_time`/`end_time`はHHMM4桁文字列 （`end_time`は時が24〜29を取りうる。`formatEndTime`が「翌HH:MM」に整形）。 `Schedule.active`は`inactive`の反転（`active: row.inactive === 0`。`Boolean()`にすると全件逆になる） 7. **`devices.maker_id`の採番**（確認1の結果）: `1`=PUDU / `2`=Keenon。`lib/config/index.ts`の `MAKER_NAMES`に定義。★DFA側の暫定決定であり、実データのmaker_idを受領したら差し替える★ （makersテーブルは提供されない。D-057 A-1） 8. **施設12のスケジュールをシードから除外したこと**: `scripts/seed-local-db.ts`が 「シリアルが`facilities` fixturesのロボット一覧に存在しない行はスキップする」という 構造的な規則で判定（`facility_id === 12`を名指ししない）。実測でスキップは1件のみ （id33・シリアル`8111R5628060166`）。第2歩で清掃ログ側も同じ規則で除外すれば、 ダッシュボードの`planned`相当が9対9で均衡する 9. **`inactive`では絞らない（`deleted_at IS NULL`でのみ絞る）と決めたこと**: `inactive`は「無効化」であって削除ではなく、画面が見せ分ける可能性がある （`lib/schedules/query.ts:108-112`に前例あり:「一覧は有効・無効の両方を返す」）。 ★**これは仕様が未確定な箇所である**★。将来的に「一覧APIは有効のみ返す」等の仕様が 確定した場合は、この決定を上書きすること 10. **id27の`end_time`をDBに`"2430"`で入れ、APIが`"翌00:30"`を返すこと**: fixtures側は D-060より前の書き方のまま`"00:30"`を持っている（23:30開始・日跨ぎ）が、これをそのまま DBに書くと「開始より前に終わる」という矛盾したデータになる。シードはD-060に忠実な `"2430"`を書く。★段階5で確認したとおり、fixtures版（`"00:30"`）とDB版（`"翌00:30"`）は この1件だけ意図的に不一致——DB版が正しい★ 11. **シードの実行方法**: `npm run seed:local`（内部で`tsx scripts/seed-local-db.ts`）。 ★理由: 生成されたPrismaクライアントは拡張子なし相対import（例:`export * from './enums'`）を 使っており、これはこのプロジェクトの`tsconfig.json`の`moduleResolution: "bundler"`前提の コードで、素の`node`のESMローダー（拡張子必須）では解決できない（実測。 `node --experimental-transform-types`でも同じ`ERR_MODULE_NOT_FOUND`）。 `prisma/schema.prisma`のgenerator設定を変える対応はD-056違反なので取らず、 esbuildベースの`tsx`を追加して解決した★ 12. **`lib/fixtures/`は変更していない**（`git diff --stat lib/fixtures/`が空）。テストは fixturesと純粋関数のままで、DB依存にしていない（`lib/db/local-guard.ts`のテストも URL文字列を渡す純粋関数のテストのみ） 13. ★★**第2歩に残した10メソッドの一覧**★★（`lib/db/index.ts`で実測）: `cleanLogs` / `prechecks` / `dsDevices` / `dsAlerts` / `inspections` / `inspectionDetail` / `reportKpis` / `facilityPerformance` / `continuousProblems` / `errorBreakdown` 14. **`USE_FIXTURES=false`で落ちる画面の一覧**（段階5の確認4の実測。いずれもエラーメッセージは `[db] {name} のPrisma実装はまだありません。USE_FIXTURES=true で開発してください。`で統一）: `/api/clean-logs`（`/detail-log` `/alerts`が使用）・`/api/prechecks`・`/api/ds-devices`・ `/api/ds-alerts`・`/api/dashboard`・`/api/reports/kpi` `/facility-performance` `/continuous-problems` `/error-breakdown`（`/reports`が使用）はすべて500。 画面（HTMLシェル）自体はクライアントコンポーネントのため200を返し、実際のエラーは ブラウザ側のfetchで発生する（指示書L/D-084と同じ制約。ブラウザ操作手段が無い環境のため `curl`とサーバログで代替確認した） 15. **`ds-alerts` / `ds-devices`の「緑野第二店」の不整合は未解決のまま残っている** （`dsDevices()` / `dsAlerts()`の実装とセット。第2歩で解消する） 16. 実測値: `npm test` **28ファイル / 572テスト 全パス**（着手前24ファイル/530テストから +4ファイル/+42テスト）。`npx tsc --noEmit`エラー0。`npm run lint` 0 #### ★段階5で発見した想定外の不具合とその修正（重要）★ ★★**`USE_FIXTURES=false`にした直後、`/api/reports/*`（4エンドポイントすべて）が404になった**★★。 指示書には無かった発見であり、後任が同じ地雷を踏まないよう詳しく記録する。 - **原因**: `lib/logger/index.ts`が`USE_FIXTURES`の判定のために`@/lib/db`（`lib/db/index.ts`）を importしていた。`lib/logger`は`instrumentation.ts`（`register()` / `onRequestError`）経由で **Edge Runtimeでもコンパイルされる**。段階3で`lib/db/index.ts`の`prismaSource`が生成済み Prismaクライアントを動的import（`await import("./prisma")`）するようになったため、 Turbopackが（実行されるかどうかに関わらず）そのimport先を静的にバンドル対象として解析し、 Prismaクライアントが依存する`node:path` / `node:url`等のNode組み込みモジュールが Edgeバンドルに引きずり込まれてビルドが壊れた。ビルドログに `A Node.js module is loaded ('node:path') which is not supported in the Edge Runtime`と `Ecmascript file had an error`が繰り返し出ていたことから特定した - **修正**: `USE_FIXTURES`を`lib/db/use-fixtures.ts`という依存の無い独立ファイルに切り出し、 `lib/logger/index.ts`はそちらから読むようにした（`lib/db/index.ts`は引き続き同名でre-exportする ので、他の呼び出し側の変更は不要）。コミット`553b3cc` - ★**教訓**: `lib/db/index.ts`（またはそこから到達可能なモジュール）に、生成済みPrismaクライアント へ到達する新しいimport（動的importも含む）を足すときは、`instrumentation.ts`経由でEdge Runtimeにも到達しないか必ず確認すること。`USE_FIXTURES=false`にしてdev serverを再起動し、 `/api/reports/*`等の全エンドポイントを一通り叩くまで「動いている」と判断しないこと★ #### 実行環境について このセッションは`.claude/commands/d-watch.md`の役割分担では「Claude Code側は調査・検証・ 指示書作成まで、実装はCursor側」だが、ユーザーが「このセッションはCursorのターミナル上で 動いているClaude」と明示したため、Claude Code側のセッションがそのまま段階1〜6を直接実装した （サブエージェントへの委譲はしていない。段階2〜4の完了後、独立した2視点 （データ変換ロジックの正しさ／禁止事項・完了条件の遵守）でforkレビューを行い、 両方とも問題なしの結果を得てからpushした）。 --- ### D-087 `[確定]` 指示書N（対応機種レジストリと未対応機種の表示）を実行した 段階0〜6を実施。★**役割分担上は「実装はCursor側」だが、指示書を渡された側で 実装を行うようユーザーから直接指示されたため、Claude Code側のセッションがそのまま 実装を行った**★。着手前確認は「なし」（2件とも2026-09-09にユーザーが回答済み。指示書内に明記）。 #### 発端 2026-09-09、ユーザーから次の情報を受けた（原文）: > pudu製品は現状CC1のみ、将来的にMT1も表示するかもしれません > keenon製品はC30とC40を将来的にやる可能性があります > なので現状はCC1のみ表示されるように、他の3機種は追加が必要になったときに迅速に追加できるように土台だけ置いておいてください CLAUDE.md §1「ロボットメーカーはPUDU Roboticsのみ（KeenonはP2以降）」と、 `lib/fixtures/facilities.ts`に混入していたKeenon T5(1台)・PUDU Phantas(1台)が 食い違っていた。また「対応している機種はどれか」という情報がコードのどこにも 存在しなかった（`devices.model_name`の文字列をそのまま画面に出すだけ）。 #### 実装した内容 | 段階 | 内容 | コミット | |---|---|---| | 段階0 | 前提の確認（コミットなし） | — | | 段階1 | `ROBOT_MODELS`（対応機種レジストリ）と`isSupportedModel()`を追加 | `d3f95bd` | | 段階2 | `FacilitiesScreen.tsx`のロボット列に「未対応」バッジを追加 | `7a68a4d` | | 段階3 | fixturesをPUDU CC1のみにする（台数14台は維持） | `6f7eb92` | | 段階4 | 境界ケースをテスト側で担保する（Keenonテストは1件も削除せず） | `57a22f3` | | 段階5 | 動作確認（コミットなし） | — | | 段階6 | 本記録 | 本コミット | #### 記録すべき事項（指示書Nが指定した16項目） 1. **対応機種は現状PUDU CC1のみ**。将来PUDU MT1 / Keenon C30 / Keenon C40の可能性がある （2026-09-09ユーザー情報。原文は上記「発端」に引用済み） 2. ★★**未登録機種は隠さず「未対応」バッジを付ける**★★。理由: 隠す（フィルタする）と、 実データに未登録機種（例: MT1）が来たときロボットが画面から静かに消え、例外もテスト 失敗も出ないまま誰も気づけなくなる。指示書K（エラー種別を変換しない。D-077）で 避けた構図と同じであり、`MAKER_NAMES`のコメント（「未知の番号を"不明"等に潰さない」） とも同じ思想 3. **`supported`フラグ方式を採った理由**: コメントアウトだと型チェックもテストも通らず、 有効化するまで綴りの誤り（`MT-1`/`mt1`等）に気づけない。フラグなら「既知だが未対応」と 「完全に未知」を区別できる。有効化が`false`→`true`の1文字で済み、 「迅速に追加できるように土台を置く」というユーザー要望に直結する 4. **レジストリの置き場所を`lib/config/index.ts`（`MAKER_NAMES`の隣）にした**。 理由: `MAKER_NAMES`とまったく同じ性質の設定値（「DBから来た識別子をDFA側の対応表で 解釈する」）であり、分散させると片方だけ直す事故が起きる。`lib/config/allowed-ips.ts` を独立させた理由（proxyのEdgeバンドルに judge 系を引き込まないため。指示書I）は ここには当てはまらない — `FacilitiesScreen.tsx`は既に`@/lib/config`をimportしている クライアントコンポーネントであり、バンドル分離の必要が無いため。 ★判定関数は`lib/format/robot-model.ts`を選んだ★（`lib/format/contract.ts`と同じ 「設定値は`lib/config`、それを読む純粋関数は`lib/format`」という既存の分け方を踏襲した） 5. **大文字小文字・前後空白の扱い**: `trim()`してから`toUpperCase()`で揃え、正規化後の 完全一致で判定する（部分一致はしない。`"CC10"`が`"CC1"`にヒットしないことをテストで固定）。 指示書Kが採ったB2判定の考え方（実データの表記ゆれに備え、正規化してから完全一致）と揃えた 6. **fixturesからKeenon / Phantasを外し、CC1のみにした**。台数（14台）は変えていない （施設5は2台のまま、施設7は3台のまま。`npm run seed:local`で`skip: 1件`のまま 完了することを実測で確認した） 7. **境界ケースは`lib/facilities/__tests__/query.test.ts`の合成データ（`row()`/`robot()` ヘルパ）で担保する**（`:158`「メーカーの部分一致」/ `:188`相当 / `:225`〜`:229` 「3台目のシリアルでもヒット」/ `:308`・`:313`「`filterFacilitiesByFields`側の同シリアル」。 いずれも1件も削除していない。それぞれの箇所に「なぜKeenonが残っているか」のコメントを追加した） 8. ★★**`CLAUDE.md` §1「P1はPUDUのみ」とfixturesが食い違っていたのを解消した**★★ （fixturesが実装解析の中で唯一「PUDU限定」の前提から外れていた箇所だった） 9. **シリアル番号は「揃える」を選んだ**（当方の推奨どおり）。理由: 他機種由来の値 （`8222P...`=Phantas由来 / `9333K...`=Keenon由来と思われる接頭辞）を残したままCC1に 機種名だけ変えると、シリアルと機種が食い違って見え、後任が混乱する。既存のどのシリアル とも重複しない`8111R5628060088`（元Phantas。施設5・2台目）/ `8111R5628060177` （元Keenon T5。施設7・3台目）に変更し、fixtures側6箇所 （`facilities.ts`2 / `clean-logs.ts`2 / `inspections.ts`1 / `schedules.ts`1）を 同じコミットで直した。`query.test.ts`側の合成データ（5箇所）は変えていない （独立しているため。変え忘れは`npm run seed:local`のスキップ件数ガードで検知できる 仕組みが既にあり、実際に1件のまま完了することを確認した） 10. **`lib/fixtures/clean-logs.ts:149, 151`の`model_name`も直した**（調査で追加判明。 `"Keenon T5"` / `"PUDU Phantas"`という明示指定を削除し、`row()`の既定値 `"PUDU CC1"`に落ちるようにした） 11. **清掃ログ画面（F-02）には「未対応」バッジを出していない**。理由: `CleanLogItem.model_name`は「PUDU CC1」という1本の文字列で、`facilities`側の `RobotSummary`（`maker`と`model`が別項目）と形が違う。分解して判定するのは 仕様の無い推測になるため、本指示書の範囲外とした（fixturesの値を直すだけにとどめた） 12. **「fixturesの全ロボットが対応済み」テストは入れた**（`lib/format/__tests__/robot-model.test.ts`）。 理由: 段階3の成果（fixturesがP1スコープ通りPUDU CC1のみで揃っている）を固定できる利点が、 「将来fixturesに境界ケースを足したい日に落ちる」欠点を上回ると判断した。落ちた人が 「バグか意図した変更か」を区別できるよう、テスト名に 「意図的に未対応機種を足したい場合はこのテストごと見直すこと」を明記した 13. **シードの`devices`が3行→1行になった**（`maker_id=1` / `model_name='CC1'`。 指示書M `2-9`の検算期待値`d=3`はこれで`d=1`に更新される。実測で確認済み） 14. **`MAKER_NAMES`の`Keenon`（`2`）は残した**（D-085の暫定採番はそのまま）。 ユーザーが「Keenon製品は将来やる可能性がある」と明言しているため 15. **`d-watch-api.yaml`は変更していない**。理由: `supported`はサーバーのデータではなく DFA側の静的な対応表を画面（フロント）が引くだけであり、レスポンスに`supported`を 足すとAPI契約の変更になりTeamWorks側との調整が発生する。範囲が広がるため見送った 16. 実測値: 着手前 **28ファイル / 572テスト**（`tsc`エラー0 / `lint`0）→ 完了後 **29ファイル / 587テスト 全パス**（+1ファイル / +15テスト）。 `npx tsc --noEmit`エラー0。`npm run lint`0 #### `CLAUDE.md` §1への追記 ★**追記した**★。P1スコープ表に「対応機種」の行を1行足した （「PUDU CC1のみ（将来候補: PUDU MT1 / Keenon C30 / C40。`lib/config/index.ts`の `ROBOT_MODELS`が正）」）。§1以外は触っていない（`git diff CLAUDE.md`で確認。 末尾の「This is NOT the Next.js you know」ブロックは無傷）。 #### 段階5の動作確認について（★環境の制約と代替手段★） ★**このセッションにはブラウザ操作手段（Cursorの`preview_start`等）が無いため、 指示書が前提とする目視確認は行えなかった**★。以下で代替し、限界も明記する。 - `npm run dev`をバックグラウンドで起動し、`curl`で`/api/facilities`・`/api/clean-logs`の JSONレスポンスを取得。ただし`FacilitiesScreen.tsx`は`"use client"`でクライアント側 `useEffect`によるデータフェッチのため、**`curl`で取得した`/facilities`のHTMLには 読み込み中プレースホルダしか出ず、ロボット行・バッジは含まれない**（実測。 `grep`で確認: 取得したHTMLに含まれるのは`読み込み中`の1件のみ）。 ★**したがってバッジのテキストを画面のHTMLから直接目視・grepすることはできなかった**★ - 代替として、本番の`isSupportedModel()`を実際に呼び出し、`curl`で取得した `/api/facilities`のJSON（フロントが受け取るのと同じデータ）に対して 「未対応バッジが何個出るはずか」を計算するスクリプトを都度実行した （フロントのロジックを再実装せず、本番関数をそのまま使っている点が単体テストとの 違い）: - `USE_FIXTURES=true`（既定）: 0個（期待どおり）。`facility_id=5`が2台・`facility_id=7`が 3台・総施設数12であることも`/api/facilities`のJSONで確認した - `USE_FIXTURES=false` + 検証用ロボット1台（`devices.model_name='MT1'`）を `dwatch_local`に投入: 1個（期待どおり。`facility_id=1`の新規ロボットが検出された） - 検証用データ削除 → `npm run seed:local`で復元 → 再度0個であることを確認 （消し忘れ検知）→ `USE_FIXTURES`を`true`に戻し、再起動後もう一度0個であることを確認 - `/api/clean-logs`のJSON（`per_page=200`分）で`model_name`が全件`"PUDU CC1"`であることも確認 （ただし総件数280件中200件分のみ。fixtures本体（`lib/fixtures/clean-logs.ts`）は `grep`で"Keenon"/"Phantas"が0件であることを直接確認済みなので、これは補助的な確認） - ★**ダーク/ライト・JP/EN の切替は`ThemeProvider`が素の`useState`（クライアント側の 状態）で持っており、URLクエリ・Cookieの類が無い**★（`components/theme/ThemeProvider.tsx` 実測）。★**このためcurlでは4通りの切替を一切再現できず、目視確認は行えていない**★。 バッジのJSXは`c.wn`（`THEME_TOKENS[theme]`由来）を使っており生の色コードは無いこと、 および`t("未対応")`が`lib/i18n.ts`に登録済みであることをコードレビューで確認したのみ - dev サーバのログ（stdout）にエラー・警告が出ていないことを`grep`で確認した（0件） - 検証用データは削除済み・`npm run seed:local`で復元済み・`USE_FIXTURES`は`true`に 戻し済み・devサーバは停止済み（ポート3000のプロセスが残っていないことを`netstat`で確認） --- ### D-088 `[確定]` 指示書K（エラー値を変換せず生値で表示する）を実行した D-077 項1・項2・項4（エラー種別を変換せず生値で表示する）と、D-078 項2 / D-082（B2/B3の 暫定値承認）を実装に落とした。段階0〜9 ＋ 段階7-B（全11段階）をすべて実施。 着手前確認は「なし」（B2/B3の扱いはD-078項2で、位置づけはD-082でユーザーが事前に確定済み）。 #### 実施した段階とコミット | 段階 | 内容 | コミット | |---|---|---| | 段階0 | 前提の確認（コミットなし） | — | | 段階1 | `d-watch-api.yaml` からエラー種別enumを撤去。meta方針を決定 | `b33b40d` | | 段階2〜5 | `ErrorType`型の撤去・ソート順の作り直し・画面の色分けフォールバック・fixturesを実データ形式に | `67e7014` | | 段階6 | 色分けの重複実装（`AlertsScreen.tsx`の`robotStatusColor`）を`lib/theme-status.ts`に一本化 | `0474448` | | 段階7 | `DsAlert.detail`を落とす（D-065 Q1-3の残作業） | `bd10bac` | | 段階7-B | B2の発火条件を設定値に外出しし、暫定値`Handrail Lifted`を入れる | `2287fa3` | | 段階8 | 最終確認（コミットなし） | — | | 段階9 | 本記録・push | 本コミット | #### ★段階2〜5を1コミットにまとめた（指示書の当初想定から変更）★ 指示書は「段階2〜4で1コミット／段階5で1コミット」の2コミット構成を想定していたが、 実際には1コミットにまとめた。 **理由**: `ErrorType`型（`lib/types/index.ts`）を削除すると、`lib/fixtures/__tests__/reports.test.ts` の `import type { ErrorType, ... }` がコンパイルエラーになる。このテストファイルの `ALL_ERROR_TYPES`／`ErrorType`参照の削除は指示書上は段階5の作業だが、段階5を分離した 状態のままでは段階4単独で`npx tsc --noEmit`がエラー0にならない（両者が不可分）。 指示書自身が段階2〜4を1コミットにまとめた理由（「型変更はコンパイルが通らないと切れない」） と全く同じ論理が段階5にも及ぶため、当初の分割から外れて段階2〜5を合体させた。 これにより「段階ごとに検証が通ってからコミットする」（D-050）という原則は崩さずに済んだ。 実装内容そのもの（何を変更したか）は指示書の指定どおりで、コミットの粒度だけが変わっている。 #### 記録すべき事項（指示書Kが指定した17項目） 1. 指示書Kを実行した（D-077項1・項2・項4の実装）。詳細は上表のとおり 2. **`ErrorType` unionを別名で残さず削除した**。別名（`export type ErrorType = string`）は 「7値のどれか」という誤解を後任に残すため（指示書の案Bを採らず案Aを採用） 3. **同値時のタイブレークを`type`（生値）の文字列昇順にし、`localeCompare`を使わなかった**。 ロケール依存を持ち込まないため。`error_type`はPUDU由来のASCII識別子で、単純な`<`比較で 決定的な順序が得られる。目的は「画面の順序がリロードで変わらないこと」であって 「人間にとって自然な並び」ではない 4. **`meta`を返すかどうかの判断（段階1-3）**: 案A（当方の推奨）を採用し、`meta`を返さないままにした。 根拠を「7分類固定でページングの余地がない」から「エラー種別の内訳は集計結果であり全件返す。 ページングが要るほどの種別数にはならない見込み」に書き換えた（`d-watch-api.yaml`の `/reports/error-breakdown`description・`app/api/reports/error-breakdown/route.ts`の コメントの両方に反映）。★実データで種別が数十に膨らむ可能性があるため、 実DB接続後に件数を実測して再判断すること★（受領済みの24値が実態と一致する保証はない） 5. **`label`に生値を入れ、画面に英語識別子がそのまま出ることが意図した挙動である**。 `d-watch-mock.jsx:751-757`の日本語ラベル（「ハンドルアップ」「LostLocation」等）から 意図的に外れた（`CLAUDE.md` §5「モックが文言の正」に対する明示的な例外。D-077のユーザー 指示が上位のため）。`label`を残す理由は将来TeamWorchから正式な表示名が来たときの受け皿 6. fixtures（`lib/fixtures/reports.ts`の`errorCounts`）に**未知の値**（`UnknownErrorFromCloud`）と **空文字**（`""`）のケースを1件ずつ足した。前者はERROR_TONEのフォールバック確認用、 後者は画面が落ちないこと・ソートが落ちないことの確認用（label空欄で行が視覚的に潰れるのが 現状の挙動。直すには実データの値が要る） 7. 色分けを`lib/theme-status.ts`に一本化し（`AlertsScreen.tsx`の`robotStatusColor`を削除）、 マッピングを`lib/config/index.ts`の`ROBOT_STATUS_TONES`（設定値）に外出しした。 フォールバックがグレー（`c.txD`）であることをdocstringに明記。実データ接続後は 実際に出現する値を突き合わせてこの表に追記する 8. `DsAlert.detail`を落とした（D-065 Q1-3の残作業）。YAML/型/fixtures(12件)/画面/CSSから削除。 ★`alert_type`の「種別」列を落とすかは別途ユーザー判断が要る★ （`security_off`は`security_statuses`由来で制御盤のアラートではなく、 「制御盤アラートは1種類だけ」という前提が成立しないため） 9. **段階7-B（B2/B3）を実施した**。D-078項2の承認に基づく。 `lib/config/robot-status-match.ts`を独立ファイルにした理由: `lib/config/index.ts`は judge系の閾値（`GRADE_THRESHOLDS`等）を持ち、ここに統合すると不要な依存が広がる （指示書Iの`lib/config/allowed-ips.ts`と同じ理由） 10. **`Handrail Lifted`は暫定値である**。受領済みの`error_type`24値リストに含まれていない。 ユーザーも「〜だと思いますが」と述べており確定ではない。「暫定で変更のおそれはあります」 とユーザーが明言している（D-078項2原文） 11. **B3のマッチ配列は空のままにした**（値が未判明。発火しないのが現在の期待挙動）。 `lib/fixtures/clean-logs.ts`の「オフライン」3行は、B3が発火しないことの検証ケースとして そのまま残した（R3/R4は連続日数ベースなので影響を受けない） 12. **マッチはtrim + 大小文字無視にした**。理由: `Handrail Lifted`は空白入りで、他24値の PascalCase（`EmergencyStop`等）と形が違う。`error_type`の値の形が1種類ではない 可能性があり、表記ゆれで取りこぼすため（D-074） 13. **申し送り: 実データに接続できたら、`error_type`に`Handrail Lifted`が実在するかを 最優先で確認すること**。参照用アカウントは2026-09-08に受領済み（D-078項1）。 ★ただしホスト名が未受領のため、本記録時点ではまだ接続できない★ 14. 実測値: `npm test` 30ファイル / 603テスト（着手前基準29ファイル/587テストから増加。 段階2〜5で+5、段階6で+5、段階7-Bで+6）。`npx tsc --noEmit` エラー0。`npm run lint` 0 15. D-082を踏まえ、**「B2/B3に入れた値は暫定であり、正しく発火させることは段階7-Bの 目的ではなかった」**。「アドバイスは連続で清掃失敗したときのものですね、それなら 一旦そのままの文字列で出して、後々修正する形にします」というユーザー判断（D-082項1）に 沿った実装。実データで`error_type`を数えた後に設定値を差し替える予定（D-082項5）。 見つからなければ`prismaSource実装前チェックリスト.md` §H の保留質問をTeamWorksに送る 16. **アドバイスの主軸R1〜R4はB2/B3の不発火の影響を受けない**（R1は初回の出発失敗、 R2は単日の完了率×で発火する。連続を見るのはR3/R4だけ。`CLAUDE.md` §4.5）。 したがってB2/B3の優先度は「中」だが、スコープはP1のまま（D-039 / D-082項3） 17. `prismaSource実装前チェックリスト.md` §B / §H のB2・B3の記載は消していない （「静かに発火しなくなる」性質は優先度が下がっても変わらないため。D-082項3） #### 既存の誤記を直した - `docs/decisions.md:1350`（本改訂前）の「`:1160`」誤記を訂正した（上記の第4節参照。 実体はかつて`:1205`にあったenumで、D-088で撤去済み） - `docs/handoff/analysis/error-type-mapping.md:40`は「enumが撤去された」ことを追記した - `docs/fixtures.md:129`は段階5で生値方針に書き換え済み #### 事前レビューで指摘されていた行番号の食い違い（答え合わせ） 作業開始前に、直前セッションから「段階5の行番号3箇所は改訂漏れ」との指摘があった。 着手直前に自分で`grep`して確認した実測値は次のとおりで、指摘どおりズレていた: | 対象 | 指示書の記載 | 実測（着手時点） | |---|---|---| | `errorCounts` | `:448-463` | `:455-464` | | `ALL_ERROR_TYPES` | `:59-73` | `:65`から開始 | | 「7種を重複なく網羅」テスト | `:291-300` | `test(...)`が`:292`、削除対象行が`:298` | その他の行番号（`d-watch-api.yaml:1205`のenum、`lib/types/index.ts:197/207`の`ErrorType`、 `lib/db/index.ts:150-151/254-255`、`lib/judge/advice.ts:79-85`、 `lib/config/advice-rules.ts:108/111/118/121`）は事前レビューどおり実測と一致していた。 #### 動作確認で代替した方法とその限界 ★このセッションの環境にはCursorの「Browser pane」機能が無いため★、目視確認は `USE_FIXTURES=true npm run dev`（バックグラウンド起動）＋`curl`で代替した。 - `/api/reports/error-breakdown`: 英語識別子（`EmergencyStop`等）が変換されず生値のまま 返ること、空文字ケース（`type:""`）と未知の値ケース（`UnknownErrorFromCloud`）が 同数（count:1）で文字列昇順（`""`→`UnknownErrorFromCloud`）にソートされていることを レスポンスJSONで直接確認した - `/reports`・`/ds-alerts`ページはHTTP 200で応答することを確認した （クライアントコンポーネントがuseEffectでフェッチする構成のため、curlで取得した 素のHTMLにはフェッチ結果が反映されない。★実際の見た目・色分け・行の潰れ方の 目視確認はできていない★。この点はテスト（`lib/__tests__/theme-status.test.ts`・ `lib/reports/__tests__/query.test.ts`・`lib/fixtures/__tests__/reports.test.ts`）で ロジックレベルの担保に置き換えている） - `/api/ds-alerts`: レスポンスJSONに`detail`フィールドが存在しないことを確認した - 確認後、devサーバは停止済み（ポート3000にプロセスが残っていないことを`Get-NetTCPConnection`で確認） #### push `origin/develop`へpush済み（`main`へは push していない）。push後の `git log --oneline -1 origin/develop`とローカルHEADの一致、`git status -sb`の ahead/behind無しをpush直後に確認した（実測値は作業報告に記載）。 --- ### D-089 `[確定]` 指示書O（エラー種別ラベルの折り返しと空値表示）を実行した D-088（指示書K。生値表示への切替）が表面化させた2つの表示上の問題（ラベルの折り返し・ 空値の空白表示）を直した。仕様変更ではなく表示の修正であり、D-077（エラー種別を変換しない） とは矛盾しない。着手前確認は「なし」（2件とも2026-09-09にユーザーが回答済み。段階1から そのまま進めた）。 #### 実施した段階とコミット | 段階 | 内容 | コミット | |---|---|---| | 段階1 | `.errorLabel`に`overflow-wrap: anywhere`を追加（CSSのみ） | `beec8e3` | | 段階2 | 空値の代替文言を返す純粋関数`formatRawLabel()`を`lib/format/raw-label.ts`に新規作成 | `d53cc5d` | | 段階3 | `ReportsScreen.tsx:440`に適用・`lib/i18n.ts`に対訳を追加 | `2f25d19` | | 段階4 | 動作確認・本記録・push | 本コミット | #### 記録すべき事項（指示書Oが指定した7項目） 1. **生値方針（D-077/D-088）で表面化した「表示」の問題であり、仕様変更ではない**。 `error_type`の値そのものは一切加工していない。変えたのは「画面上でどう見せるか」だけ （折り返し＝CSS、空値の代替文言＝表示専用の純粋関数） 2. **クランプせず折り返しにした理由**: `-webkit-line-clamp`等で切り詰めると、 英語識別子の後半が読めなくなり「生値をそのまま見せる」というD-077の趣旨と矛盾する。 `.errorRow`に高さ固定が無いため、折り返しで行が伸びても崩れない（指示書O 禁止事項1） 3. **代替文言は`(値なし)`を選んだ**（指示書Oの推奨案どおり）。「その他」はD-067（破棄済み）の 「未知の値をその他に寄せる」方針と紛らわしく、「不明」は「エラー内容が不明」とも読めて しまうため避けた。「文字列が入っていれば生値のまま、入っていなければその他や不明としても 矛盾しない」というユーザー回答（2026-09-09）に沿いつつ、3案のうち最も事実ベースな `(値なし)`を採った 4. **`(値なし)`は「値が空である」という事実の表示であり、D-077の「推測でマッピングしない」に 反しない**。値が入っている場合は`formatRawLabel()`が一切加工しない（トリムのみ許容。 指示書O禁止事項2）。空/非空の分岐だけで、値の中身を7分類等に推測変換することはしていない 5. **前後に空白がある値はトリムして返すことに決めた**（`lib/format/__tests__/raw-label.test.ts` ケース6で固定）。理由: `lib/format/robot-model.ts`が比較前にトリムしている前例を踏襲した。 指示書Oの禁止事項2「トリム以外の変換をしない」＝トリムは唯一許容される変換という読みに沿う。 表示上も先頭・末尾の空白による見た目のズレを避けられる 6. **`width: 110px`は変えていない**。指示書Oの「実測した識別子は110px幅で2行に収まる」を そのまま採用し、他の列とのバランスを崩さない方針（指示書Oの既定推奨）に従った 7. **申し送り**: 同じ問題（空値だと空のバッジが出る）は`status_1h`／`status_30m`／ `robot_status`にも起こりうるが、fixturesに空値が無く実データで空になるか未確認のため 今回は適用しない（指示書O 禁止事項4）。次にこれらの表示を扱う指示書を作るときに、 `formatRawLabel()`の流用を検討すること #### 実測値 `npm test` 31ファイル / 610テスト（着手前基準30ファイル/603テストから+1ファイル/+7テスト。 段階2で追加した`lib/format/__tests__/raw-label.test.ts`の7ケース分）。 `npx tsc --noEmit`エラー0。`npm run lint`0（段階1〜3のいずれの時点でも0を維持）。 `grep -n "ERROR_TONE" components/features/reports/ReportsScreen.tsx`の該当2行の**内容**は 無変更（`const ERROR_TONE: Record<...> = {`と`tone={ERROR_TONE[item.type] ?? "pr"}`）。 ★行番号自体は58行目・453行目に変わった★（着手前は57行目・447行目）。理由はERROR_TONEより 前の行に`import { formatRawLabel } from "@/lib/format/raw-label";`を1行追加し、かつ `.errorLabel`のJSXにコメント3行を足したため。ERROR_TONE自体の定義・使用箇所は触っていない （禁止事項5）。`lib/fixtures/reports.ts`・`d-watch-api.yaml`・`prisma/schema.prisma`・ `lib/db/`は無差分（`git diff --stat`で確認済み）。 #### 動作確認で代替した方法とその限界 ★このセッションの環境にはCursorの「Browser pane」機能が無いため★、`npm run dev` （バックグラウンド起動、`USE_FIXTURES`未設定＝既定のfixturesモード）＋`curl`で代替した。 - `/api/reports/error-breakdown?period=weekly&year=2026&month=9&week=2`: レスポンスJSONに `{"type":"","label":"","count":1,...}`が引き続き含まれることを確認した （サーバ側は生値のまま返す契約に変更が無いことの確認。表示側の代替文言はクライアント側の `formatRawLabel()`が担う） - `/reports`はHTTP 200で応答することを確認したが、★`ReportsScreen.tsx`は`"use client"`の クライアントコンポーネントで初回フェッチが`useEffect`で走るため、curlで取得した素のHTMLには フェッチ結果もCSSの折り返し結果も反映されない。以下は目視確認できていない★: - 確認項目1（`RobotHardwareErrorToAdmin`が2行に折り返りバーに重ならないこと） - 確認項目2（空文字の行に`(値なし)`が出ること） - 確認項目3（行の高さが伸びても件数・パーセント・バーの縦位置がずれないこと） - 確認項目4（ダーク/ライト） - 確認項目5（JP/EN切替でのUI上の見た目） - 確認項目6（`read_console_messages`によるコンソールエラー0件の確認。このツール自体が この環境に無い） 上記はロジック単体では担保している: `lib/format/__tests__/raw-label.test.ts`が `formatRawLabel()`の6ケース（生値そのまま／空文字／空白のみ／null／undefined／トリム）を 固定し、`lib/i18n.ts`の対訳キー追加は`translate()`の完全一致ロジック（既存実装）に そのまま乗るためコードレビューで妥当性を確認した。CSSの折り返し指定（`overflow-wrap: anywhere`） と非クランプは`ReportsScreen.module.css`のソースを直接確認した - 確認項目7（`/dashboard`が「9/10完了」であること）は`curl`で代替した: `GET /api/dashboard`のレスポンスに`"schedule_progress":{"planned":10,"completed":9,"rate":90}` を確認した（本指示書の変更はダッシュボードに触れていないため回帰は想定していないが、 実測で確認した） - devサーバのログ（`next dev`の標準出力）に、上記リクエストに対するアプリケーションエラーが 出ていないことを確認した（クエリパラメータ不備による最初の1件の`422`を除く。 これはサーバ側の検証エラーで想定内）。ただし★クライアント側（ブラウザのJS実行時）の コンソールエラーはサーバログに出ないため確認できていない★ - 確認後、devサーバは停止済み（`Get-NetTCPConnection -LocalPort 3000`で該当プロセスが 無いことを確認） #### push `origin/develop`へpush済み（`main`へは push していない）。push後の `git log --oneline -1 origin/develop`とローカルHEADの一致、`git status -sb`の ahead/behind無しをpush直後に確認した（実測値は作業報告に記載）。 --- ### D-090 `[確定]` 第2歩は依存グラフで3系統に分ける。未決20件を洗い出した `prismaSource` の残り10メソッド（D-086 の「第2歩」）を1本の指示書にまとめる予定で調査したが、 ★**8本（点検記録2本を除く）をまとめて書くことは不可能と判明した**★。 ★仕様が未決の項目が20件あり、その多くが `cleanLogs` と `dsAlerts` の `security_off` 側に 集中している★ためである。 > ★**採番についての注記**★: 本項は当初 `D-089` として起票する指示だったが、 > ★`D-089` は既に指示書O の実行記録が取得済み（`docs/decisions.md:3225`）★だったため > `D-090` を採った。★D-070 の冒頭が警告している「追記直前に最終番号を確認する」を > 守ったことで衝突を回避した事例★。★指示書O の `D-089` は履歴なので繰り上げていない★。 #### 1. ★8メソッドをまとめて書けない★ - 点検記録2本（`inspections` / `inspectionDetail`）は ★D-072 項7（`docs/decisions.md:1052`）で 「最後に回す」と決定済み★なので、そもそも第2歩以降の対象外 （`lib/db/index.ts:239-244`。呼び出している API ルートも ★無し★ — `docs/handoff/analysis/prismaSource実装前チェックリスト.md:415-416`） - 残り8本のうち ★仕様が確定しているのは `dsDevices` と `dsAlerts` の disconnected 側だけ★ （取得元は D-065 Q1-2 / Q1-3（`:483-484`）・D-067 項1（`:604`）・D-070 D-3（`:1133`）で確定） - ★`docs/handoff/analysis/prismaSource実装前チェックリスト.md:358` が既に 「★**まとめて書かない**★。1メソッドずつ、§F の表の順（依存の少ない順）で進める」と 定めている★。★今回の調査はその指示の裏付けを取り直した形になった★ #### 2. ★分割方針（依存グラフに沿って切る）★ ★「明細4本 / サマリ4本」で割らない理由★: ★`continuousProblems`（サマリ側）は `cleanLogs`（明細側）の連続日数算出に構造的に依存する★（`ContinuousProblem.consecutive_problem_days` は `CleanLogItem.consecutive_problem_days` と同じ「スケジュール存在日ベースの連続」。D-026）ため、 その線で切ると**2つの束が相互依存する**。 | 段 | 対象 | 根拠 | |---|---|---| | ★第2歩★ | `dsDevices` + `dsAlerts`（★disconnected のみ★） | 取得元が D-065 / D-067 / D-070 で確定済み。judge も集計も連続日数も不要。★影響画面が F-06 / F-07 に閉じており、失敗しても被害が小さい★ | | 第3歩 | `dsAlerts`（security_off）+ `cleanLogs` | ★`cleanLogs` を先に仕上げるべき理由★: B2 / B3 の発火と色分けの検証がここで初めて可能になる（D-082 / D-088） | | 第4歩 | `prechecks` + `reportKpis` + `facilityPerformance` + `errorBreakdown` | `prechecks` は `cleanLogs` の join（`clean_timetables` × `clean_statuses`）を流用できる。サマリ3本は共通構造（`facility_summaries` / `facility_error_summaries`） | | 第5歩 | `continuousProblems` | ★`cleanLogs` の連続日数算出に依存。単独では書けない★ | #### 3. ★★未決事項20件★★ ★「誰が決めるか」の3分類★: ★**DFA**★ = DFA 側で決められる / ★**TW**★ = TeamWorks に聞くべき / ★**実データ**★ = 実DBに繋げば分かる。 **`cleanLogs` 関連（5件）** | # | 内容 | 誰が決めるか | |---|---|---| | 1 | ★`status_1h` / `status_30m` の具体的な値★（`lib/types/index.ts:64-65`）。取得元は D-070 D-2（`:1132`）で判明（待機中・充電中は `robots.status`、ハンドルアップ以降は `robot_error_reports`）だが、★「60分前時点のスナップショット」を保持するカラムが schema に存在しない★。`clean_timetables.precheck = 1 / 2`（`prisma/schema.prisma:540`）の行と `clean_statuses` / `robot_error_reports` から導出する規則の決定が必要 | ★DFA★ | | 2 | ★`departed` の判定規則が未定義★（`lib/types/index.ts:67`）。`clean_statuses.started_at`（`prisma/schema.prisma:419`）/ `clean_status`（`:405`）/ `clean_task_reports` のどれを使うか、どこにも記述が無い | ★DFA★ | | 3 | ★`CleanLogItem.id` の出所が不明★（`lib/types/index.ts:52`。`number`）。`clean_statuses.id` か `clean_timetables.id` か、記述が無い | ★DFA★ | | 4 | ★`model_name` の連結規則が未定義★。fixtures は `"PUDU CC1"` の1文字列だが、`Facility.robots[]` では `maker` / `model` が別フィールド（`lib/db/index.ts:190-195`）。区切り文字・順序を決める必要がある | ★DFA★ | | 5 | ★`completion_rate`★（`lib/types/index.ts:69`。★丸める前の生値★を要求）。`clean_statuses.clean_ratio` は ★`Int @db.UnsignedTinyInt`（整数）★（`prisma/schema.prisma:418`）なので、そのまま入れると `CLAUDE.md` §4.3 の「表示用に丸めた値で判定しない」に違反する。★`clean_area` / `task_area`（`Decimal(12,6)`。`:413-415`）から再計算する必要がある★ | ★DFA★ | **`prechecks` 関連（3件）** | # | 内容 | 誰が決めるか | |---|---|---| | 6 | ★`severity` の `precheck` 1/2 対応は推定のみ★。`PrecheckSeverity` は `"precheck_1h"` / `"precheck_30m"` / `"launch_failed"` の3値（`lib/types/index.ts:118`）だが、★「`precheck = 1` が60分前」と明記した記述はどこにも無い★（D-065 Q2 は「0: 本清掃 / 1: 1回目 / 2: 2回目」としか言っていない）。★`launch_failed` の DB 表現も未定義★ | ★DFA★（1/2 の対応は ★TW★ 照会が確実） | | 7 | ★`PrecheckItem.id` の型★。DB は `varchar(50)`、API 契約と型定義は `number`（`lib/types/index.ts:133`）。★方針は D-070 1-2（`:1130`）で確定済み（`error_id` を使い string のまま）だが実装が未着手★ | ★DFA★（決定済み・未実装） | | 8 | ★`battery_level` の「事前チェック時点」の値が取れない★（`lib/types/index.ts:148`）。`robots.battery`（`prisma/schema.prisma:210`）は ★現在値のみ★で履歴が無い | ★DFA★ | **`dsAlerts`（security_off）関連（2件）— ★これが第2歩から security_off を外す理由★** | # | 内容 | 誰が決めるか | |---|---|---| | 9 | ★`id` / `device_serial` / `resolution_status` / `responded_at` / `resolved_at` / `memo` の6つに対応するカラムが `security_statuses`（`prisma/schema.prisma:362-377`）にも `security_status_histories`（`:379-392`）にも存在しない★。両テーブルが持つのは `id` / `facility_id` / `section_id` / `status` / `reported_at` / `created_at` だけ。★D-042 の書き込み許可4カラムにも含まれない → DFA 独自ストアが要る可能性★（D-065 Q1-1（`:482`）の備考と同じ構図） | ★DFA★ | | 10 | ★`detected_at` の導出規則が未定義★。`security_statuses.reported_at` は ★`@updatedAt`★（`prisma/schema.prisma:368`）なので「いつから0か」が取れない（更新のたびに現在時刻で上書きされる）。`security_status_histories` を遡って「status が 0 になった最初の行」を探す必要がある | ★DFA★ | **サマリ系（4件）** | # | 内容 | 誰が決めるか | |---|---|---| | 11 | ★`reportKpis` / `errorBreakdown` が customer 版と facility 版のどちらを読むか未決★。`customer_summaries`（`prisma/schema.prisma:623`）/ `facility_summaries`（`:649`）/ `customer_error_summaries`（`:675`）/ `facility_error_summaries`（`:695`）の4本があり、画面の粒度（P1 は顧客がドンキ1社のみ）との対応が決まっていない | ★DFA★ | | 12 | ★★D-022（`:104`。率カラムは小数のまま格納）が実DDLに反映されていない★★。実DDL の `operation_ratio` / `launch_ratio` / `clean_ratio` / `error_ratio` は ★すべて `Int @db.UnsignedTinyInt`（整数）★（`prisma/schema.prisma:634-637` / `:660-663`）。★`CLAUDE.md` §4.3・§7 の「表示用に丸めた値で判定すること」の禁止と正面から衝突するため、同じ行にある `*_count` / `*_area`（`:629-633`）から再計算する必要がある★。★しかもテーブル定義書に計算式が書かれておらず、DFA の再計算値と TeamWorks のバッチ値が一致する保証がない★ | ★★TW★★（照会候補の筆頭） | | 13 | ★`ContinuousProblem.summary`（自由文）の生成規則が未定義★（`lib/types/index.ts:197`）。D-068 でモックの「完了率{n}%」から自由文に変えた経緯があるが、★DB からどう組み立てるかは決めていない★ | ★DFA★ | | 14 | ★当期その場集計を `prismaSource` でやるか `lib/reports/query.ts` でやるか未決★。`selectKpiRow`（`lib/reports/query.ts:325-333`）は当期を判定するが ★「器だけ」で分岐しても null を返すだけ★（同 `:319-323` のコメント） | ★DFA★（項15 と一体） | **設計判断（2件）** | # | 内容 | 誰が決めるか | |---|---|---| | 15 | ★`lib/db/index.ts:59-63` の方針コメント「フィルタや集計はこの層では行わず、APIルート側で組み立てます」と、`consecutive_problem_days`（全期間走査）・当期KPI（その場集計）が衝突する★。★`DataSource` は引数を取らない契約（`lib/db/index.ts:74-82`）なので API ルート側では期間を渡せない★ → ★「判定も集計も `prismaSource` 内でやる」と決めるのが妥当だが、方針コメントの書き換えを伴う★ | ★DFA★ | | 16 | ★judge を `prismaSource` の中で呼ぶこと自体は妥当★。`CLAUDE.md`「判定ロジックは切替の外側に置く」は ★「`lib/judge/` を fixtures 用と Prisma 用に分岐させるな」の意味★であり、「`lib/db/` の外で呼べ」という意味ではない（`lib/judge/index.ts:3-5` の冒頭コメントが同じことを書いている） | ★DFA★（本項で確定と扱ってよい） | **実データを見れば分かるもの（4件）** | # | 内容 | 誰が決めるか | |---|---|---| | 17 | サマリの `week=6` が実在するか / 月跨ぎ週が2行に分割されているか（D-071 / `CLAUDE.md` §4.7。第5回 X-3 で照会中） | ★実データ★ | | 18 | `robot_error_reports.error_type` の実値（D-077 / D-088。B2 の暫定マッチ値 `Handrail Lifted` が実在するか） | ★実データ★ | | 19 | `dwatch_local` の実テーブル一覧（★今回の調査ではDBに接続していない★） | ★実データ★ | | 20 | `prisma/schema.prisma` の FK 48本 vs `dwatch_local` の 50本 の差（D-066 / D-086 項2。★差の2本は未特定★） | ★実データ★ | #### 4. ★★新たに見つかった fixtures の不整合（3件。うち2件は未記録）★★ | # | 内容 | 状態 | |---|---|---| | 1 | ★「メガバリューマート緑野第二店」（`facility_id: 12`）★ — 施設マスタの実名は「フレッシュタウン湖畔店」（`lib/fixtures/facilities.ts:204`）。`lib/fixtures/ds-devices.ts:111` と `lib/fixtures/ds-alerts.ts:145` の2箇所 | ★既知★（D-086 項1 / 項15 に記録済み。指示書M でも言及） | | ★2★ | ★「バリューマート城南店」（`facility_id: 10`）★ — 施設マスタの実名は「フレッシュタウン大和店」（`lib/fixtures/facilities.ts:169`）。`lib/fixtures/ds-devices.ts:103` と `lib/fixtures/ds-alerts.ts:132` の2箇所 | ★**未記録の新発見**★ | | ★3★ | ★施設12 は `d_security_enabled: false`（`lib/fixtures/facilities.ts:212`）かつ `robots: []`（`:213`）→ `sections` が0件★（シードがロボットごとに section を作るため。`scripts/seed-local-db.ts:207-224`）★なのに D-Sec デバイス `DS-012` とアラート `id: 10` を持っている★ | ★**未記録の新発見**★。★`controls.section_id` は NOT NULL の FK（`prisma/schema.prisma:182` / `:193`）なので、そのままシードすると FK 違反で止まる★ | ★これらは DB 経由にすれば構造的に消える★ — `controls` / `control_reports` / `control_error_histories` は いずれも `facilities` / `sections` への FK を持つ（`prisma/schema.prisma:192-193` / `:332-334` / `:352-354`）ので、 ★施設名は結合で取ることになり、手書きの文字列を入れる余地が無くなる★。 ★ただし #3 は第2歩で判断が要る★（`DS-012` を落とす / 施設12 に section を作る / 別施設に付け替える）。 #### 5. 帰結 - ★第2歩の指示書（`docs/handoff/指示書P_ローカルDBで動かす第2歩_DSec.md`）を D-Sec 2メソッドに絞って作成した★ - ★未決20件のうち、TeamWorks に聞くべきは項12（サマリの率カラムの型と計算式）が筆頭★。 ★第7回の確認書を作るときの候補として記録する★ - ★DFA 側で決められるものが多い★（項1〜4、6、9、10、13〜16）。 ★第3歩以降の着手前に順次決める必要がある★ --- ### D-091 `[確定]` 2026-09-09 のユーザー判断4件（出発判定 / 率の小数化 / セキュリティ無効の扱い / precheck の値） ★D-090（`docs/decisions.md:3325`）で洗い出した未決20件のうち4件が解決した★。 以下、ユーザー回答の原文を項ごとに引用する。 > ★**採番についての注記**★: 追記直前に `grep -n "^### D-0" docs/decisions.md | tail -3` を実行し、 > 最終番号が `D-090`（`:3325`）であることを実測してから `D-091` を採った > （D-070 冒頭・D-090 冒頭が警告している二重採番の回避手順）。 #### 1. ★出発の判定は DB の値を使う（D-090 項2 の解決）★ ユーザー原文: ``` ★B. 「出発した / しなかった」の決め方が決まっていない★、これは時間は設定で変わるので DBからきた失敗かどうかを判断軸にしてください ``` - ★当方で「予定時刻＋猶予30分」を計算して判定しない★ - 理由（ユーザーの言）: ★猶予時間は設定値なので変わる★（`lib/config/index.ts:31` の `LAUNCH_GRACE_MINUTES = 30`）。★当方が計算すると、設定を変えた瞬間に過去のログの判定まで 変わってしまう★ - ★DB 側が持っている「失敗かどうか」の状態を読む★ - ★実装時に確認すべきこと★: ★どのカラムが「失敗」を表すのかを実データで特定する★。 候補は `clean_statuses.clean_status`（`prisma/schema.prisma:405`。 ★-1=清掃完了(セキュリティ無効) / 0=清掃前 / 1=清掃中 / 2=清掃終了(セキュリティ有効)★。 TeamWorks 回答 A-2。D-057）だが、★「出発しなかった」を表す値がこの4値に見当たらない★。 ★`clean_statuses` に行が作られないことが「未実施」を意味する可能性がある★ — ★これは実データで確認する★ - ★D-090 項2 は解決したが、「DB のどの値を見るか」は実データ接続後に確定する★ #### 2. ★★率カラムが小数第一位まで持つことになった（D-090 項12 の解決）★★ ユーザー原文: ``` ★C. 丸めた数字で判定してしまう危険★、これはいまDB側と話して、数値は86.5のように 小数第一位まで持つことになりました ``` - ★TeamWorks 側で対応してもらえることになった★。★D-022（`:104`。率カラムは小数のまま格納）が 実DDLに反映される★ - ★これで整数（`Int @db.UnsignedTinyInt`）による丸め問題は解消する★ （現行は `prisma/schema.prisma:634-637` / `:660-663` がすべて整数） - ★仕様の境界値はすべて小数第一位までなので、第一位まであれば判定は正しく行える★: `CLAUDE.md` §9.4 の境界値（90.0 / 90.1 / 70.0 / 70.1 / 10.0 / 9.9）は ★すべて第一位までで表現できる★ - ★ただし1点だけ残る★: ★`90.04%` のような第二位以下は `90.0` に丸められる★ため、 ★本来◎（90超）のものが○になりうる★。★同じ行にある `clean_area` / `task_area` （`prisma/schema.prisma:413-415`。`Decimal(12,6)`）から計算すれば完全な生値が得られる★ので、 ★境界の厳密さが要る場面ではそちらを使う選択肢が残る★。 ★実務上の差はごく小さいので、まず小数第一位の値をそのまま使い、問題が出たら面積から 計算する方針とする★ - ★★確認が必要なこと（第7回の候補）★★: - ★いつ反映されるか★ - ★反映後の DDL をもらえるか★（★現行の `prisma/schema.prisma` は整数のままなので `db pull` のやり直しが要る★。D-056） - ★既存データはどうなるか★（遡って小数に戻るのか、新規分だけか） - ★TeamWorks のバッチの計算式★（★テーブル定義書に計算式が書かれておらず、 当方の再計算値と一致する保証がない件は未解決のまま★。D-090 項12 の後段） #### 3. ★★セキュリティ無効はアラートから外す方向（D-090 項9・項10 に影響）★★ ユーザー原文: ``` ★D. セキュリティ無効アラートは「対応状況」を保存できません★、これに関しては一旦保留にしてください、 セキュリティが無効であっても異常ではないのでアラートを出すようなものでもないので、 「未対応 / 対応中 / 対応済み」を切り替えも削除する可能性があります D-secアラートはサーバーとの生死報告が途切れたなどのエラーのみでアラートを出すのみにできるように 内部で調整します ``` - ★セキュリティ無効は「異常ではない」ので、アラートとして出すものではない★というのがユーザーの整理 - ★D-Sec アラートは「サーバーとの生死報告が途切れた」等のエラーのみにする方向で内部調整中★ - ★★これは「保留」であって確定ではない★★。★内部調整の結果を待つ★ - ★帰結: D-090 項9（`security_off` の対応状況を保存する場所が無い）は、 `security_off` 自体がアラートでなくなれば消滅する★。★項10（`detected_at` の導出）も同様★ - ★指示書P（第2歩。`docs/handoff/指示書P_ローカルDBで動かす第2歩_DSec.md`）が `disconnected` のみを実装する方針にしていたのは、結果的にこの方向と一致する★ - ★★確認が必要なこと★★: ★ダッシュボードのセキュリティバナー（赤い警告帯）をどうするか★。 `lib/dashboard/aggregate.ts:113` の `computeSecurityBanner()` が ★`:117` で `alert_type === "security_off"` に絞っている★ため、`security_off` が無くなると ★バナーが出なくなる★。`docs/spec.md:31` は「D-Secアラートバナー（セキュリティ無効施設の赤警告）」を F-01 の機能として挙げており、★D-032（`:198`）の表示設定にも ON/OFF 項目がある★。 ★「アラートではないが、ダッシュボードには出す」のか「バナーごと廃止する」のかを決める必要がある★ - ★影響範囲（実測。`security_off` を含む箇所）★: | ファイル | 該当 | |---|---| | `lib/types/index.ts` | `:304` `DsAlertType` / `:308` `DsAlertTypeFilter`（`:314` で `alert_type` に使用） | | `lib/dashboard/aggregate.ts` | `:113-123` `computeSecurityBanner()`（絞り込みは `:117`） | | `lib/ds-alerts/query.ts` | `:11`（`TYPE_FILTERS` の要素） | | `lib/fixtures/ds-alerts.ts` | `:8`（説明コメント）/ `:22` `:61` `:77` `:90` `:129` `:142` `:168` の7件 | | `components/features/ds-alerts/DsAlertsScreen.tsx` | `:25`（ラベル「セキュリティ無効」）/ `:107`（種別フィルタの `