# データの流れ — 画面1〜5（2026-09-17） 対象は ★ダッシュボード（F-01） / 清掃詳細ログ（F-02） / アラート（F-03） / レポート（F-04） / 清掃面積（D-141）★ の5画面です。 残り5画面（D-Secログ / D-Secアラート / 施設ロボットマスタ / スケジュール / システム管理）は ★別の文書の担当★で、本書には含みません。 --- ## 0. この文書の読み方 ### 0.1 何のための文書か 「この列の数字はどこから来て、途中でどの関数を通り、どんな形で画面に出るのか」を ★実物の値と型つき★で1本の縦線として追えるようにしたものです。 各列は次の順で並べます。 ``` 【DBの列】 テーブル.カラム 型 / NULL可否（prisma/schema.prisma:NNN） ↓ 読む 【取得】 読み出している場所（file:line）と、そこに書かれている式 ↓ 型 【型】 API の型（lib/types/index.ts:NNN） ↓ API エンドポイントとレスポンスキー（d-watch-api.yaml:NNN） ↓ 整形 【整形】 表示整形の純粋関数（file:line）とシグネチャ ↓ 表示 【画面】 実際に描いている行（file:line） 【値の例】 出所つきの実物の値 ``` ### 0.2 ★値の出所の凡例★（`CLAUDE.md` §6-6） 本書に出る具体的な値には、必ず次の3つのどれかの印を付けます。 ★印の無い数字は本書には書きません★。 | 印 | 意味 | 出所 | |---|---|---| | ★シード由来★ | ★当方が作ったサンプルデータの値★ | `lib/fixtures/*.ts` / `scripts/seed-local-db.ts` | | ★構造由来★ | ★型・DDL・API契約から読み取れる値★（データではなく器） | `prisma/schema.prisma` / `d-watch-api.yaml` / `lib/config/index.ts` | | ★記録済み実測★ | ★`docs/decisions.md` / `docs/handoff.md` に日付つきで記録済みの実測値★ | 決定番号と日付を併記する | ★「実測」と書くときは出所を必ず併記する★（`CLAUDE.md` §6-6）。 出所を書けない数字は「実測」と呼びません。 ### 0.3 ★★本番DBに入っているデータは当方のダミーです★★ - ★`133.125.238.144` / `clean_watch` は **本番DBそのもの**★（★D-148★。2026-09-17 ユーザー確認）。 ★検証用の別DBではありません★。過去の文書が「テストDB」「テスト環境」と呼んでいるのは誤りです。 - ★★そこに現在入っている行は、1行残らず当方の `scripts/seed-local-db.ts` 由来★★（★D-145★。 2026-09-17）。★先方由来なのは器（スキーマ・索引・型・サーバー変数・権限）だけ★です。 `customers` / `groups` には当方の★旧版シードの文字列（`テスト顧客001` / `テストグループ001`）★ まで残っていました。 - ★★したがって、本書は本番DBに接続していません★★。値はすべて ★fixtures（シード由来）★ か ★型・DDL（構造由来）★ か ★既に記録済みの実測値★ から採っています。 - ★本番DBの行数・分布・サマリバッチの実挙動を、本書の数字から推し量らないこと★ （D-111 項7 / D-145 / D-148）。 ### 0.4 ★共通の骨格★（5画面すべてに効く） ``` ブラウザ（components/features/…） ↓ apiFetch()（lib/api/client.ts） 自アプリの API ルート（app/api/…/route.ts） ↓ db.xxx() データ層（lib/db/index.ts の `db`） ↓ USE_FIXTURES で分岐（lib/db/index.ts:2476） ├─ fixtureSource（lib/db/index.ts:426〜）… lib/fixtures/*.ts を読む └─ prismaSource（lib/db/index.ts:655〜）… Prisma で MariaDB を読む ``` - `lib/db/index.ts:2476` — `export const db: DataSource = USE_FIXTURES ? fixtureSource : prismaSource;` - ★判定（`lib/judge/`）は切替の外側★ではなく ★両方の実装が同じ関数を通る★形になっています （`CLAUDE.md` §9.5 / D-044 / D-090 項16）。fixtures でも本番同等の判定が走ります。 - ★画面は判定をやり直さない★（`CLAUDE.md` §9.6）。◎○△×・L1〜L3・並び順は API が返した値を そのまま描きます。★画面がやるのは「丸め」と「日本語の組み立て」だけ★です。 ### 0.5 ★事故りやすい変換の境目（本書で繰り返し出てくる4つ）★ | # | 事故 | 何が起きるか | 本書で出る場所 | |---|---|---|---| | 1 | ★`??` を `\|\|` にする★ | `0` が `null` に化ける（`clean_error` の「正常」、面積の 0） | 1章・2章・5章 | | 2 | ★丸めてから判定する★ | 89.5 が ◎ になる／90.4 の ◎ が消える | 2章・4章 | | 3 | ★`null` と `[]` を混同する★ | 「0件ヒット」が「全件表示」に化ける（Prisma の `in: undefined`） | 全章 | | 4 | ★DBの DATETIME を「真の瞬間」と取り違える★ | 9時間ずれて境界の行が消える | 全章 | ★どれも例外もテスト失敗も出ません★。数字が静かに変わるだけです。 --- # 第1章 ダッシュボード（F-01） - 画面: `app/(dashboard)/dashboard/page.tsx` → `components/features/dashboard/DashboardScreen.tsx` - API: ★2本を並列に叩く★（`DashboardScreen.tsx:83-86`） - `GET /api/dashboard`（`app/api/dashboard/route.ts` / `d-watch-api.yaml:214`） - `GET /api/clean-logs?result=problem&date_from=当日&date_to=当日&per_page=5` （`DashboardScreen.tsx:77-82`） - ★コンパクト版清掃詳細ログは `/dashboard` には含まれません★（`d-watch-api.yaml:218-220`）。 ★`/clean-logs` を再利用する★ので、5列の中身は ★第2章と同じ縦線★ です。 ## 1.1 `GET /api/dashboard` のクエリパラメータ（`d-watch-api.yaml:221-227`） | キー | 型 | 既定 | 備考 | |---|---|---|---| | `date` | `string (date)` | ★当日（＝昨夜分）★ | `app/api/dashboard/route.ts:55` | | `group_id` | `integer` | なし | `parseMasterIdFilters()`（`app/api/dashboard/route.ts:61`） | | `customer_id` | `integer` | なし | 同上。`group_id` と同時指定は AND | ★★`route.ts:55` は `dateRaw || todayJst()` であって `??` ではありません★★ — ★`?date=`（値が空）だと `""` は `null` でも `undefined` でもないので `??` では既定に倒れず★、 `dbDateRange("", "")` で `start_at` の条件ごと消えて ★テーブル全件読みに戻ります★。 ★ここだけは `||` が正解★です（事故#1 の向きが逆になる唯一の箇所）。 ## 1.2 数値カード「成功 / 失敗 / 未実施 / 成功率」 ``` 【DBの列】 clean_status_histories.clean_error 型: Int @default(0) @db.UnsignedTinyInt（NOT NULL）（prisma/schema.prisma:487） 意味: 0=正常 / 1=異常(清掃未実施) / 2=異常(セキュリティ有効) / 3=異常(D-S制御盤異常) / 4=異常(清掃ロボット異常)（lib/config/index.ts:263-274） ★unsigned tinyint なのでコード表に無い 5〜255 も入りうる★ ↓ 読む 【取得】 lib/db/index.ts:896 const history = historyByTimetableId.get(key(row.id)); lib/db/index.ts:909 departed: !notExecutedFromHistory(history), lib/db/index.ts:918 completion_rate: completionRateFromHistory(history), ↓ 判定 【判定】 lib/db/clean-log-mapping.ts:152-157 notExecutedFromHistory(history: CleanResultLike | undefined): boolean → 履歴の行が無い（undefined） … true（＝出発失敗） → clean_error === 1 … true → 0 / 2 / 3 / 4 / 5以上 … false（＝出発した扱い） lib/db/clean-log-mapping.ts:184-192 completionRateFromHistory(h: (CleanResultLike & {clean_ratio:number}) | undefined): number | null → 行なし / clean_error===1 … null → それ以外 … clean_ratio の生値（丸めない） lib/judge/grade.ts:29-35 judgeGrade(rate: number | null): Grade ↓ 集計 【集計】 lib/dashboard/aggregate.ts:31-59 computeSummary(logs: CleanLogItem[]): DashboardResponse["summary"] - !departed → not_executed++ - grade が ◎ or ○ → success++ - grade が △ or × → failed++ - success_rate = 分母0なら null、でなければ success / 分母 * 100（★丸めない★） ↓ 型 【型】 DashboardResponse["summary"]（lib/types/index.ts:1081-1087） { success: number; failed: number; not_executed: number; success_rate: number | null } ↓ API 【API】 GET /dashboard の summary（d-watch-api.yaml:236-247） ↓ 整形 【整形】 lib/judge/grade.ts:43-46 displayRate(rate: number | null): string null → "-" / それ以外 → `${Math.round(rate)}%` ↓ 画面 【画面】 components/features/dashboard/DashboardScreen.tsx:231-257（StatCard 4枚） 成功 : String(data.summary.success) sub=`/ ${totalLogsToday}件` 失敗 : String(data.summary.failed) クリックで /detail-log へ 未実施 : String(data.summary.not_executed) 成功率 : displayRate(data.summary.success_rate) sub=`目標: 95%` components/ui/StatCard.tsx:24-34 【値の例】 ★シード由来★（lib/fixtures/clean-logs.ts:94-107 の当日10件から） 当日の boundaryCases は 90.1/90.0/89.5/70.1/70.0/10.1/10.0/9.9/0/null。 判定は ◎◎○○○△△×××（未実施1件）。 → success=5 / failed=4 / not_executed=1 / success_rate = 5/10*100 = 50 → 表示「50%」 ★構造由来★: 目標値 95 は SUCCESS_RATE_TARGET（lib/config/index.ts:491） ``` ★★`failed` が「出発した△×」に限られている理由★★（`lib/dashboard/aggregate.ts:28-30`）— 未出発の行を `not_executed` と `failed` の両方に数えると ★二重計上★ になるためです。 したがって ★`success + failed + not_executed` が当日の行数★ になり、 `DashboardScreen.tsx:205-207` の `totalLogsToday` がそれを計算しています。 ★★「/ N件」の N は `schedule_progress.planned` とは別概念★★（D-049。`DashboardScreen.tsx:201-204`）。 ## 1.3 スケジュール進捗カード ``` 【DBの列】 clean_schedules.weeks 型: String @db.VarChar(7)（prisma/schema.prisma:556） clean_schedules.inactive 型: Int @default(0) @db.UnsignedTinyInt（:564） ↓ 読む 【取得】 app/api/dashboard/route.ts:93 db.schedules()（★引数を取らない契約★） app/api/dashboard/route.ts:124 filterRowsByFacilityIds(schedules, facilityIds) ↓ 型 【型】 Schedule.weekdays: string（7桁。日月火水木金土、清掃する曜日=1） Schedule.active: boolean（lib/types/index.ts:964-975） ↓ 集計 【集計】 lib/dashboard/aggregate.ts:84-103 computeScheduleProgress(logs: CleanLogItem[], schedules: Schedule[], date: string) : DashboardResponse["schedule_progress"] planned = schedules.filter(s => s.active && s.weekdays[dow] === "1").length completed = logs.filter(r => r.departed).length ★「完了」ではなく「出発」★ rate = planned === 0 ? null : completed / planned * 100 ★dow は lib/dashboard/aggregate.ts:67-72 の weekdayIndex() が Date.UTC で出す★ （`new Date("YYYY-MM-DD").getDay()` は実行環境のTZで答えが変わるので使わない） ↓ 型 【型】 DashboardResponse["schedule_progress"]（lib/types/index.ts:1088-1095） { planned: number; completed: number; rate: number | null } ↓ 画面 【画面】 components/features/dashboard/ScheduleProgressCard.tsx:21-29 rate === null → 「本日の清掃予定はありません」（★0% のバーを出さない★。D-049） それ以外 → `{completed} / {planned} 完了` + components/ui/ProgressBar.tsx:17-27 percent が NaN / Infinity なら 0 にクランプ、0〜100 にクランプ 【値の例】 ★シード由来★: fixtures の `lib/fixtures/schedules.ts` の active な行のうち、 当日の曜日ビットが "1" の件数が planned になる。 ★構造由来★: weekdays は7文字固定（prisma/schema.prisma:556 の varchar(7)）。 ``` ★★`planned` をスケジュール由来にしている理由★★（`lib/dashboard/aggregate.ts:77-79` / D-049）— 清掃ログの行数を使うと、収集処理が止まって当日の行が0件のときに ★「本当に定休日」と「収集処理の障害」が区別できなくなる★。 食い違いは `app/api/dashboard/route.ts:138-147` が `logEvent("warn", { event: "data.anomaly" })` で 記録します（★原因の断定は書かない★。`docs/logging-design.md` §7）。 ## 1.4 セキュリティバナー ``` 【DBの列】 （D-Sアラート由来。★実DB上の `section_name` の取得元が未確定★ — lib/types/index.ts:865-870 の注記のとおり fixtures では暫定のダミー値） ↓ 取得 【取得】 app/api/dashboard/route.ts:94 db.dsAlerts() app/api/dashboard/route.ts:125 filterRowsByFacilityIds(dsAlerts, facilityIds) ↓ 集計 【集計】 lib/dashboard/aggregate.ts:113-123 computeSecurityBanner(alerts: DsAlert[]): DashboardResponse["security_banner"] 条件: alert_type === "security_off" && resolution_status !== "done" 返すのは facility_name / section_name / since（= detected_at）の3つだけ ★detail / memo は載せない★（自由記述は §4 の記録禁止フィールド） ↓ 型 【型】 DashboardResponse["security_banner"]（lib/types/index.ts:1108-1112） Array<{ facility_name: string; section_name: string; since: string }> ↓ 整形 【整形】 lib/format/date.ts:15-17 formatHm(iso: string): string → iso.slice(11, 16) ★Date に通さず文字列を切る★（ISO8601 +09:00 なので実行環境のTZに依存しない） ↓ 画面 【画面】 components/features/dashboard/SecurityBanner.tsx:22 「⚠ セキュリティ無効: {facility_name} {section_name}（{formatHm(since)}以降）」 ★0件なら null を返してバナーごと消す★（SecurityBanner.tsx:16） ヘッダの件数 Pill: DashboardScreen.tsx:217-219 → `D-Sec {n}件` 【値の例】 ★シード由来★: lib/fixtures/ds-alerts.ts の security_off 行。 ★`2026-09-17T01:20:00+09:00` → formatHm → `"01:20"`★（構造由来の変換規則） ``` ## 1.5 要レスキュー店舗カード（D-137 / 指示書AI） ★★モックに対応する画面がありません★★（`RescueRequiredCard.tsx:12-21`）。 ユーザー指示（2026-09-15）に基づく `CLAUDE.md` §5 の例外です。 ``` 【DBの列】 clean_timetables.start_at DateTime @db.DateTime(0)（prisma/schema.prisma:589） clean_status_histories.clean_error Int UnsignedTinyInt（:487） clean_status_histories.clean_ratio Float（double(4,1)）（:497） clean_status_histories.clean_area Float（double(12,6)）（:492） clean_status_histories.task_area Float（double(12,6)）（:491） ↓ 読む 【取得】 app/api/dashboard/route.ts:101 db.rescueRequired({ date, facility_ids: facilityIds }) prismaSource: lib/db/index.ts:1732〜 → loadConsecutiveInputs()（lib/db/consecutive-source.ts） fixtures : lib/db/index.ts:542〜 → rescueInputsFromCleanLogs()（lib/db/rescue-mapping.ts:47-64） ↓ 中間型 【型】 ConsecutiveInput（lib/db/clean-log-mapping.ts:292-319） { id: number; facility_id: number; scheduled_at: string; completion_rate: number | null; clean_area: number; task_area: number } ★clean_area / task_area は履歴が無ければ 0★（★null にしない★。 面積は「足し合わせる量」なので 0 を足すのが正しい。 lib/db/consecutive-source.ts:199-201 / lib/db/rescue-mapping.ts:60-61） ★★`??` を `||` にしないこと★★ — 面積は 0 が正当な値（事故#1） ↓ 判定 【判定】 lib/db/rescue-mapping.ts:98-191 buildRescueRequired(inputs, facilityNames, date) 1) date 以下で切る（:105。★date ちょうどで絞らない★ — R-1 は3日、R-3 は前回日が要る） 2) 連続日数は computeConsecutiveProblemDays() の値を使う（:110。★数え直さない★。D-109） 3) 施設ごとに judgeRescue() を呼ぶ（:140） lib/judge/rescue.ts:241-268 judgeRescue(input: RescueInput): RescueJudgement R-1 not_executed_streak : countNotExecutedStreak(days) >= RESCUE_THRESHOLDS.notExecutedDays（=3） （lib/judge/rescue.ts:177-184 / lib/config/index.ts:69-72） R-2 escalation_l3 : judgeEscalationLevel(consecutive) === "L3"（:193-195） R-3 completion_drop : (前回 − 当日) ÷ 前回 >= COMPLETION_DROP.dropRatio（=0.2） （:219-228 / lib/config/index.ts:48-51） lib/judge/rescue.ts:117-125 facilityDayRate(rows): number | null = completionRate(Σclean_area, Σtask_area) ← ★面積加重。単純平均ではない★ ★分母0は null★（lib/judge/kpi.ts:20-23） ↓ 型 【型】 RescueRequiredItem（lib/types/index.ts:1047-1072） { facility_id: number; facility_name: string; evaluated_on: string; reasons: RescueReason[]; not_executed_days: number; consecutive_problem_days: number; completion_rate: number | null; previous_completion_rate: number | null; drop_ratio: number | null } RescueReason = "not_executed_streak" | "escalation_l3" | "completion_drop" （★正は lib/judge/rescue.ts:34。lib/types は型ごと借りている（:11）★） ↓ API 【API】 GET /dashboard の rescue_required（★件数で切らない＝全件返す★。 app/api/dashboard/route.ts:155-157 / lib/db/rescue-mapping.ts:81-89） ↓ 画面 【画面】 components/features/dashboard/RescueRequiredCard.tsx :91 rescueVisibility(items, expanded)（lib/dashboard/rescue-visibility.ts:37-47） canToggle = items.length > RESCUE_INITIAL_VISIBLE（=5。lib/config/index.ts:102） ★★「超える」ときだけ true。ちょうど5件なら出さない★★（>= にしない） :99 件数表示は ★items.length（絞る前の総数）★ :112 facility_name :116-123 reasons を全部出す（★1つに丸めない★） :52-73 REASON_LABEL — ★日本語を作るのはこの層★（D-111） not_executed_streak → t("{n}日連続で未実施").replace("{n}", not_executed_days) escalation_l3 → t("連続問題レベル3（{n}日連続）") completion_drop → t("完了率が前回比{n}%低下") n = Math.round(drop_ratio * 100)（★表示のためだけに丸める★） drop_ratio === null なら「完了率が前回比で急落」 :131 判定日 evaluated_on（★リクエストの date とは限らない★） :135-139 完了率 displayRate(completion_rate) ＋（前回 displayRate(previous_completion_rate)） 【値の例】 ★構造由来★: 未実施3日連続の閾値 3（RESCUE_THRESHOLDS.notExecutedDays） ★構造由来★: 急落の閾値 0.2（COMPLETION_DROP.dropRatio）→ 「20%低下」 ★シード由来★: 前回 30% → 当日 18% は drop_ratio = (30-18)/30 = 0.4 → ラベルは「完了率が前回比40%低下」 （★差で見ると「12ポイント」だが、ユーザーは比を選んだ★。lib/config/index.ts:37-44） ★記録済み実測★: ★件数上限を撤廃した理由は「実データで7件中2件が黙って消えていた」★ （指示書AJ §1 / lib/config/index.ts:80-86。★ただしその「実データ」は当方のシード由来★。 D-145 の訂正対象に含まれるため、★件数そのものを本番の規模の根拠に使わないこと★） ``` ★★母集団の罠★★（`app/api/dashboard/route.ts:66-72` / 指示書AK §7-2）— ★数値カード・スケジュール進捗・セキュリティバナー・要レスキューの4つに ★同じ `facilityIds`★ を 渡すこと★。★どれか1つを渡し忘れると「この屋号の昨夜の成績」と「要レスキュー」が別集団の話になる★。 ★例外もテスト失敗も出ない★ので `app/api/__tests__/master-filter-dashboard-reports.test.ts` で 固定してあります。 ★★要レスキューだけ母集団が違う（意図）★★ — ★当日に清掃予定が無い施設も含む★ （`lib/types/index.ts:1113-1123` / `DashboardScreen.tsx:271-272`）ので、 `summary` の件数と一致しなくて構いません。 ## 1.6 コンパクト版清掃詳細ログ（5列） `DashboardScreen.tsx:284-294` が `CleanLogTable` に `compact` を渡します。 | 出す列 | 落とす列 | |---|---| | 施設名 / 予定 / 出発 / 完了率 / 判定 | 機種・シリアル・日付・1h前ST・30分前ST・清掃結果 | `components/features/detail-log/CleanLogTable.tsx:24-38` にこの分担が書かれています。 ★列の中身の縦線は第2章と同一★です（同じコンポーネントなので分岐は `compact` だけ）。 `colSpan` は `compact ? 5 : 11`（`CleanLogTable.tsx:168` / `:221`）。 ★compact でも行は展開する★（`CleanLogTable.tsx:30-34` / D-143 §3 #6）。 展開時に `GET /api/clean-logs/{id}/advice` を叩きます（`DashboardScreen.tsx:124-126`）。 --- # 第2章 清掃詳細ログ（F-02） - 画面: `app/(dashboard)/detail-log/page.tsx` → `components/features/detail-log/DetailLogScreen.tsx` - API: `GET /api/clean-logs`（`app/api/clean-logs/route.ts` / `d-watch-api.yaml:339`） - 付随: `GET /api/clean-logs/{id}/advice`（`:468`）/ `GET /api/clean-logs/{id}/areas`（`:524`）/ `GET /api/clean-logs/export`（`:399`） ## 2.1 クエリパラメータの実物（`d-watch-api.yaml:343-385`） | キー | 型 / enum | 既定 | 画面での出どころ | |---|---|---|---| | `date_from` | `string (date)` | 省略時は直近1日 | `DetailLogScreen.tsx:122`（初期値 `todayJst()`。`:60`） | | `date_to` | `string (date)` | 同上 | `:123`（初期値 `todayJst()`。`:61`） | | `group_id` | `integer` | — | `appendClassificationParams()`（`:130`） | | `customer_id` | `integer` | — | 同上 | | `facility_name` | `string`（部分一致・★記号と大小文字を無視★） | — | `:125`（300ms debounce。`:98-104`） | | `model` | `string`（部分一致・大小文字のみ無視） | — | `:126` | | `serial` | `string`（部分一致・大小文字のみ無視） | — | `:127` | | `result` | `problem \| critical \| all` | `all` | `:124`（★画面の初期値は `problem`★。`:62`） | | `page` | `integer` | 1 | `:132` | | `per_page` | `integer` | 50（`PAGINATION.defaultPerPage`。`lib/config/index.ts:326`） | `:131` | ★日付範囲の上限は 731日★（`MAX_DATE_RANGE_DAYS`。`lib/config/index.ts:360`。★構造由来★）。 ★730 ではなく 731 なのは、2年のあいだにうるう日が入りうるため★。 超過は 422（`lib/clean-logs/query.ts:107-117`）。 ★上限がかかるのは `date_from` と `date_to` の **両方** が指定されたときだけ★。 422 の実物（`lib/clean-logs/query.ts:110-115`）: ```json { "error": { "code": "validation_failed", "message": "date_from〜date_toは731日以内で指定してください", "details": { "date_to": ["指定された範囲は900日です"] } } } ``` ## 2.2 ルートの処理順（`app/api/clean-logs/route.ts`） ``` 1. parseCleanLogQuery(searchParams) :50 ← 422 の入口（lib/clean-logs/query.ts:80-150） 2. loadConsecutiveDaysMax() :61 ← 表示上限（読めなければ既定 30 で続行） 3. 施設名 → 施設ID / 分類 → 施設ID を並列解決 :78-80 intersectFacilityIds(nameIds, masterIds) :81 ★AND。片方を捨てない★ 4. db.cleanLogs({ id: null, date_from, date_to, facility_ids }) :83-89 5. filterCleanLogs(rows, query) :98 ★規則の「正」はここ。SQL はその写し★ 6. ページ切り出し → capCleanLogs() :105 ★上限は最後にかける★ 7. { items, meta: { total, page, per_page } } :107-110 ``` ★★`facility_ids` の `null` と `[]` は別物★★（★事故#3★）— `null` = 絞らない / `[]` = 照合したが1件も当たらなかった（＝0件）。 `app/api/clean-logs/route.ts:75-77` と `lib/db/index.ts:729-736` の両方に注意書きがあります。 Prisma の `in: undefined` は ★条件が消えて `WHERE 1=1`★ になります。 ## 2.3 列ごとの縦線 ### (a) 施設名 ``` 【DBの列】 facilities.facility_name String @db.VarChar(400)（prisma/schema.prisma:129） ↓ 読む 【取得】 lib/db/index.ts:739-749 include: { facility: true } lib/db/index.ts:901 facility_name: row.facility.facility_name ↓ 型 【型】 CleanLogItem.facility_name: string（lib/types/index.ts:205） ↓ 画面 【画面】 components/features/detail-log/CleanLogTable.tsx:185 {r.facility_name} 【値の例】 ★シード由来★ "メガバリューマート三ツ橋中央ショッピングセンター店" （lib/fixtures/clean-logs.ts:104。★長い施設名の表示崩れ確認用★） ``` ★★`cleanLogs()` は `facility.deleted_at` で絞っていません★★（`lib/db/index.ts:673-678`）。 ★論理削除された施設のログも返るのが現状の挙動★なので、 ★施設名→IDの解決（`loadFacilityNameIndex()`）も `deleted_at` で絞りません★（★罠7★）。 絞ると ★その施設名で検索したときにログが静かに消えます★。 ### (b) 機種 ``` 【DBの列】 devices.maker_id Int @db.UnsignedTinyInt（prisma/schema.prisma:82） devices.model_name String @db.VarChar(100)（:83） ↓ 読む 【取得】 lib/db/index.ts:866 const robot = row.section.robots[0]; lib/db/index.ts:902 model_name: formatModelName(robot.device.maker_id, robot.device.model_name) ↓ 変換 【変換】 lib/db/clean-log-mapping.ts:27-29 formatModelName(makerId: number, modelName: string): string → `${MAKER_NAMES[makerId] ?? String(makerId)} ${modelName}` MAKER_NAMES = { 1: "PUDU", 2: "Keenon" }（lib/config/index.ts:597-600） ★★未知の maker_id は String(maker_id) をそのまま出す★★ （「不明」等に潰さない。対応表に足す必要があることに気づけるようにするため） ↓ 画面 【画面】 components/features/detail-log/CleanLogTable.tsx:186（compact では出さない） 【値の例】 ★構造由来★ maker_id=1, model_name="CC1" → "PUDU CC1" ★構造由来★ maker_id=9（表に無い）, model_name="X1" → ★"9 X1"★ ★シード由来★ fixtures の既定値は "PUDU CC1"（lib/fixtures/clean-logs.ts:50） ``` ★P1 は 1清掃エリア = 1ロボット★（`CLAUDE.md` §8）。★0台なら空文字を返さず例外★ （`lib/db/index.ts:867-871`。fail-loud）。 ### (c) シリアル ``` 【DBの列】 robots.serial_number String @db.VarChar(20)（prisma/schema.prisma:231） ↓ 読む 【取得】 lib/db/index.ts:903 serial_number: robot.serial_number ★robots は where: { deleted_at: null } で絞っている★（lib/db/index.ts:744） ↓ 画面 【画面】 CleanLogTable.tsx:187 【値の例】 ★シード由来★ "8111R5628060011"（lib/fixtures/clean-logs.ts:95） ``` ★検索の照合規則★（`lib/clean-logs/query.ts:163-178`）: - ★施設名だけ `includesFoldName()`★ — ★記号（中点・長音・空白・ハイフン類）と大小文字を無視★ - ★機種・シリアルは `includesFoldPlain()`★ — ★大小文字のみ★。★記号は除かない★ （除くと `PUDU-CC1-0001` が `10001` でヒットし、★桁の境界が消える★。指示書AG D-2） ### (d) 日付 / 予定（`scheduled_at`） ★★ここが事故#4 の本丸です★★。 ``` 【DBの列】 clean_timetables.start_at DateTime @db.DateTime(0)（prisma/schema.prisma:589） ★中身は「日本時間の壁時計値」★（TeamWorks 第8回 A2。2026-09-11 受領） ↓ 読む 【取得】 lib/db/index.ts:906 scheduled_at: jstIsoFromDb(row.start_at) ↓ 変換 【変換】 lib/format/date.ts:95-97 jstIsoFromDb(date: Date): string = toJstIso(fromDbJst(date)) lib/format/date.ts:67-69 fromDbJst(date: Date): Date = new Date(date.getTime() - DB_DATETIME_OFFSET_MINUTES * 60_000) DB_DATETIME_OFFSET_MINUTES = 9 * 60（lib/config/index.ts:193） lib/format/date.ts:37-46 toJstIso(date: Date): string → "YYYY-MM-DDTHH:mm:ss+09:00" ★★2段を1つの式に潰さないこと★★（lib/format/date.ts:88-90）— 潰すと「DBのタイムゾーン」という設定値が式から消え、lib/config を変えても効かなくなる ★性質★: 戻り値の桁は ★DBの生値そのもの★。 DB が `2026-09-11 02:00:00` なら `"2026-09-11T02:00:00+09:00"` ↓ 型 【型】 CleanLogItem.scheduled_at: string（ISO8601 +09:00）（lib/types/index.ts:209） ↓ 整形 【整形】 lib/format/date.ts:8-12 formatMd(iso): string → iso.slice(5,7)/iso.slice(8,10) を数値化 "2026-08-27T02:00:00+09:00" → "8/27" lib/format/date.ts:15-17 formatHm(iso): string → iso.slice(11,16) → "02:00" ↓ 画面 【画面】 CleanLogTable.tsx:188 日付 {formatMd(r.scheduled_at)} CleanLogTable.tsx:189 予定 {formatHm(r.scheduled_at)} 【値の例】 ★シード由来★ at(0,"02:00") → その日の "…T02:00:00+09:00" → 日付 "9/17" / 予定 "02:00" ``` ★★なぜ補正が要るのか★★（`lib/format/date.ts:51-62`）— Prisma の MariaDB アダプタは ``new Date(`${value}Z`)`` で ★UTC とみなして★ `Date` にします （設定で変更できない）。補正しないと `Date` は ★真の瞬間より9時間先★ を指し、 `isFutureSchedule()` の比較が狂って ★深夜2時の清掃が翌朝の確認時刻でも「まだ未来」と判定されて 画面から消えます★（「翌朝確認型」の運用を直撃する）。 ★★逆向き（クエリの条件）も同じ★★: ``` lib/db/date-range.ts:50-67 dbDateRange(from: string | null, to: string | null): { gte?: Date; lt?: Date } range.gte = toDbJst(parseDate(from)) range.lt = toDbJst(parseDate(to) + 1日) ★to は「その日を含む」ので翌日 00:00 未満★ ★lte: その日 23:59:59 にしないこと★（DATETIME の桁が増えたとき 23:59:59.5 が静かに落ちる） parseDate("2026-09-08") = 2026-09-07T15:00:00.000Z（真の瞬間） toDbJst(parseDate("2026-09-08")) = 2026-09-08T00:00:00.000Z（DBの壁時計値として渡せる形） ``` ★★ローカルDBではこの間違いが1件も表に出ません★★（`lib/db/date-range.ts:19-24`）— ★記録済み実測（指示書AC C-6。★当方のシード由来★）★: `clean_timetables` 1,044行の `start_at` は ★0時:210 / 1時:516 / 2時:288 / 3時:30 で、15時以降が0件★。 9時間ずらしても日付が変わらない時間帯にしかデータが無いため、★補正を忘れても件数が1件も変わりません★。 だから `lib/db/__tests__/date-range.test.ts` に「壁時計 20:00 の清掃」の合成データがあります。 ★そのテストを消さないこと★。 ### (e) 1h前ST / 30分前ST ``` 【DBの列】 robot_error_reports.error_type String @db.VarChar(100)（prisma/schema.prisma:328） robot_error_reports.errored_at DateTime? @db.DateTime(0)（:332。★nullable★） clean_timetables.precheck Int @default(0) @db.UnsignedTinyInt（:596） 0 = 本清掃 / それ以外は「本清掃開始の何分前か」の分数そのもの（D-112） ↓ 読む 【取得】 lib/db/index.ts:777-785 事前チェック行を parent_id で引く（select は id/parent_id/precheck の3列） lib/db/index.ts:799-805 そのエラー行を clean_timetable_id で引く lib/db/index.ts:879-888 precheck の生値 → エラー配列 の Map に詰め替えて statusColumnsFromPrecheckRows() に渡す ↓ 変換 【変換】 lib/db/precheck-mapping.ts:125-132 statusColumnsFromPrecheckRows(m: ReadonlyMap): [string, string] = PRECHECK_MINUTES_BEFORE.map(minutes => robotStatusFromErrors(m.get(minutes) ?? [])) PRECHECK_MINUTES_BEFORE = [60, 30]（lib/config/index.ts:214。★構造由来★） lib/db/clean-log-mapping.ts:54-60 robotStatusFromErrors(errors: readonly RobotErrorLike[]): string - 0件 → ROBOT_STATUS_STANDBY = "Standby."（lib/config/index.ts:322。★末尾のピリオド込みが原文★） - 1件以上 → errored_at が最新の1件の error_type を ★生値のまま★ ↓ 型 【型】 CleanLogItem.status_1h / status_30m: string（lib/types/index.ts:215-217） ★実DB上の取得元・値の形式は未確定★（D-077 項3）。日本語6値は fixtures 由来の暫定値 ↓ 画面 【画面】 CleanLogTable.tsx:192 / :197 lib/theme-status.ts:24-29 statusColor(theme: ThemeName, status: string): string Object.hasOwn(ROBOT_STATUS_TONES, status) でないと c.txD（グレー）にフォールバック ROBOT_STATUS_TONES（lib/config/index.ts:676-683） 待機中:"ok" / 充電中:"pr" / ハンドルアップ:"ng" / 緊急停止:"ng" / オフライン:"ng" / セキュリティ有効:"ac" 【値の例】 ★シード由来★ "待機中" → 緑（ok）。"オフライン" → 赤（ng） ★構造由来★ "EmergencyStop"（実データで来うる英語識別子）→ ★表に無いのでグレー★ ★構造由来★ "Standby."（エラー0件の代替値）→ ★あえて表に足していない★のでグレー ``` ★★D-077 の帰結★★（`CLAUDE.md` §4.8）— ★`error_type` も `robots.status` も変換しません★。 画面には ★英語識別子がそのまま出る★のが意図した挙動で、 ★`lib/theme-status.ts` の色分けは日本語6文字列の完全一致なので、生値では全部グレーになります★。 ★それも含めて現在の期待挙動★です（`lib/config/index.ts:658-674` / `lib/theme-status.ts:9-13`）。 ★`Object.hasOwn()` を先に通す理由★（`lib/theme-status.ts:14-22`）— `constructor` / `toString` / `__proto__` のような `Object.prototype` のメンバー名が `status` として 来ると、添字アクセスが ★`undefined` ではなくプロトタイプ側の関数を拾い★、 `Pill` が `background: undefined22` を出して ★グレーにすらフォールバックしません★。 ### (f) 出発（✓ / ✗） ``` 【DBの列】 clean_status_histories の行の有無 ＋ clean_error（prisma/schema.prisma:487） ↓ 判定 【判定】 lib/db/index.ts:909 departed: !notExecutedFromHistory(history) lib/db/clean-log-mapping.ts:152-157 notExecutedFromHistory(history: CleanResultLike | undefined): boolean if (!hasCleanResult(history)) return true; ← ★行が無い＝出発失敗★ return history.clean_error === CLEAN_ERROR.notExecuted; ← ★=== 1 のみ★ ★★`!== 0` なら異常、と書かないこと★★（指示書U 落とし穴3）— `=== 1` の形だから ★コード表に無い 5以上は自動的に「未実施ではない」側に落ちる★ ↓ 型 【型】 CleanLogItem.departed: boolean（lib/types/index.ts:222） ↓ 画面 【画面】 CleanLogTable.tsx:200-202 {r.departed ? "✓" : "✗"}（色は departedOk / departedNg） 【値の例】 ★構造由来★ clean_error=0 → departed=true（✓） ★構造由来★ clean_error=1 → departed=false（✗） ★構造由来★ clean_error=2/3/4 → ★departed=true（✓）★（未実施とは違う扱い。ユーザー回答 2026-09-10） ★構造由来★ 履歴の行が無い → ★departed=false（✗）★（D-107 設計3-C。fail-loud） ★シード由来★ fixtures は departed が入力で clean_error が導出（lib/fixtures/clean-logs.ts:66） → ★fixtures に clean_error === null の行は存在しない★（null は DB 経由でだけ出る） ``` ★★「履歴の行が無い」を出発失敗にするのは推測ではなく決定★★ （`lib/db/clean-log-mapping.ts:116-128` / D-107 設計3-C）— ★過去なのに履歴の行が無いのはデータ収集処理の障害★なので、 ★行ごと結果から消す（fail-silent）と運用担当は「何かが足りない」ことにすら気づけません★。 ★帰結として過剰検知になる（結果がまだ書かれていないだけの清掃も出発失敗として出る）★のは ★意図して選んだ側★です。 ★★未来の予定を外す `isFutureSchedule()` は必須★★（`lib/db/clean-log-mapping.ts:263-265`）— `clean_timetables` には ★1週間分の予定がまとめて登録される★ので、 外すと ★最大7日先までの予定が全部「出発失敗」になります★。 ★記録済み実測（★当方のシード由来★）★: 3日後の予定を1行入れると `launch_failed` が 13 → 14 件に増えた（`lib/db/clean-log-mapping.ts:236`）。 ★同時刻（`start_at === now`）は「来ていない」に入れない★（`>` であって `>=` ではない）。 ### (g) 清掃結果（★D-146 項2 / 指示書AO で追加された列★） ``` 【DBの列】 clean_status_histories.clean_error 型: Int @default(0) @db.UnsignedTinyInt（NOT NULL）（prisma/schema.prisma:487） 意味: 0=正常 / 1=異常(清掃未実施) / 2=異常(セキュリティ有効) / 3=異常(D-S制御盤異常) / 4=異常(清掃ロボット異常) （lib/config/index.ts:263-274。原文は docs/handoff/analysis/table-definitions-02-clean-error.md:213） ↓ 読む 【取得】 lib/db/index.ts:913 clean_error: history?.clean_error ?? null ★★`??` を `||` にすると 0（正常）が null に化ける★★（★事故#1★。 tsc も lint も捕まえない。lib/db/index.ts:911-912） ↓ 型 【型】 CleanLogItem.clean_error: number | null（lib/types/index.ts:242） ★null = 「履歴の行が無い（清掃結果が記録されていない）」★ ↓ 整形 【整形】 lib/format/clean-result.ts:34-39 formatCleanResult(cleanError: number | null): string if (cleanError === null) return CLEAN_RESULT_NOT_DEPARTED_LABEL; // "出発失敗" return cleanErrorLabel(cleanError); lib/format/clean-result.ts:35 に ★「`??` を `||` にしないこと」★ の注記 lib/config/index.ts:302-304 cleanErrorLabel(code: number): string → CLEAN_ERROR_LABELS[code] ?? String(code) CLEAN_ERROR_LABELS（lib/config/index.ts:286-292。★定義書の原文ママ。括弧は半角★） ↓ 画面 【画面】 CleanLogTable.tsx:208 {formatCleanResult(r.clean_error)} ★セルの値は t() に通さない★（CleanLogTable.tsx:203-207）— 原文ママのラベルに対訳を当てると何が原文だったか分からなくなる。 コード表に無い値は String(code) なのでそもそも訳せない（D-077） 【値の例】 ★構造由来★ null → "出発失敗" ★構造由来★ 0 → "正常" ★構造由来★ 1 → "異常(清掃未実施)" ★「出発失敗」とは別表示★ ★構造由来★ 2 → "異常(セキュリティ有効)" ★構造由来★ 5 → ★"5"★（★「その他」「不明」に潰さない★。D-089 項3 / D-104 項2） ★シード由来★ fixtures は 0 か 1 しか作らない（lib/fixtures/clean-logs.ts:66） ``` ### (h) 完了率 ``` 【DBの列】 clean_status_histories.clean_ratio 型: Float @default(0.0)（★実DDL は double(4,1)★。D-094）（prisma/schema.prisma:497） ★取得元で 100 に丸められるため上限は 100★（TeamWorks 回答 B-3。:494-496） ↓ 読む 【取得】 lib/db/index.ts:918 completion_rate: completionRateFromHistory(history) ↓ 変換 【変換】 lib/db/clean-log-mapping.ts:184-192 completionRateFromHistory(h: (CleanResultLike & { clean_ratio: number }) | undefined): number | null 行が無い → null notExecutedFromHistory() → null それ以外 → h.clean_ratio（★丸めない生値★） ★★`history ? history.clean_ratio : null` に戻さないこと★★（lib/db/index.ts:915-917）— 未実施行の clean_ratio は既定値の 0 なので、★null が 0（＝「0%で実施した」）に化ける★。 ★判定はどちらも × なので画面もテストも赤くならない★（D-107 落とし穴1） ↓ 型 【型】 CleanLogItem.completion_rate: number | null（lib/types/index.ts:247） ↓ 整形 【整形】 lib/judge/grade.ts:43-46 displayRate(rate: number | null): string null → "-" / それ以外 → `${Math.round(rate)}%` ↓ 画面 【画面】 CleanLogTable.tsx:209 {displayRate(r.completion_rate)} 【値の例】 ★シード由来★（lib/fixtures/clean-logs.ts:94-107） 90.1 → "90%" / 89.5 → "90%" / 10.0 → "10%" / 9.9 → "10%" / 0 → "0%" / null → "-" ``` ### (i) 判定（◎○△×） ``` 【判定】 lib/db/index.ts:947 grade: judgeGrade(draft.completion_rate) lib/judge/grade.ts:29-35 judgeGrade(rate: number | null): Grade rate === null → "×" rate >= GRADE_THRESHOLDS.excellent(90) → "◎" rate >= GRADE_THRESHOLDS.good(70) → "○" rate < GRADE_THRESHOLDS.poor(10) → "×" それ以外 → "△" GRADE_THRESHOLDS（lib/config/index.ts:18-25。★構造由来★） excellent: 90 / good: 70 / poor: 10 ★★境界はすべて「上のランクに入る」★★（D-139。2026-09-16）— 90.0 は ◎、70.0 は ○。 ★★× の境界だけ「未満」のまま★★ — 10.0 は △。 ↓ 型 【型】 CleanLogItem.grade: Grade = "◎" | "○" | "△" | "×"（lib/types/index.ts:17 / :249） ↓ 画面 【画面】 CleanLogTable.tsx:212 components/ui/GradeBadge.tsx:9-15 ◎ / ○ → tone "ok" / △ → "wn" / × → "ng" 凡例（「判定 ?」ボタン）: CleanLogTable.tsx:135-164 ★閾値を直書きせず GRADE_THRESHOLDS から出す★（:140 / :143 / :149 / :153） ★「10-69%」のような表記にしないこと★（:145-147）— 69.5 がどこにも該当しない読み方になる ``` ★★期待値表（`CLAUDE.md` §9.4 / `lib/fixtures/clean-logs.ts:82-92`。★シード由来★）★★ | 完了率 | 判定 | 表示（整数丸め） | 注意 | |---|---|---|---| | 90.1 | ◎ | 90% | ★丸めると90だが◎★ | | 90.0 | ◎ | 90% | ★D-139 で ○ から変わった★ | | 89.5 | ○ | 90% | ★表示は90%だが判定は○★（★事故#2★） | | 70.1 | ○ | 70% | | | 70.0 | ○ | 70% | ★D-139 で △ から変わった★ | | 10.1 | △ | 10% | | | 10.0 | △ | 10% | ★「10%未満」が×なので △★ | | 9.9 | × | 10% | | | 0 | × | 0% | ★「0%で実施した」★ | | null | × | - | ★未実施★ | ★★`isProblemCompletion()` と `judgeGrade()` は結果が常に一致する★★ （`lib/db/clean-log-mapping.ts:287-289` / `lib/judge/grade.ts:54-59`）— 入力が違うだけの同じ規則（`rate === null || rate < GRADE_THRESHOLDS.good`）なので、 ★片方の比較演算子だけを動かさないこと★。★D-139 以前は `<=` が正しかった★という履歴があります。 ### (j) 連続問題日数とエスカレーション（★画面の表には出ないが判定に効く★） ``` 【取得】 lib/db/index.ts:933-939 loadConsecutiveInputs(prisma, now, { date_from, date_to }) → computeConsecutiveProblemDays(...) : Map ↓ 遡り幅 【遡り】 lib/db/consecutive-source.ts:132-137 consecutiveLookbackCalendarDays(maxDays: number): number = (maxDays + CONSECUTIVE_LOOKBACK.plusDays) * CONSECUTIVE_LOOKBACK.calendarDaysPerScheduleDay = (30 + 1) * 7 = ★217 カレンダー日★（★構造由来★。lib/config/index.ts:167-172） lib/db/consecutive-source.ts:147-156 consecutiveLookbackFrom(dateFrom, maxDays) ★★表示期間そのもので絞らないこと★★（★指示書AC C-2 の地雷★）— 「9/8× 9/9× 9/10×」（3日連続 = L3）を「9/10〜9/10」で絞って渡すと ★1日 = L1 に化ける★。★例外もテスト失敗も出ない★ ★★`plusDays` を 0 にしないこと★★（lib/config/index.ts:157-161）— 上限ちょうどまでしか読まないと `capped` が永久に false になり、 ★「30日以上」が二度と画面に出なくなる★ ↓ 畳み込み 【畳込】 lib/db/clean-log-mapping.ts:340-352 foldProblemDaysByDate(rows): ScheduleDayResult[] ★同一日に問題ありの行が1つでもあれば その日は「問題あり」（OR。A案。D-109）★ ★施設に複数台あると同じ日に複数行が生まれるので、畳まないと「N日連続」が水増しされる★ ↓ 数える 【数え】 lib/judge/escalation.ts:32-39 countConsecutiveProblemDays(days: ScheduleDayResult[]): number ★直近から遡って数える。最新日が問題なしなら 0★ ↓ 判定 【判定】 lib/judge/escalation.ts:52-59 judgeEscalationLevel(consecutiveDays: number): EscalationLevel | null 0以下 → null / >= 3 → "L3" / >= 2 → "L2" / それ以外 → "L1" ESCALATION_THRESHOLDS = { level2Days: 2, level3Days: 3 }（lib/config/index.ts:27-32） ↓ 表示上限 【上限】 app/api/clean-logs/route.ts:105 capCleanLogs(items, maxDays) lib/clean-logs/query.ts:208-220 → lib/format/consecutive-days.ts:32-38 capConsecutiveDays(rawDays, maxDays = 30): { days, capped } ★rawDays > maxDays のときだけ capped: true★（★上限ちょうどは false★） ★★escalation_level は触らない★★（lib/clean-logs/query.ts:196-197）— L1〜L3 は ★上限をかける前の生値★で判定済み（指示書AF 禁止事項9） ↓ 型 【型】 CleanLogItem.consecutive_problem_days: number（lib/types/index.ts:254） CleanLogItem.consecutive_problem_days_capped?: boolean（:262。★任意項目★） CleanLogItem.escalation_level: EscalationLevel | null（:264） 【値の例】 ★シード由来★ 施設4（月水金スケジュール）は5日前・3日前・1日前の3回とも失敗 → ★カレンダー上は5日だがスケジュール存在日の連続は3日 → L3★ （lib/fixtures/clean-logs.ts:148-153） ★構造由来★ 表示上限 30（CONSECUTIVE_DAYS_DISPLAY.defaultMax。lib/config/index.ts:135） 下限 3（= level3Days）/ 上限 365（:137-139） ``` ## 2.4 アドバイス（行を開いたとき）— `GET /clean-logs/{id}/advice` ``` 【取得】 app/api/clean-logs/[id]/advice/route.ts:58-63 db.cleanLogs({ id: logId, date_from: null, date_to: null, facility_ids: null }) ★★`facility_ids: []` を渡さないこと★★ — `[]` は「0件ヒット」なので★全部 404★（罠1） ↓ 判定（★入力は生値★。:78-80 の注記） 【判定】 app/api/clean-logs/[id]/advice/route.ts:81-87 matchAdviceRules({ departed, completionRate, consecutiveProblemDays, status1h, status30m }) lib/judge/advice.ts:50-94 matchAdviceRules(input: AdviceInput): AdviceRuleId[] R1: !departed && consecutiveProblemDays <= 1 R2: completionRate !== null && completionRate < GRADE_THRESHOLDS.poor(10) R3: consecutiveProblemDays >= ESCALATION_THRESHOLDS.level2Days(2) R4: consecutiveProblemDays >= ESCALATION_THRESHOLDS.level3Days(3) B1: completionRate !== null && judgeGrade(completionRate) === "△" B2: status が B2_HANDLE_UP_STATUSES に一致（lib/config/robot-status-match.ts） B3: status が B3_OFFLINE_STATUSES に一致（★現在このマッチ配列は空なので発火しない★） ★複数該当したら全部返す★ ↓ 文言 【文言】 loadAdviceRules()（lib/settings/advice.ts）→ 既定は lib/config/advice-rules.ts app/api/clean-logs/[id]/advice/route.ts:114-124 で AdviceItem に詰め替える ↓ 表示上限 【上限】 app/api/clean-logs/[id]/advice/route.ts:154 capConsecutiveDays(生値, maxDays) ★★ここだけが表示上限をかけてよい場所★★（:143-146）— 判定も judge.* の logEvent も生値のまま ↓ 型 【型】 CleanLogAdviceResponse（lib/types/index.ts:366-375） { escalation_level: EscalationLevel | null; consecutive_problem_days: number; consecutive_problem_days_capped: boolean; max_level: number; advices: AdviceItem[] } AdviceItem（:269-277）= { rule; level: 1|2|3; icon; title; estimated_cause; recommended_actions: string[] } ↓ 画面 【画面】 CleanLogTable.tsx:219-266 :41-61 adviceHead(maxLevel) → 3:「🔴 レベル3 — DFA介入を検討」/ 2:「🔶 レベル2 — DFA運用担当がアクション」/ それ以外:「⚠ レベル1 — 現場確認が必要」 :238-241 {a.icon} {a.title} / {a.estimated_cause} :243-247 recommended_actions を
  • で並べる :251-260 「エリア別詳細を見る →」ボタン ★行が開けるのは grade が △ か × の行だけ★（CleanLogTable.tsx:174 / :183） ★取得に失敗しても行は開く★（DetailLogScreen.tsx:227-242）— 一覧が持っている値で埋める ``` ## 2.5 エリアモーダル — `GET /clean-logs/{id}/areas` ★★`{id}` は「エリアを特定するキー」ではなく、施設と日付を特定するための入口★★ （指示書Z 決定1。`app/api/clean-logs/[id]/areas/route.ts:103-105`）。 ★同じ施設・同じ日の**全エリア**を出す★ので、`clean_log_id` で引くと他のエリアが消えます。 ``` 【DBの列】 sections.section_name String @db.VarChar(100)（prisma/schema.prisma:171） clean_status_histories.clean_ratio Float（:497） clean_status_histories.clean_area Float（:492） clean_status_histories.task_area Float（:491） ↓ 2段構え 【取得】 1段目 app/api/clean-logs/[id]/areas/route.ts:78-83 db.cleanLogs({ id: logId, date_from: null, date_to: null, facility_ids: null }) → 404 の判定と、facility_id / JST 日付の特定だけに使う :99 const date = log.scheduled_at.slice(0, 10) ★★areaCompletions() の date と同じ作り方★★（片方だけ生の Date から作ると 9時間ずれて突き合わせが外れる。D-115） 2段目 :106 db.areaCompletions({ facility_id: log.facility_id, date }) prismaSource: lib/db/index.ts:1080-1096 completion_rate: completionRateFromHistory(history) ← ★clean_ratio の生値★ clean_area: history?.clean_area ?? 0 ← ★`||` にしない（事故#1）★ task_area: history?.task_area ?? 0 date: jstIsoFromDb(row.start_at).slice(0, 10) ↓ 中間型 【型】 AreaCompletionRow（lib/types/index.ts:325-339） { clean_log_id; facility_id; date; section_id; section_name; completion_rate: number | null; clean_area: number; task_area: number } ↓ 絞り込み・集計 【集計】 app/api/clean-logs/[id]/areas/route.ts:116-119（selected）/ :120（body） lib/clean-logs/areas.ts:55-62 selectAreaRowsForLog(rows, { facility_id, date }) lib/clean-logs/areas.ts:110-139 buildAreaCompletions(rows, filter): AreaCompletionsResponse items = rows.map(...) に judgeGrade() を当てて compareByCompletion でソート problem_count = isProblemGrade(grade) の件数（★filter で絞る前★） overall = completionRate(Σclean_area, Σtask_area) ★面積ベース★ total_count = items.length（★filter で絞る前★） items（返す分）= filter === "problem" なら △× のみ 並び順（lib/clean-logs/areas.ts:70-82 compareByCompletion） ★完了率の昇順。未実施(null)は先頭。同値は section_id の昇順★ （★悪いものから見る画面なので、いちばん悪い「未実施」を先頭に置く★。決定10） ↓ 型 【型】 AreaCompletionsResponse（lib/types/index.ts:303-317） { overall_completion_rate: number | null; overall_grade: Grade; total_count: number; problem_count: number; items: AreaCompletionItem[] } AreaCompletionItem（:286-300）= { section_id; section_name; completion_rate: number | null; grade } ↓ 画面 【画面】 components/features/detail-log/AreaModal.tsx :70-71 ヘッダ「全体 {displayRate(overall_completion_rate)} {overall_grade}」 :104-111 「問題エリア（{problem_count} / {total_count}エリア）」/「全{total_count}エリア（完了率昇順）」 :113-120 0件の文言を ★total_count === 0 かどうかで分ける★ → 「エリアのデータがありません」/「問題エリアはありません（全エリア◎○）」 :131 section_name（★生値。当方で整形しない★） :135-138 ★未実施（null）は 0 幅★ :142 displayRate(item.completion_rate) ★未実施は "-"。0% と書かない★ :144 【値の例】 ★シード由来★（lib/fixtures/areas.ts:67-） 施設1・当日: task_area = 1000、行の completion_rate = 90.1 → clean_area = 1000 × 90.1 ÷ 100 = 901 → overall = 901 / 1000 × 100 = 90.1 → 表示「90%」/ overall_grade「◎」 ★構造由来★ section_name はシードと同じ形「清掃エリア（ロボット11）」 （lib/fixtures/areas.ts:44） ``` ★★行と全体で完了率の出し方が違う（意図した非対称）★★（指示書Z 決定7。 `lib/clean-logs/areas.ts:87-97` / `lib/types/index.ts:291-296`） | | 出し方 | |---|---| | 各行の `completion_rate` | ★`clean_ratio` の生値★（面積から再計算しない） | | `overall_completion_rate` | ★Σ`clean_area` ÷ Σ`task_area` × 100★（面積ベース。`CLAUDE.md` §4.2） | ★合計が行の平均と一致しないことがあります★。 行を面積から再計算すると `cleanLogs()` の完了率と食い違い、 全体を単純平均で出すと担当面積の違う台を等しく扱うことになるため、 ★どちらを選んでも揃わない。揃わないことを明示する★という判断です。 ## 2.6 CSV エクスポート - `DetailLogScreen.tsx:463` — `` （★`router.push` を使わない★。RSC のプリフェッチで ★エクスポートが2回走る★。`:442-445`） - ★上限は `MAX_CSV_ROWS = 20_000`★（`lib/config/index.ts:385`。★構造由来★）。 ★「上限」は含む★ — ちょうど 20,000 行は出せて、20,001 行から 422。 - 画面側の歯止め: `DetailLogScreen.tsx:162` — `const csvBlocked = total > MAX_CSV_ROWS;` ★`>` であってサーバ側と同じ向きにすること★（`:155-157`）。 ★片方だけ `>=` にすると、押せるのに422が返る（またはその逆）★。 - 上限超過時は ★`` ではなく `