/** * データソースの切替 * * 環境変数 `USE_FIXTURES` で「サンプルデータ」と「実DB（Prisma）」を切り替えます。 * * USE_FIXTURES=true → lib/fixtures/ のサンプルデータを返す（DB不要） * USE_FIXTURES=false → Prisma経由で実DBを読む * * ★画面側のコードは切替を意識しません。APIルートがこのモジュールを呼ぶだけです★ * * ★判定ロジック（lib/judge/）はこの切替の外側に置くこと★ * fixture開発中も本番と同じ判定ロジックが走るようにするためです（D-044）。 * * 【重要】メインDBは原則読み取り専用です。 * 書き込んでよいのは robot_error_reports / control_error_histories の * status / comment / responded_at / resolved_at の4カラムのみ（D-042）。 * ★書き込みは `lib/db/robot-error-write.ts` の `writeRobotErrorColumns()` だけ★（指示書AT）。 */ import type { AreaCompletionDbQuery, AreaCompletionRow, CleanAreaDbQuery, CleanLogDbQuery, CleanLogItem, CleanLogRunMeta, ContinuousProblemRow, Customer, DsAlert, DsDevice, ErrorBreakdownRow, ErrorReportDbQuery, ErrorReportItem, Facility, FacilityGroupRef, FacilityNameRef, FacilityPerformance, FacilityPerformanceDbQuery, FacilityPerformanceRow, Group, InspectionDetail, InspectionListItem, PrecheckDbQuery, PrecheckItem, PrecheckStatusPatch, ReportDbQuery, ReportKpi, ReportKpiDbQuery, ReportKpiRow, ReportPeriodKey, RescueDbQuery, RescueRequiredItem, Schedule, } from "@/lib/types"; import { areaCompletions, cleanLogs, continuousProblems, customers, dsAlerts, dsDevices, errorBreakdown, errorReportRows, errorReportTimetables, facilities, facilityPerformance, groups, inspectionDetails, inspections, prechecks, reportKpis, schedules, } from "@/lib/fixtures"; import { CLEAN_TIMETABLE_PRECHECK, MAKER_NAMES } from "@/lib/config"; import { judgeEscalationLevel, judgeFacilityStatus, judgeGrade } from "@/lib/judge"; import { completionRateFromReport, computeConsecutiveProblemDays, formatModelName, isFutureSchedule, latestReportByTimetableId, notExecutedFromReport, robotStatusFromErrors, type ConsecutiveInput, type RobotErrorLike, } from "@/lib/db/clean-log-mapping"; import { chunkForInClause } from "@/lib/db/chunked"; import { isResultPending } from "@/lib/clean-logs/result-pending"; // ★清掃面積（指示書AN 段階3）★ — ★ロールアップ（`aggregateCleanArea()`）はここでやらない★。 // 材料（施設ごとの合計 + 施設マスタ + 番人の件数）を返すだけにして、 // ★粒度（`group_by`）ごとの組み立てはルート層に任せる★（同じ材料から3粒度とも作れる）。 // ★★`groupBy` はここに直書きせず、同ファイルの2関数を必ず経由する★★（指示書AQ §5-3）— // ★番人の `clean_timetable_id IS NOT NULL` 除外があちらにしか無い★ため。 import { countDuplicatedTimetables, loadCleanAreaFacilityMasters, loadCleanAreaFacilityStatsWithRowCount, type CleanAreaSourceResult, type CleanAreaWhere, } from "@/lib/db/clean-area-source"; import { cleanAreaStatsFromFixtureAreas } from "@/lib/db/fixture-clean-area"; import { loadConsecutiveInputs, type ConsecutiveDbRange, } from "@/lib/db/consecutive-source"; import { dbDateRange } from "@/lib/db/date-range"; import { buildRescueRequired, rescueInputsFromCleanLogs, } from "@/lib/db/rescue-mapping"; import { loadFacilityGroupIndex } from "@/lib/db/facility-group-source"; import { loadFacilityNameIndex } from "@/lib/db/facility-name-source"; import { filterFixtureAreaCompletions } from "@/lib/db/fixture-area-completions"; import { filterFixtureCleanLogs } from "@/lib/db/fixture-clean-logs"; import { filterFixturePrechecks } from "@/lib/db/fixture-prechecks"; import { applyFixturePrecheckPatch, withFixturePrecheckOverride, } from "@/lib/db/fixture-precheck-overrides"; import { applyFixtureErrorReportPatch, withFixtureErrorReportOverride, } from "@/lib/db/fixture-error-report-overrides"; import { errorReportItemFromRow, errorReportKeyFromRow, errorReportListWhere, type ErrorReportKey, type ErrorReportRowSource, type ErrorTimetableRef, } from "@/lib/db/error-report-mapping"; import { filterSortErrorReportKeys } from "@/lib/error-reports/query"; import { writeRobotErrorColumns } from "@/lib/db/robot-error-write"; import { findTimetableById, findTimetables, findTimetablesByChunks, type TimetableFindManyArgs, } from "@/lib/db/timetable-source"; import { ROBOT_ERROR_COUNT_SELECT, ROBOT_ERROR_LIST_KEY_SELECT, ROBOT_ERROR_LIST_ROW_SELECT, ROBOT_ERROR_PRECHECK_ROW_SELECT, ROBOT_ERROR_STATUS_SELECT, ROBOT_ERROR_TYPE_SELECT, } from "@/lib/db/robot-error-select"; import { filterFixtureFacilityPerformance, filterFixtureReportKpis, filterFixtureReportRows, filterFixtureRowsByFacility, } from "@/lib/db/fixture-reports"; import { filterRowsByFacilityIds } from "@/lib/facilities/filter-by-ids"; // ★fixtures の屋号一覧を `id` 昇順にするため★（指示書AL 段階3 §4-4）— // ★並べ替え規則の「正」は `sortCustomers()` の1本★。ここに比較関数を写さない。 import { sortCustomers } from "@/lib/masters/query"; import { mainRunSucceededFromReport, PRECHECK_COLUMN_COUNT, precheckItemFromErrorRow, precheckMinutesFromCode, statusColumnsFromPrecheckRows, } from "@/lib/db/precheck-mapping"; import { logEvent } from "@/lib/logger"; import { connectionStatusFromControlStatus, resolutionStatusFromControlErrorStatus, } from "@/lib/db/ds-status"; import { aggregateCleanStatsByFacility, consecutiveProblemDaysAtPeriodEnd, continuousProblemsInPeriod, countMainErrorTypesInRange, customerSummariesByPeriodKey, errorBreakdownItemsFromCounts, errorBreakdownRowsFromSummary, errorCountByMainTimetable, kpiFromCleanStats, kpiFromSummaryRatios, mainTimetableStartAtById, periodMapKey, periodOfSummaryRow, sumCleanStatsBuckets, } from "@/lib/db/report-mapping"; import { formatAddress } from "@/lib/format/address"; import { parseContract } from "@/lib/format/contract"; import { fromDbJst, jstIsoFromDb } from "@/lib/format/date"; // ★`customers.group_id` の 0 → null 変換はこの1本だけが知っている★（D-011 / 指示書AK §4-4）— // ★`=== 0` を `prismaSource` の中に書かないこと★（落とし穴3）。 import { groupIdFromDb } from "@/lib/format/group-id"; // ★`todayJst()` / `weekOfMonth()` はもうここでは使わない★（指示書AC 段階5）— // ★当期かどうかの判定は `isCurrentPeriod()` に、期間の範囲は `periodRange()` に任せる★。 // ★★「今日」から期間キーを自分で組み立てないこと★★（月跨ぎ週の帰属を知っているのは // `weekOfMonth()` だけ。`CLAUDE.md` §4.7 / D-071）。 import { isCurrentPeriod, periodRange, shiftPeriod } from "@/lib/format/period"; import { formatEndTime, formatStartTime, weekdaysLabel, } from "@/lib/format/schedule"; export { USE_FIXTURES } from "@/lib/db/use-fixtures"; import { USE_FIXTURES } from "@/lib/db/use-fixtures"; /** * データソースが実装すべきインターフェース。 * フィルタや集計はこの層では行わず、APIルート側で組み立てます * （実DB接続時にクエリへ落とすときの差分を小さくするため）。 * * ★例外: レポート4メソッドの「当期（進行中の週・月）」だけは `prismaSource` の中で * 詳細テーブルからその場集計する（指示書T 段階2。D-090項14/項15の解決）★ — * `cleanLogs()` の連続日数・judge 呼び出しと同じ扱い * （D-090項16「judgeをprismaSourceの中で呼ぶこと自体は妥当」）。 * 確定期間（サマリテーブル由来）はこれまでどおり再計算しない（D-102 / CLAUDE.md 禁止事項1）。 * ★★2026-09-13（段階5）以降は「どの期間を集計すべきか」を `ReportDbQuery` で * 受け取る★★ので、★当期かどうかの判定も期間の範囲もその引数から導く★ * （`todayJst()` は当期判定（`isCurrentPeriod()`）の中だけで使う）。 * * ★★2026-09-13（指示書AC 段階2 / ★段階3★ / ★段階4★ / ★段階5★）: * `inspectionDetail()` 以外の主要メソッドは引数を取るようになりました★★ — * ★「全部返す」しかできない契約では本番のデータ量（保持2年で約26万行）に耐えない★ * ため、★日付範囲・施設ID・単一ID・期間 を SQL に降ろします★。 * ★絞り込み規則の「正」は API ルート側の純粋関数（`filterCleanLogs()` / * `selectAreaRowsForLog()` 等）に置いたまま★ — * ★SQL 側はその写し★ です（指示書AC C-5。★だから `filterXxx()` を外さないこと★）。 */ export interface DataSource { /** * 清掃詳細ログの一覧。 * * ★★引数は必須★★（指示書AC C-4 項4）— ★全件が要る呼び出し側は「範囲なし」 * （`{ date_from: null, date_to: null, facility_ids: null }`）を明示的に渡すこと★。 * ★任意引数にすると「渡し忘れても動く（が全件読む）」状態が残り、 * 直したつもりで直っていないことに誰も気づけない★。 * * ★★`facility_ids` の `null` と `[]` は別物★★（`CleanLogDbQuery` の型コメント）— * `null` = 施設で絞らない / `[]` = ★0件★。 */ cleanLogs(query: CleanLogDbQuery): Promise; /** * ★清掃ログの id → { 清掃エリア, 予定の終了 }★（ダッシュボードの直近モード専用。D-159 / 指示書AV）。 * ★`cleanLogs()` と同じ引数を渡すこと★（同じ `where`。突き合わせは `pickLatestRunPerSection()`）。 * ★`cleanLogs()` が返さない id（未来の予定）を含んでよい★。逆（`cleanLogs()` の行に対応が無い）は呼び出し側の例外 * * ★★`CleanLogItem` にこの2列を足さずに別メソッドにした理由★★（指示書AV §2 D9）: `CleanLogItem` は * 多くの経路が共有しており、内部用の列を足すと剥がし忘れた瞬間に API に漏れるため。 */ cleanLogRunMeta(query: CleanLogDbQuery): Promise; /** * ★施設名 → 施設ID の解決★にだけ使う、施設マスタの最小限の一覧（指示書AC 段階2 D-6）。 * * ★★`facilities()` と用途が違う★★ — あちらは施設マスタ画面（F-05）に返す一覧で * ★`deleted_at` で絞っている★。こちらは ★絞らない★（★罠7★。理由は * `loadFacilityNameIndex()`（`lib/db/facility-name-source.ts`）の docstring）。 * ★★`facilities()` で代用しないこと★★ — 論理削除された施設のログが * 検索から静かに消えます。 */ facilityNameIndex(): Promise; /** * ★分類（ホールディングス／屋号）→ 施設ID の解決★にだけ使う、施設マスタの最小限の一覧 * （指示書AK 段階3 §6-3）。 * * ★★`facilityNameIndex()` と同じ立ち位置★★ — ★`facilities()` で代用しないこと★ * （あちらは `deleted_at` で絞っている。★罠7★。理由は * `loadFacilityGroupIndex()`（`lib/db/facility-group-source.ts`）の docstring）。 * * ★★`facilityNameIndex()` に列を足す形にしないこと★★ — 用途が違う2つの読み取りを * 1本にまとめると、片方の都合で `where` や列を変えたときに * ★もう片方の要件を黙って壊します★（`dsDeviceExists()` を `dsDevices()` に * 足さなかったのと同じ判断）。 * * ★解決（当たり外れ）は `lib/facilities/resolve-by-master.ts` の純粋関数★。 * ★このメソッドは行を読むだけ★。 */ facilityGroupIndex(): Promise; /** * エリア別完了率の行。 * * ★★引数は必須★★（指示書AC 段階3 / C-4 項4。`cleanLogs()` と同じ作法）— * ★全件が要る呼び出し側は「範囲なし」（`{ facility_id: null, date: null }`）を * 明示的に渡すこと★。★以前は引数を取らず**全期間・全施設**を読んでいた★ * （1行の表示のために実測 1,582行。指示書AC B-3）。 * * ★★`filter` の適用と全体率の計算は APIルート側のまま★★ * （`lib/clean-logs/areas.ts` の `selectAreaRowsForLog()` / `buildAreaCompletions()`）— * ★SQL 側は `selectAreaRowsForLog()` の写し★ です（C-5）。 */ areaCompletions(query: AreaCompletionDbQuery): Promise; /** * アラート（事前チェック）一覧。 * * ★★引数は必須★★（指示書AC 段階4 / C-4 項4。`cleanLogs()` と同じ作法）— * ★全件が要る呼び出し側は「範囲なし」（`{ date_from: null, date_to: null, * facility_ids: null }`）を明示的に渡すこと★。 * * ★★`facility_ids` の `null` と `[]` は別物★★（`cleanLogs()` と同じ契約。★罠1★）— * `null` = 施設で絞らない / `[]` = ★0件★（分類で絞って1件も当たらなかった）。 * * ★★2種類の行（`precheck` / `launch_failed`）を**同じ期間**で絞る★★ — * ★基準はどちらも「本清掃行の `start_at`」★（`PrecheckDbQuery` の型コメント）。 * ★★片方だけ絞れている状態を検出するため、`severity` の内訳をテストで固定してある★★ * （`app/api/prechecks/__tests__/route.test.ts` の #3）。 * * ★★対応状況（`status`）の絞り込みは APIルート側のまま★★ * （`filterPrechecksByStatus()` / `sortPrechecks()`。指示書AC C-5）。 */ prechecks(query: PrecheckDbQuery): Promise; /** * `PATCH /prechecks/{id}/status` の前後の読み取り（指示書AT 段階4-2 / §3-3）。★参照用の接続で読む★。 * * `{id}` を `robot_error_reports.error_id` として引き、★次をすべて満たすときだけ★行を返す: * 1. `error_id = id` の行がある（★大小文字も含めて JS の `===` で一致★。DB の照合順序は ci。D-4） * 2. その行の `clean_timetable_id` が null でない * 3. その `clean_timetables` 行があり、`precheckMinutesFromCode(precheck)` が null でない（＝事前チェック行） * 4. その事前チェック行の `parent_id` が指す本清掃行がある（★無ければ例外＝500★。`prechecks()` と同じ） * ★1〜3 のどれかを満たさなければ `null`（＝404）★。★出発失敗の id（`clean_timetables.id` の文字列）は * `error_id` として引いても当たらないので `null`★（別の分岐を作らない）。 * ★期間・施設では絞らない★（一覧の絞り込みであって行の性質ではない）。 * ★行の組み立ては `precheckItemFromErrorRow()`★（`prechecks()` と同じ関数）。 * ★`main_run_succeeded`（D-171）は 4. の本清掃行の `clean_task_reports` から決める★（無ければ false。404 にはしない）。 */ precheckItemById(id: string): Promise; /** * `robot_error_reports` の4カラムを `updateMany` の1文で書く（指示書AT §3-2 / 段階4-2）。 * ★書き込み用の接続（`getWritePrisma()`）で書く★。中身は `writeRobotErrorColumns()` * （`lib/db/robot-error-write.ts`）の1本。 * * ★`matched` で存在を判定しないこと★ — 存在確認は書く前に `precheckItemById()` で行う。 * 0 なら「確認と書き込みの間に行が消えた」（ルートが 404 にする）。 */ updatePrecheckErrorColumns(errorId: string, patch: PrecheckStatusPatch): Promise<{ matched: number }>; /** * エラー一覧（`GET /errors`。指示書AW）。★`robot_error_reports` の全行★が対象（事前チェック・本清掃・予定なし・`robot_id` NULL を問わない）。 * ★2段階で読む★（D8）: キーだけを SQL で `status IN`・`facility_id IN`・期間で絞って読み、 * `filterSortErrorReportKeys()` で絞り込み・並べ替え → ページの `error_id` だけ列を足して読む。 * ★`total` は絞り込み後・ページ分け前の件数★（`meta.total`）。 */ errorReports(query: ErrorReportDbQuery): Promise<{ items: ErrorReportItem[]; total: number }>; /** * `PATCH /errors/{error_id}/status` の前後の読み取り。★`error_id === id` の行があれば返す（事前チェックかどうかを問わない）★。 * ★大小文字は JS の `===` で決める★（D-4。`precheckItemById()` と同じ）。★期間・施設・状態では絞らない★ */ errorReportById(id: string): Promise; /** * 4カラムを書く（`writeRobotErrorColumns()` の1本。★書き込み用の接続★）。 * ★`matched` で存在を判定しないこと★ — 存在確認は書く前に `errorReportById()` で行う */ updateErrorReportColumns(errorId: string, patch: PrecheckStatusPatch): Promise<{ matched: number }>; dsDevices(): Promise; /** * ★備考の保存（`PATCH /ds-devices/{serial_number}/note`）の実在確認★だけに使う * （指示書AH 段階2）。 * * ★★`dsDevices()` に引数を足す形にしないこと★★ — ★一覧側はサマリ（`summarizeDsDevices()`） * のために全件が要る★（D-054。`summary.total` は q / status フィルタの影響を受けない）。 * ★`facilityNameIndex()` が前例★（「`facilities()` と用途が違うから別メソッドにした」）。 * * ★★`deleted_at` の絞りを `dsDevices()` と揃えること★★（★罠7★）— * 絞りをやめると ★一覧に出ないデバイスの備考が保存できてしまい、どこからも参照されない * 行がストアに残る★。★それはこのチェックが防いでいる当のもの★。 * * ★★当たり外れは呼び出し先の実装が JS の `===` で決める★★（D-4）— * ★DBの既定の照合順序は大小文字を区別しない（ci）★ので、SQL の一致をそのまま * 答えにすると `ds-001` が `DS-001` に当たって 404 が 200 になる。 * ★保存キーはリクエストの生文字列★（`lib/settings/ds-device-notes.ts` は * `Record`）で、★一覧は `notes["DS-001"]` で引く★ため、 * ★★保存されたのに一生表示されない孤児行が残る★★。 */ dsDeviceExists(serialNumber: string): Promise; dsAlerts(): Promise; /** * ホールディングス一覧（`GET /groups`。指示書AK 段階1）。 * * ★`deleted_at IS NULL` でのみ絞る★（`facilities()` と揃える）。 * ★`inactive` では絞らない★ — 無効化は削除ではなく、画面が見せ分ける可能性がある * （`facilities()` :1300-1302 と同じ判断）。 * * ★★引数を取らない★★ — 分類マスタは数十行の規模で、絞り込む対象が無い * （`facilities()` / `schedules()` と同じ扱い）。 * ★`id = 0` の行はそもそも存在しない★（0 は `customers.group_id` 側のセンチネル。D-011）。 */ groups(): Promise; /** * 屋号一覧（`GET /customers`。指示書AK 段階1）。 * * ★`group_id` の絞り込みは API ルート側の純粋関数★（`filterCustomersByGroup()`）— * ★分類マスタは数十行なので SQL に降ろす利得が無い★（清掃ログの26万行とは事情が違う。 * 指示書AC C-4 の「引数必須」はデータ量が理由）。★絞り込み規則を1箇所に置く★ほうを採る。 * * ★★`customers.contract` を読まないこと★★（D-010 / `CLAUDE.md` §7。落とし穴5）— * 削除依頼済みの列で、契約フラグは `facilities.contract` のみが正。 * * ★`group_id` は 0 → `null` に変換して返す★（D-011）。 * 変換を知っているのは `groupIdFromDb()`（`lib/format/group-id.ts`）だけ。 * * ★★`id` の昇順で返すこと★★（指示書AL ★段階3★ / §4-4。`groups()` と違う点）— * `GET /customers` はルート側の `sortCustomers()` で並べ替えるので順序に依存しないが、 * ★`GET /reports/kpi` の 422 は `db.customers()` の並びをそのまま * `details.customer_ids` に流す★（`resolveTargetCustomer()` は並べ替えない）。 * 順序をDB任せにすると ★画面に出る候補の並びが環境で変わる★。 */ customers(): Promise; facilities(): Promise; schedules(): Promise; inspections(): Promise; inspectionDetail(id: number): Promise; /** * 要レスキュー店舗（F-01 の `GET /dashboard` の `rescue_required`。指示書AI 段階4）。 * * ★★引数は必須★★（指示書AC C-4 項4。`cleanLogs()` と同じ作法）。 * * ★★`cleanLogs()` で代用しないこと★★ — 3条件のうち * ★R-1（未実施3日連続）と R-3（前回比の急落）は当日の行だけでは判定できない★し、 * ★★当該日に予定が無い施設も対象に含める★★（ユーザー指示 2026-09-15 / 指示書AI §1-5）ので * 母集団も違う。★`CleanLogItem` には前回比も未実施連続日数も入っていない★。 * * ★★数値カード（`summary`）には影響しない★★ — あちらは当日のログだけから作る * （`lib/dashboard/aggregate.ts`。★変更しない★）。 * ★★ただし分類の絞り込み（`facility_ids`）は両方に同じ配列を渡すこと★★ * （指示書AK §7-2）— ★母集団がずれると、数値カードと要レスキューが * 別の集団の話になる（例外もテスト失敗も出ない）★。 * * ★入力は `loadConsecutiveInputs()` の1本から取る★（★新しい全期間クエリを書かないこと★。 * D-109 の再発防止。要レスキューは4本目の呼び出し元になる）。 */ rescueRequired(query: RescueDbQuery): Promise; /** * 清掃面積の集計材料（`GET /clean-area`。指示書AN ★段階3★ / §6-1）。 * * ★★引数は必須★★（指示書AC C-4 項4。`cleanLogs()` と同じ作法）— * ★全期間が要る呼び出し側は「範囲なし」を明示的に渡すこと★。 * * ★★集計材料を返すだけ★★ — ★ロールアップ（`aggregateCleanArea()`。段階2 の純粋関数）は * 呼ばない★。理由は ★粒度（`group_by`）がリクエストの引数★で、 * ★同じ材料から group / customer / facility の3粒度とも作れる★ため * （粒度をここで受け取ると、粒度ごとに同じ集計クエリを撃ち直す形に誘導してしまう）。 * ★判定・集計をデータ層に持ち込まない★という既存の分担（`filterXxx()` / `sortXxx()` が * ルート側にあるのと同じ。指示書AC C-5）にも合う。 * * ★★サマリテーブルの面積を読まないこと★★（指示書AN §1-2 / 落とし穴1）— * `facility_summaries` / `customer_summaries` の `task_area` は * ★実データで全行 1000 固定★で、★期間内の合計になっていない★（第9回 Q2-1 で照会中）。 * ★D-102（サマリは再計算しない）の対象は KPI 4指標で、面積は対象外と読む★（指示書AN §1-2）。 * * ★★戻り値の `duplicated_timetable_count` を握りつぶさないこと★★（★番人★。§2-5 / §6-3）— * ★ルートは必ず `reportCleanAreaAnomalies()`（`lib/clean-area/anomaly.ts`）に渡すこと★。 * ★渡し忘れても例外もテスト失敗も出ない★（数字が静かに大きくなるだけ）。 */ cleanArea(query: CleanAreaDbQuery): Promise; /** * レポートの4メソッド。 * * ★★引数は必須★★（指示書AC ★段階5★ / C-4 項4。`cleanLogs()` と同じ作法）— * ★以前は引数を取らず**全期間・全件**を読んでいた★（4API 合計で ★実測 7,587行★。 * 指示書AC B-3 の約6,000行に、段階1 で分けた連続日数の1本が加わった値）。 * ★★レポート画面は必ず1期間を選んでいる★★ので、★「範囲なし」を表す値は用意しない★。 * * ★★確定期間と当期で読むものが違う★★（`CLAUDE.md` §4.7）: * - ★確定期間★ … サマリテーブルを `where: { year, month, week }` で引く。 * ★★履歴から再計算しない（D-102 / `CLAUDE.md` 禁止事項1）★★ * - ★当期（進行中の週・月）★ … サマリに行が無いのが正常なので、詳細テーブルを * ★`periodRange()` が返す範囲★で絞ってその場集計する * * 戻り値が `Xxx[]` ではなく `XxxRow[]`（期間キー付きの行型）なのは、 * ★ルート側の `selectXxxRows()` / `selectKpiRow()`（＝絞り込み規則の「正」。C-5）が * そのキーで照合するため★です（`ReportPeriodKey` のコメント参照）。 * ★★`filterXxx()` / `sortXxx()` と同じく、あちらを外さないこと★★。 */ /** * レポートKPI。★前期比のため1つ前の期間のサマリも読む（2行ぶんだけ）★ * * ★★このメソッドだけ絞り込みの軸が2つある★★: * - ★確定期間★ … `customer_summaries`（★施設ではなく**顧客**単位★）を読むので * ★`customer_id`★ で絞る（指示書AK ★段階6★ / §2-1。`ReportKpiDbQuery`） * - ★★当期（進行中の週・月）★★ … 詳細テーブルをその場集計するので * ★`facility_ids`★ で絞る（指示書AL ★段階1★。★以前はここを絞っておらず、 * ★★確定期間は1社・当期は全社合算★★ という食い違いが起きていた。D-138 の残課題） * * ★★2つの軸は同じ顧客を指していなければならない★★ — ★`facility_ids` は * `customer_id` と同じ顧客から解決したものを渡す契約★（ルート側で解決する。 * ★リクエストの `group_id` から直接引かないこと★。指示書AL §2-3）。 * * ★★`customer_id` は必ず1社★★ — ★「顧客が決まらない」ときはデータ層を呼ばず 422★ * （`resolveTargetCustomer()` → `app/api/reports/kpi/route.ts`）。 * ★★静かに1社を選ぶことも、全顧客を合算することもしない★★（D-133 / 落とし穴6）。 * * ★★複数顧客の行が混ざっていたら例外にする安全弁（D-5 / D-133）は**残してある**★★ — * `customerSummariesByPeriodKey()`（`lib/db/report-mapping.ts`）。 * ★`where` で絞れているので通常は発火しない★が、★同一顧客でも同じ期間キーの重複は * 起こりうる（一意制約が無い）★ので検知は必要（期待値表 6-8）。 */ reportKpis(query: ReportKpiDbQuery): Promise; /** * 施設別パフォーマンス。並び替え・`status` フィルタ・`serial` フィルタ・limit はAPIルート側。 * * ★★施設名の絞り込みを持つのはこのメソッドだけ★★（`d-watch-api.yaml` の * `/reports/facility-performance` にだけ `facility_name` がある）— * ★段階2 と同じく「解決済みの施設ID配列」で受ける★。 * ★分類（`group_id` / `customer_id`）との積集合はルート側で取ってから渡す★ * （`intersectFacilityIds()`。指示書AK §6-2）。 */ facilityPerformance(query: FacilityPerformanceDbQuery): Promise; /** * 連続問題施設。2日以上の絞り込みと limit はAPIルート側。 * ★`query.facility_ids` で施設を絞る（`null` = 絞らない / `[]` = 0件。指示書AK 段階4b）★ */ continuousProblems(query: ReportDbQuery): Promise; /** * エラー種別内訳。降順ソートはAPIルート側。 * ★`query.facility_ids` で施設を絞る（指示書AK 段階4b §7-3。D-133 申し送り③の解消）★ — * ★★ただし fixtures 版は `[]` 以外を絞れない★★（理由は `fixtureSource.errorBreakdown()`）。 */ errorBreakdown(query: ReportDbQuery): Promise; } // ---------------------------------------------------------------- エラー一覧の共通部品（指示書AW） /** * 並べ替え済みのキーから、そのページの `error_id` を切り出す（fixtures 版・Prisma 版で共有。★規則を2箇所に書かない★）。 * ★範囲外のページは `[]`★（404 にしない。表2 F11）。 */ function errorReportPageIds(keys: readonly ErrorReportKey[], query: ErrorReportDbQuery): string[] { const start = (query.page - 1) * query.per_page; return keys.slice(start, start + query.per_page).map((key) => key.error_id); } /** * ページの `error_id` の順に、行と予定を引き当てて `ErrorReportItem` にする（fixtures 版・Prisma 版で共有）。 * * ★予定の引き当ては `.toString()` をキーにした Map★（`bigint` は Map のキーにならない。指示書AW 4-9）。 * ★`timetables` は呼び出し側で「同じ id は本表が勝つ」を済ませたもの★（Prisma 版は `findTimetablesByChunks()`。D5）。 * ★`rows` に無い `error_id` は飛ばす（例外にしない）★ — Prisma 版では1段目（キー）と2段目（行）の間に * 行が消えうる（ステージングのデータ入れ替え。第10回 N-6）。例外にすると1行のために一覧全体が500になる。 * `meta.total` は1段目の件数のまま（1件ずれうる。承知のうえ。指示書AW 4-15）。 */ function errorReportItemsInPageOrder( pageIds: readonly string[], rows: readonly ErrorReportRowSource[], timetables: readonly ErrorTimetableRef[] ): ErrorReportItem[] { const rowById = new Map(rows.map((row) => [row.error_id, row])); const timetableById = new Map(timetables.map((t) => [t.id.toString(), t])); const items: ErrorReportItem[] = []; for (const id of pageIds) { const row = rowById.get(id); if (!row) continue; // 1段目と2段目の間に消えた行（上の docstring） const timetable = row.clean_timetable_id === null ? undefined : timetableById.get(row.clean_timetable_id.toString()); items.push(errorReportItemFromRow(row, timetable)); } return items; } // ---------------------------------------------------------------- fixtures const fixtureSource: DataSource = { /** * ★Prisma 版と**同じ引数**を受け取り、**同じ結果**を返す★（指示書AC 段階2 D-5）。 * ★★`USE_FIXTURES` の true/false で件数が変わってはいけない★★（禁止事項6）。 * 絞り込みの中身は `filterFixtureCleanLogs()`（純粋関数）に置いてある。 */ async cleanLogs(query: CleanLogDbQuery) { return filterFixtureCleanLogs(cleanLogs, query); }, /** * ★fixtures には予定の終了も清掃エリアも無い★（`lib/fixtures/clean-logs.ts`。指示書AV §2 D10）。 * ★終了＝開始★（`scheduled_at`。落ち着き時間は開始から数える）、 * ★清掃エリア＝ロボット★（`serial_number`。P1 は1エリア＝1ロボット。`CLAUDE.md` §8）とみなす。 * ★★fixtures のデータに終了時刻・清掃エリアを足さないこと★★（`docs/fixtures.md` の正を崩さない）。 * ★`cleanLogs()` と同じ `filterFixtureCleanLogs()` を通す★ので、`facility_ids` の * `null`（絞らない）/ `[]`（0件）の扱いは `cleanLogs()` と同じになる。 */ async cleanLogRunMeta(query: CleanLogDbQuery) { return filterFixtureCleanLogs(cleanLogs, query).map((row) => ({ id: row.id, section_key: `fixture-robot:${row.serial_number}`, planned_end_at: row.scheduled_at, })); }, /** * ★`deleted_at` の概念が fixtures には無いので全件★（Prisma 版も絞らない。罠7）。 * ★`facilities`（施設マスタの fixtures）から id と名前だけを写す★ — * ★`cleanLogs` の `facility_name` から作らないこと★（清掃ログが1件も無い施設が * 解決できなくなり、Prisma 版と結果が食い違う）。 */ async facilityNameIndex() { return facilities.map((f) => ({ id: f.id, facility_name: f.facility_name })); }, /** * ★Prisma 版と**同じ意味**の行を返す★（指示書AK 段階3 §6-3）。 * ★★`USE_FIXTURES` の true/false で件数が変わってはいけない★★（禁止事項6）。 * * ★`deleted_at` の概念が fixtures には無いので全件★（Prisma 版も絞らない。罠7）。 * * ★所属は `Facility` 自身が持っている★（指示書AK ★段階5★）— * 段階1〜4 は `lib/fixtures/customers.ts` の `customerIdByFacilityId` という暫定マップを * 引いていたが、★段階5 で `Facility` に所属の列が載ったのでマップごと消した★。 * ★所属の割り当てを2箇所に持たないこと★（片方だけ直すと静かにズレる）。 * * ★fixtures の `group_id` は既に API の形（`null` = 所属なし）★なので変換しない * （`groupIdFromDb()` を二重に通さないこと。`lib/fixtures/facilities.ts`）。 */ async facilityGroupIndex() { return facilities.map( (f): FacilityGroupRef => ({ id: f.id, customer_id: f.customer_id, group_id: f.group_id, }) ); }, /** * ★Prisma 版と**同じ引数**を受け取り、**同じ結果**を返す★（指示書AC 段階3）。 * ★★`USE_FIXTURES` の true/false で件数が変わってはいけない★★（禁止事項6）。 */ async areaCompletions(query: AreaCompletionDbQuery) { return filterFixtureAreaCompletions(areaCompletions, query); }, /** * ★Prisma 版と**同じ引数**を受け取り、**同じ結果**を返す★（指示書AC 段階4 / 段階2 D-5）。 * ★★`USE_FIXTURES` の true/false で件数が変わってはいけない★★（禁止事項6）。 */ async prechecks(query: PrecheckDbQuery) { // ★対応状況の上書き（`PATCH /prechecks/{id}/status`）を反映してから絞る★（指示書AT 段階4-3） return filterFixturePrechecks(prechecks.map(withFixturePrecheckOverride), query); }, /** * ★Prisma 版と同じ判定★（指示書AT §3-3）— id が一致し、かつ `severity === "precheck"` の行だけ。 * ★`launch_failed` の id は null（＝404）★。 */ async precheckItemById(id: string) { const row = prechecks.find((p) => p.id === id && p.severity === "precheck"); return row ? withFixturePrecheckOverride(row) : null; }, async updatePrecheckErrorColumns(errorId: string, patch: PrecheckStatusPatch) { return applyFixturePrecheckPatch(prechecks, errorId, patch); }, /** * ★Prisma 版と同じ関数を通す★（指示書AW D13）— キー → `filterSortErrorReportKeys()` → ページ → * `errorReportItemsInPageOrder()`。★`USE_FIXTURES` で件数・並びが変わらない★（指示書AC 禁止事項6）。 * ★対応状況の上書き（`PATCH /errors/{error_id}/status`）を反映してから絞る★。 */ async errorReports(query: ErrorReportDbQuery) { const rows = errorReportRows.map(withFixtureErrorReportOverride); const keys = filterSortErrorReportKeys(rows.map(errorReportKeyFromRow), query); const items = errorReportItemsInPageOrder( errorReportPageIds(keys, query), rows, errorReportTimetables ); return { items, total: keys.length }; }, /** ★Prisma 版と同じ判定★ — `error_id === id`（大小文字を区別する。D-4）の行があれば返す */ async errorReportById(id: string) { const row = errorReportRows.find((r) => r.error_id === id); if (!row) return null; const [item] = errorReportItemsInPageOrder( [id], [withFixtureErrorReportOverride(row)], errorReportTimetables ); return item ?? null; }, async updateErrorReportColumns(errorId: string, patch: PrecheckStatusPatch) { return applyFixtureErrorReportPatch(errorReportRows, errorId, patch); }, async dsDevices() { return dsDevices; }, /** * ★Prisma 版と**同じ規則**で判定する★ — ★完全一致（`===`）★（D-4）。 * ★★`toUpperCase()` 等で緩めないこと★★ — `USE_FIXTURES` の true/false で * 404/200 が変わってはいけない（禁止事項6）うえ、緩めると孤児行が残る。 * ★fixtures には論理削除の概念が無い★ので `deleted_at` 相当の絞りは無い。 */ async dsDeviceExists(serialNumber: string) { return dsDevices.some((d) => d.serial_number === serialNumber); }, async dsAlerts() { return dsAlerts; }, /** * ★★`notImplemented` にしないこと★★（指示書AK 落とし穴9）— * 絞り込みUI（段階7）は `USE_FIXTURES=true` でも開く。ここで落とすと * ★選択肢が取れず、全画面の絞り込みが出なくなる★。 */ async groups() { return groups; }, /** * ★fixtures は `group_id` を API の形（`null` = 所属なし）で持つ★（`lib/fixtures/customers.ts`） * * ★`id` 昇順にして返す★（指示書AL 段階3 §4-4）— ★Prisma 版の `orderBy` と揃える★。 * ★規則の「正」は `sortCustomers()`★（`lib/masters/query.ts`）なので、ここで * ★比較関数を書き写さない★。★`customers` を破壊的に並べ替えないこと★（`sortCustomers()` * は複製してから並べ替える）。 */ async customers() { return sortCustomers(customers); }, async facilities() { return facilities; }, async schedules() { return schedules; }, async inspections() { return inspections; }, async inspectionDetail(id: number) { return inspectionDetails.find((i) => i.id === id) ?? null; }, /** * ★Prisma 版と**同じ判定**を通す★（指示書AI 段階4 / `CLAUDE.md` §9.5）— * ★★fixtures 用に別の判定を書かないこと★★。判定は `buildRescueRequired()` → * `judgeRescue()` の1本で、こちらは ★入力の作り方が違うだけ★。 * * ★★`notImplemented` にしないこと★★ — ダッシュボードは `USE_FIXTURES=true` でも開く。 * ★ここで落とすと、実装した本人が最初に踏む★。 * * ★入力は fixtures の清掃ログ全件★（★当日で絞らない★。R-1 は3日、R-3 は前回の日、 * R-2 は遡りぶんを必要とする）。 * ★R-3 は1回ごとの完了率の単純平均で判定する★（`meanCleanRatio()`。2026-09-30 D-151・ * 2026-10-02 D-155）ので、 * ★面積が無くても成立する★。旧: 「面積は `areaCompletions` から引く — 仕込みのある施設×日でしか * R-3 は成立しない」（R-3 が面積加重だった当時の制約。D-151 で解消）。 * * ★施設名は `facilities`（施設マスタ）から★ — `facilityNameIndex()` と同じ作り方。 * ★清掃ログの `facility_name` から作らないこと★（Prisma 版と食い違う）。 */ async rescueRequired(query: RescueDbQuery) { // ★件数の上限は渡さない★（指示書AJ 段階1。該当する施設を全部返す） // ★★分類の絞り込みは「入力の行」にかける★★（指示書AK 段階4b）— // `buildRescueRequired()` は ★渡された行に出てくる施設だけ★ を判定するので、 // ★施設名の索引（第2引数）を絞っても母集団は減らない★（あちらは名前の引き当てだけ）。 // ★`null`（絞らない）と `[]`（0件ヒット）の区別は `filterRowsByFacilityIds()` が持つ★。 return buildRescueRequired( filterRowsByFacilityIds( rescueInputsFromCleanLogs(cleanLogs, areaCompletions), query.facility_ids ), facilities.map((f) => ({ id: f.id, facility_name: f.facility_name })), query.date ); }, /** * 清掃面積（指示書AN 段階3 §6-4）。 * * ★★`notImplemented` にしないこと★★（指示書AN 落とし穴11）— 清掃面積の画面は * `USE_FIXTURES=true` でも開く。★ここで落とすと、実装した本人が最初に踏む★。 * * ★★ロールアップは Prisma 版と同じ `aggregateCleanArea()` を通す★★（`CLAUDE.md` §9.5）— * ★fixtures 用に別の集計を書かないこと★。★違うのは材料の作り方だけ★ * （こちらは `lib/fixtures/areas.ts` の面積行から作る。`cleanAreaStatsFromFixtureAreas()`）。 * * ★施設マスタは `facilities`（施設マスタの fixtures）から★ — ★所属は `Facility` 自身が * 持っている★（指示書AK 段階5）。★`group_id` は既に API の形（`null` = 所属なし）★なので * `groupIdFromDb()` を二重に通さない。★fixtures に論理削除の概念は無い★ので全件 * （Prisma 版も `deleted_at` で絞らない。★罠7★。理由は `lib/db/clean-area-source.ts`）。 * * ★番人は常に 0★ — fixtures の面積行は ★1エリア × 1日で1行★（`lib/fixtures/areas.ts` の * `build()` が施設×日のエリアの顔ぶれを検査している）ので、 * ★1つの清掃に履歴が2行ある状態を作れない★。★★0 を返すのは「異常が無い」という事実であって、 * 未実装の意味ではない★★（ここを `-1` 等にすると番人が誤発火する）。 */ async cleanArea(query: CleanAreaDbQuery) { const stats = cleanAreaStatsFromFixtureAreas(areaCompletions, query); return { stats, facilities: facilities.map((f) => ({ id: f.id, facility_name: f.facility_name, customer_id: f.customer_id, customer_name: f.customer_name, group_id: f.group_id, group_name: f.group_name, })), duplicated_timetable_count: 0, // ★完了率の材料にした fixtures の行数★（Prisma 版は取り寄せた行数。ログ用。D-156 論点2） rate_rows: stats.reduce((sum, s) => sum + s.executed_count, 0), }; }, /** * ★Prisma 版と**同じ引数**を受け取り、**同じ結果**を返す★（指示書AC 段階5 / 段階2 D-5）。 * ★★`USE_FIXTURES` の true/false で件数が変わってはいけない★★（禁止事項6）。 * 絞り込みの中身は `lib/db/fixture-reports.ts`（純粋関数）に置いてある。 */ /** * ★Prisma 版と**同じ意味**で `customer_id` で絞る★（指示書AK ★段階6★ / §2-1）— * ★`USE_FIXTURES` の true/false で数字が変わってはいけない★（禁止事項6）。 * ★fixtures のKPI行は屋号1 のもの★（`REPORT_KPI_CUSTOMER_ID`）なので、 * ★他の屋号を選ぶと 200・空のKPI★になる（6-9 と同じ形）。 */ async reportKpis(query: ReportKpiDbQuery) { return filterFixtureReportKpis(reportKpis, query); }, /** ★施設IDの絞り込み（`null` と `[]` は別物。罠9）も Prisma 版と同じ意味で効かせる★ */ async facilityPerformance(query: FacilityPerformanceDbQuery) { return filterFixtureFacilityPerformance(facilityPerformance, query); }, /** ★施設IDの絞り込み（`null` と `[]` は別物。罠9）も Prisma 版と同じ意味で効かせる★ */ async continuousProblems(query: ReportDbQuery) { return filterFixtureRowsByFacility(continuousProblems, query); }, /** * ★★fixtures だけは施設で絞りきれない（★既知の制約★。指示書AK 段階4b）★★ * * `errorBreakdown` の fixtures は ★施設をまたいで足し上げたあとの集計値★ * （`lib/fixtures/reports.ts` の `errorCounts`。`type` / `label` / `count` / `rate` しか無く、 * ★どの施設のエラーかという情報を持っていない★）ので、 * ★「屋号1の施設ぶんだけ」に割り戻すことができません★。 * * | `facility_ids` | ここでの扱い | * |---|---| * | `null`（絞らない） | ★期間の行をそのまま★ | * | ★`[]`（0件ヒット）★ | ★★空配列★★（★施設が1つも当たらない＝エラーも0件★。ここは正確） | * | ★1件以上★ | ★★全社ぶんを返す（＝絞り込みが効かない）★★ | * * ★★`USE_FIXTURES=true` のときだけ件数が多く出ます★★（禁止事項6 の例外）。 * ★直すには fixtures のエラー内訳を「施設ごとの件数」から組み立て直す必要があり、 * `rate`（全エラー件数に対する割合）の分母も作り直しになる★ため、 * ★実データの分布が分からないうちは捏造しない★（`CLAUDE.md` §7「推測で実装しない」）。 * ★Prisma 版（`facility_error_summaries` / `robot_error_reports`）は施設で絞れています★。 */ async errorBreakdown(query: ReportDbQuery) { // ★★`!== null` で分岐すること★★（罠1）— `?.length` だと `null` も `[]` も同じ枝になる if (query.facility_ids !== null && query.facility_ids.length === 0) return []; return filterFixtureReportRows(errorBreakdown, query); }, }; // ---------------------------------------------------------------- prisma /** * 実DB実装。 * * TeamWorksがDBを構築し `prisma db pull` でスキーマを取り込んだあとに実装します。 * それまでは呼ばれたら分かるように明示的にエラーを投げます * （黙って空配列を返すと「データがない」のか「未実装」なのか切り分けられないため）。 */ function notImplemented(name: string): never { throw new Error( `[db] ${name} のPrisma実装はまだありません。USE_FIXTURES=true で開発してください。` ); } /** * ★`prismaSource.cleanLogs()` と `prismaSource.cleanLogRunMeta()` が共有する `where`★（指示書AV 段階3-3 / 4-8）。 * * ★★2本で別々に書かないこと★★ — 片方だけ直すと、`pickLatestRunPerSection()` の id の突き合わせが * 静かにずれる（行に対応するメタが無ければ例外、メタが余れば無視されるだけ）。 * ★中身は `cleanLogs()` にあった `where` をそのまま移したもの★（1文字も変えていない。コメントも一緒に移した）。 */ function mainTimetableWhere( query: CleanLogDbQuery ): NonNullable { // ★★`parseDate()` の返す「真の瞬間」をそのまま渡さないこと★★ — // DB の DATETIME は日本時間の壁時計値なので9時間ずれる（指示書AC C-6）。 // ★変換は `dbDateRange()` の1箇所に閉じ込めてある（`toDbJst()` を通す）★。 // ★★ローカルDB（深夜0〜3時のデータしか無い）では付け忘れを検出できない★★ので、 // `lib/db/__tests__/date-range.test.ts` の合成データで固定している。 const range = dbDateRange(query.date_from, query.date_to); return { // ★本清掃だけを引く（メモリ側の filter をやめて SQL に降ろした）★ precheck: CLEAN_TIMETABLE_PRECHECK.main, // ★★単一ID の取得経路（指示書AC 段階3）★★ — `/clean-logs/{id}/advice` と // `/clean-logs/{id}/areas` はここを通って1件だけ引く。 // ★`clean_timetables.id` は `BigInt` 列なので `BigInt()` に包む★ — // ★Prisma の型は `number` も受け付ける（実測。`tsc` は通る）★が、 // ★★このファイルの他の箇所（`key()` / `parent_id` / `clean_timetable_id`）が // すべて `bigint` を扱っている★★ので、DB に渡す形をそこに揃えておく。 // ★`query.id` は `parsePathId()` が安全整数に限っている★ので変換で桁が落ちない。 // ★★`!== null` で分岐すること★★（罠1と同じ理由。`query.id ? ... : {}` と // 書くと `0` が「指定なし＝全件」に化ける）。 ...(query.id !== null ? { id: BigInt(query.id) } : {}), // ★`gte` も `lt` も無いときは `start_at` のキーごと付けない★ ...(range.gte || range.lt ? { start_at: range } : {}), // ★★必ず `!== null` で分岐すること★★（★罠1★）— // ★`in: undefined` は**条件が消えて全件を返す**★（生成SQL が `WHERE 1=1`）。 // ★`in: []` なら `WHERE 1=0` で0件★＝「施設名で照合したが1件も当たらなかった」。 // ★★`query.facility_ids?.length ? ... : {}` と書かないこと★★ — // ★「0件ヒット」が「全件表示」に化け、例外もテスト失敗も出ません★。 ...(query.facility_ids !== null ? { facility_id: { in: query.facility_ids } } : {}), }; } const prismaSource: DataSource = { /** * 清掃詳細ログ（F-02）＋ ダッシュボード（F-01）＋ アラート（F-03）が使う一覧。 * * ★★`include` が使えないので手動 join する★★（指示書R 落とし穴1 / D-092 項3-3） * `clean_statuses.clean_timetable_id`（`prisma/schema.prisma:445`）/ * `clean_task_reports.clean_timetable_id`（`:524`。★nullable★。指示書AQ 決定2/3 で * `clean_status_histories` から差し替えた）/ * `robot_error_reports.clean_timetable_id`（`:322`）には ★FK も KEY も無い★。 * Prisma のリレーションが張られていないため `include` で辿れない。そこで * 別クエリで取得し、`clean_timetable_id` をキーにメモリ上で突き合わせている。 * ★D-094 で TeamWorks に FK 追加を再依頼中★。FK が付いたらこの手動 join は * そのまま `include` に書き換えられる（そのときは下の Map 3本が消える）。 * * ★1回の清掃は `clean_timetables` の3行で表される★（D-092 項1）: * `precheck = 0` … 本清掃（`parent_id = 0`）… これが `CleanLogItem` 1件の骨格 * `precheck = 1` … 1回目の事前チェック（60分前）… `parent_id` = 本清掃の id * `precheck = 2` … 2回目の事前チェック（30分前）… 同上 * * ★`deleted_at` はこの4テーブルのどれにも無い★ので論理削除で絞らない。 * `clean_timetables.inactive` でも絞らない（第1歩・第2歩と同じ方針。指示書R 禁止事項4/5）。 * ★★`include: { facility: true }` にも `deleted_at` の条件が無い★★ — * ★論理削除された施設のログも返している★（それが現状の挙動）。 * ★★だから施設名の解決も `deleted_at` で絞らない★★（罠7。 * `lib/db/facility-name-source.ts`）。 * * ★★性能（指示書AC 段階2 で解決）★★: 以前は `DataSource` が引数を取らない契約だったため * ★全期間・全件★を読んでいた（D-092 項3-3。保持2年で `clean_timetables` は約26万行）。 * ★★いまは日付範囲・施設ID・単一ID・本清掃（`precheck = 0`）・並び順を SQL に降ろしている★★ * （★単一ID（`query.id`）は段階3。`/clean-logs/{id}/advice` と `/{id}/areas` が使う★）。 * ★索引は最初から張られている★（`@@index([start_at])` / `@@index([facility_id])` / * `@@index([parent_id])`。`prisma/schema.prisma`）ので、TeamWorks への依頼は要らない。 * * ★★降ろせないもの★★（指示書AC C-1。★取得後にメモリで絞る★）: * - ★判定（◎○△×）★ … 完了率（`runCompletionRate()`）から `judgeGrade()` で計算しており DB に列が無い * - ★連続日数 / エスカレーション★ … 日をまたいで数える（D-026） * - ★機種 / シリアルの部分一致★ … 索引が効かず利得が薄いので据え置き * - ★施設名の部分一致★ … ★記号を無視する照合★なので LIKE では書けない。 * ★API ルート側で `resolveFacilityIdsByName()` が施設IDに解決してから渡す★ * - ★`take` / `skip`★ … 判定フィルタが SQL で絞れないため、降ろすと `meta.total` が * 食い違う（指示書AC D-3。★P1ではやらないという決定★） * * ★★連続日数だけは「表示期間そのもの」で絞らない★★（★★指示書AC C-2 の地雷★★）— * 期間で絞ると前日のデータが消えて ★連続が途切れ、L3 が L1 に化ける * （例外もテスト失敗も出ない）★。★★`loadConsecutiveInputs()` は表示期間の手前を * 「保存された表示上限 +1日」ぶん遡って読む★★（段階6）。★遡り幅の計算を * ここに書き下さないこと★ — 3経路で食い違う（D-109 の再発防止）。 */ async cleanLogs(query: CleanLogDbQuery) { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); // ★★予定は `clean_timetables` と `clean_timetable_histories` の両方から読む★★ // （指示書AU 段階3b。第11回 P-7。★同じ `args` を2表に渡す・同じ id は本表を採る★のは `findTimetables()`） const mainTimetables = await findTimetables(prisma, { where: mainTimetableWhere(query), // ★リレーションがある結合先は include してよい（落とし穴1 は FK が無い3テーブルの話）★ include: { facility: true, section: { include: { robots: { where: { deleted_at: null }, include: { device: true }, }, }, }, }, // ★並び順も SQL に降ろす（`start_at` に索引がある）★。 // ★下の `.sort()` は残す★ — 規則の正はデータソースの戻り値であって // `orderBy` はその写し（C-5 と同じ理由。`sort` は安定なので二度手間にならない）。 // ★★同着の第2キーは `id` の**昇順**★★ — ★指示書AC D-4 の例は `id: "desc"` だが、 // ★★下の `.sort()` が以前から `a.id - b.id`（昇順）で並べている★★ので、 // そちらに合わせる（★段階2 はレスポンスを1バイトも変えない★。指示書AC 禁止事項14）。 // ★★2表を合わせるので、DB の順序はもう写しにもならない★★（指示書AU 段階3b-2 の 3）— // ★順序の正は下の `.sort()` だけ★。 orderBy: [{ start_at: "desc" }, { id: "asc" }], }); // BigInt はキーとして === で比較できないので文字列化して引く const key = (id: bigint) => id.toString(); // ★引いた本清掃の id で、関連する行を引き直す★（★全件読みに戻さないこと★）。 // ★`in` の要素数には上限がある★（`DB_IN_CLAUSE_MAX_ITEMS`。指示書AC §E-5）— // ★★超える場合は分割する（`facility_id` + 日付での絞り直しは採らない）★★。 // 理由は `DB_IN_CLAUSE_MAX_ITEMS` の docstring（別経路で行が選ばれると // ずれたときに行が静かに落ちる）。 // ★塊が0個（本清掃が0件）ならクエリを1本も撃たない★。 const mainIds = mainTimetables.map((row) => row.id); const mainIdChunks = chunkForInClause(mainIds); // ★事前チェック行（`precheck !== 0`）は `parent_id` で別クエリに分ける★（指示書AC D-4）— // ★★1回のクエリで `precheck` 混在のまま引いて、あとでメモリで分けるやり方に // 戻さないこと★★（それだと本清掃の絞り込みが SQL で効かない）。 // ★`parent_id` には索引がある★（`clean_timetables_parent_id_index`）。 // ★読む列は3つだけ★ — 下で使うのは `parent_id` / `precheck` / `id` のみ // （事前チェック行の `facility` や `section` は使わないので `include` しない）。 // ★★2表から読み、全塊を合わせてから1回だけ id で重複を落とす★★（指示書AU 段階3b-3）— // 2表で `parent_id` が違う同じ id は別の塊に入りうるので、塊の中の重複落としだけでは足りない。 const precheckRows = await findTimetablesByChunks(prisma, mainIdChunks, (ids) => ({ where: { parent_id: { in: ids } }, select: { id: true, parent_id: true, precheck: true }, })); // ★FK が無いテーブルは別クエリ＋メモリ上の手動 join★ // ★清掃結果（`clean_task_reports`）は**本清掃の id**、エラー報告は**事前チェック行の id** // でしか引かない★（下の組み立てがそれぞれその id でしか Map を引かないため。★絞りすぎていない★） // ★★清掃結果の取得元は `clean_task_reports`★★（指示書AQ 決定2/3。2026-09-30。 // `clean_status_histories` は使わない）。 // ★`clean_timetable_id` が NULL のレポートは `in` に一致しない★ので、ここで引けない // （＝その本清掃は「レポートの行が無い」＝出発失敗として出る。指示書AQ 罠1 / 決定5） const precheckIds = precheckRows.map((row) => row.id); const [reportChunks, errorReportChunks] = await Promise.all([ Promise.all( mainIdChunks.map((ids) => prisma.cleanTaskReport.findMany({ where: { clean_timetable_id: { in: ids } }, }) ) ), Promise.all( chunkForInClause(precheckIds).map((ids) => prisma.robotErrorReport.findMany({ where: { clean_timetable_id: { in: ids } }, // ★`robot_id` / `robot` を読まない（NULL の行で落ちないため。指示書AU 段階0-4）★ select: ROBOT_ERROR_STATUS_SELECT, }) ) ), ]); const taskReports = reportChunks.flat(); const errorReports = errorReportChunks.flat(); // ★レポートを1件に絞る規則は `latestReportByTimetableId()` の1箇所★（D-107 / 指示書AQ §1-4）— // `prechecks()` と同じ関数を使う。★順序キー（`ended_at ?? started_at`）を決めるのもあちら★。 // ★ここで `orderBy` を足したり別の順序キーを書かないこと★（`/detail-log` と `/alerts` で // 選ばれる行が食い違う。D-103 が禁じた状態） const reportByTimetableId = latestReportByTimetableId(taskReports); const errorsByTimetableId = new Map(); for (const report of errorReports) { // ★nullable（清掃タイムテーブルに紐づかないエラーがありうる。`prisma/schema.prisma:322`）★ if (report.clean_timetable_id === null) continue; const k = key(report.clean_timetable_id); const list = errorsByTimetableId.get(k); const entry: RobotErrorLike = { error_type: report.error_type, errored_at: report.errored_at, }; if (list) list.push(entry); else errorsByTimetableId.set(k, [entry]); } // parent_id（本清掃の id）→ precheck コード → 事前チェック行 // ★`precheckRows` は `parent_id: { in: 本清掃の id }` で引いた行★（＝本清掃行は入らない）。 // ★それでも `precheck === main` を弾く行は残す★ — `parent_id` が 0 の本清掃行が // 混ざる余地（`parent_id = 0` を指す行）を潰しておくため。★条件を緩めないこと★ const precheckByParent = new Map>(); for (const row of precheckRows) { if (row.precheck === CLEAN_TIMETABLE_PRECHECK.main) continue; const k = key(row.parent_id); const byCode = precheckByParent.get(k) ?? new Map(); byCode.set(row.precheck, row); precheckByParent.set(k, byCode); } // ★予定時刻がまだ来ていない本清掃は**行ごと結果に含めない**★（`prechecks()` と同じ判定） // 清掃詳細ログ（F-02）は「実施済みの記録」であり、未実施の未来予定を // 「×・未実施」として出すと `computeConsecutiveProblemDays()` の連続日数まで水増しされる。 // ★★`isFutureSchedule()` は D-107（設計3-C）の下では**必須**。外さないこと★★ — // 未来の予定にはまだレポートの行が無く、`notExecutedFromReport()` は // 「レポートの行が無い」を出発失敗と判定するので、★外すと未来の清掃が全部「出発失敗」になる★。 // ★★逆に「レポートがあること」をこのフィルタに足さないこと★★（D-107 設計3-C）— // ★レポートの行が無い過去の本清掃も**返す**（出発失敗として画面に出す）★。 // 足すと、データ収集処理の障害で結果が書かれなかった清掃が // ★件数がそっと減るだけで画面から消える★（fail-silent）。 // ★`now` は1回だけ作って全行で使い回す★（行ごとに作ると境界の行の扱いがぶれる） // ★★`precheck === main` の絞り込みは SQL に降ろした★★（指示書AC 段階2 D-4）ので、 // ここに残っているのは ★未来の予定を外す条件だけ★。 // ★★SQL 側の `where` から `precheck` を外さないこと★★ — 外すと事前チェック行が // 一覧の行として並ぶ（`section.robots[0]` が同じなので例外にもならない）。 const now = new Date(); const mainRows = mainTimetables.filter( (row) => !isFutureSchedule(fromDbJst(row.start_at), now) ); // 先に骨格（judge に渡す値まで）を作る。連続日数は全行が揃わないと数えられないため2段構え const drafts = mainRows.map((row) => { // ★P1は1清掃エリア=1ロボットの前提（CLAUDE.md §8）★。0台なら静かに空文字を返さず例外 // （`schedules()` の :301-306 と同じ作法） const robot = row.section.robots[0]; if (!robot) { throw new Error( `[db] cleanLogs: clean_timetables(id=${row.id}) の section(id=${row.section_id}) にロボットが見つかりません。P1は1清掃エリア=1ロボットの前提です。` ); } const precheckRows = precheckByParent.get(key(row.id)); // ★status_1h / status_30m の列の割り当ては「分数の一致」ではなく「順番」★（D-178。ユーザー判断 2026-10-16）— // 事前チェックの分数は設定で変わりうる（例: 60/10）ので、早い方を1回目・遅い方を2回目にする。 // `precheckRows`（`precheck` の生値 → 行）を「`precheck` の生値 → エラー配列」に // 詰め替えてから、規則を1箇所に持つ `statusColumnsFromPrecheckRows()` に渡す。 // ★予定行があればエラーが無くても空配列でキーを入れる★ — ★キーが無い回は null（予定が無い）になる★ // （ユーザー指示 2026-10-07。D-171）。★`?? []` を外したりエラーの有無で入れ分けたりしないこと★ // （入れ分けると、異常なしの回が消えて列がずれる） const errorsByPrecheck = new Map(); if (precheckRows) { for (const [precheck, precheckRow] of precheckRows) { errorsByPrecheck.set( precheck, errorsByTimetableId.get(key(precheckRow.id)) ?? [] ); } } const precheckColumns = statusColumnsFromPrecheckRows(errorsByPrecheck); // ★列は2つしか無いので、3つ以上の事前チェックは開始に近い2つだけ残る★（1清掃2回で固定なので通常は起きない）。 // ★黙って捨てない★ — 捨てた分数をこの行の id と一緒に残す（原因の断定は書かない）。 // ★データ層はルートを知らないので `route` / `method` は載せない★（不明な情報は書かない） if (precheckColumns.dropped.length > 0) { logEvent("warn", { event: "data.anomaly", metric: "precheck_rounds_per_main_run", expected: PRECHECK_COLUMN_COUNT, actual: precheckColumns.dropped.length + PRECHECK_COLUMN_COUNT, clean_timetable_id: String(row.id), dropped_precheck_minutes: precheckColumns.dropped, }); } // ★「出発したか」は DB の値で決める。「予定＋猶予30分」を当方で計算しない★ // （D-091 項1 / 指示書R 禁止事項3。LAUNCH_GRACE_MINUTES はここから読まない） // ★★出発失敗（未実施）＝ 本清掃に対応する `clean_task_reports` の行が無い★★ // （指示書AQ §1-1。旧取得元の `clean_error === 1` の分岐は、列が無いので消えた）。 // ★判定そのものは `notExecutedFromReport()`（clean-log-mapping.ts）に切り出してある★ — // `prechecks()` の `launch_failed` が同じ判定を共有するため（D-103 項1）。 // ★条件を**ここに書かないこと**★（書くと規則が2箇所に散る）。 // ★`status` を未実施の判定に使わないこと★（値の意味は第10回 N-2 で受領済みだが、 // 判定には使わない。D-155 項2。ユーザー決定 2026-10-02。指示書AQ §1-2 / D-077） const report = reportByTimetableId.get(key(row.id)); return { id: Number(row.id), facility_id: Number(row.facility_id), facility_name: row.facility.facility_name, model_name: formatModelName(robot.device.maker_id, robot.device.model_name), serial_number: robot.serial_number, // ★DBのDATETIMEには日本時間の壁時計値が入っている（TeamWorks第8回A2。指示書Y）。 // Prismaから出たDateは必ずjstIsoFromDb()を通す（toJstIso()に直接渡さない）★ scheduled_at: jstIsoFromDb(row.start_at), status_1h: precheckColumns.status[0], status_1h_minutes: precheckColumns.minutes[0], status_30m: precheckColumns.status[1], status_30m_minutes: precheckColumns.minutes[1], departed: !notExecutedFromReport(report), // ★`clean_task_reports.status` の生値をそのまま運ぶ（変換しない。指示書AQ §1-2 / D-077）★。 // ★レポートの行が無ければ null★。★旧 `clean_error` から改名した（指示書AQ §5-2）★ — // ★中身が別の列になったので、旧コード表（0:正常 / 1:未実施 …）で読まれないようにするため★。 // ★★`??` を `||` にしないこと★★ — `status` の既定値は `0`（`prisma/schema.prisma`）で、 // `||` だと ★0 が null に化ける★（`tsc` も `lint` も捕まえない） task_status: report?.status ?? null, // ★結果待ち（ユーザー判断 2026-10-07。D-173）★ — 判定は `isResultPending()` の1本。 // ★`departed` / `task_status` / `completion_rate` / `grade` は結果待ちでも変えない★（別の旗で表す）。 // ★`end_at` は `start_at` と同じ JST の壁時計値なので `fromDbJst()` を通す★（9時間を足さない・引かない）。 // ★`now` は上で作った同じインスタンス★（`mainRows` の未来の予定の除外と基準時刻を揃える） result_pending: isResultPending({ startAt: fromDbJst(row.start_at), endAt: fromDbJst(row.end_at), now, hasReport: !notExecutedFromReport(report), }), // ★丸めない生値（CLAUDE.md §4.3）。未実施（レポートなし）は null★ // ★★`report ? report.clean_ratio : null` の形に戻さないこと★★ — 判定を // `completionRateFromReport()` の外に書くと、`departed` と規則が2箇所に散る // （★`departed === false` ⟺ `completion_rate === null`★ の不変条件。P-5=B で `task_area = 0` が // 0 になり両向きに成り立つ。D-107 落とし穴1 / D-155 / D-156 / D-158） completion_rate: completionRateFromReport(report), }; }); // ★連続日数は施設ごとの全期間走査（D-026 / D-090 項15 / D-109）★ // ★★入力は `loadConsecutiveInputs()`（`lib/db/consecutive-source.ts`）の1本に集約してある★★ // （`facilityPerformance()` / `continuousProblems()` と同じ1本。D-109 の再発防止）。 // ★★`drafts` から作らないこと★★ — ★段階2 で `drafts` は期間・施設で絞られた★ので、 // そこから作ると期間の外にある前日のデータが消えて連続が途切れる // （指示書AC C-2。★L3 が L1 に化ける fail-silent★）。 // ★★段階6: `loadConsecutiveInputs()` には「★表示したい期間そのもの★」を渡すこと★★ — // ★遡りぶん（保存された表示上限 +1日）は同関数が足す★（★ここで足さないこと★。 // 3経路が別々の遡り幅を持つと `/detail-log` と `/reports` で数字が食い違う。D-109）。 // ★★`query.date_from` が `null`（単一ID取得など）なら下限なし＝全期間のまま★★。 // ★`now` は上で作った同じインスタンスを渡す★（`mainRows` の絞り込みと基準時刻を揃える） const consecutiveRange: ConsecutiveDbRange = { date_from: query.date_from, date_to: query.date_to, }; const consecutiveById = computeConsecutiveProblemDays( await loadConsecutiveInputs(prisma, now, consecutiveRange) ); return drafts .map((draft): CleanLogItem => { const consecutive = consecutiveById.get(draft.id) ?? 0; return { ...draft, // ★judge は prismaSource の中で呼ぶ（D-090 項16）。fixtures 版も同じ関数を通している★ grade: judgeGrade(draft.completion_rate), consecutive_problem_days: consecutive, escalation_level: judgeEscalationLevel(consecutive), }; }) // ★fixtures と同じ「新しい順」で返す（lib/fixtures/clean-logs.ts:227-233）★ // APIルート側は並べ替えないので、順序はデータソースの責任 .sort((a, b) => { if (a.scheduled_at !== b.scheduled_at) { return a.scheduled_at < b.scheduled_at ? 1 : -1; } return a.id - b.id; }); }, /** * ★清掃ログの id → { 清掃エリア, 予定の終了 }★（ダッシュボードの直近モード専用。D-159 / 指示書AV 段階3-3）。 * * ★★`where` は `cleanLogs()` と同じ `mainTimetableWhere()`★★（4-8）— 別に書くと、片方だけ直したときに * `pickLatestRunPerSection()` の突き合わせが静かにずれる。 * ★`findTimetables()` で2表から読む★（同じ id は本表が勝つ。指示書AU 段階3b）。 * ★`prisma.cleanTimetable.findMany` を直接呼ばないこと★ — 履歴側だけにある予定のメタが欠け、E1 の例外になる。 * ★`end_at` は `start_at` と同じ DATETIME の JST 壁時計値★なので `jstIsoFromDb()` を通す * （★9時間を足さない・引かない★。`CLAUDE.md` §3 / 指示書AV 4-3）。 * ★`cleanLogs()` が外す未来の予定（`isFutureSchedule()`）もここには載る★ — 呼び出し側は無視する（表2 E6）。 */ async cleanLogRunMeta(query: CleanLogDbQuery) { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); const rows = await findTimetables(prisma, { where: mainTimetableWhere(query), // ★`id: true` は必須★（2表の重複を id で除くため。`TimetableFindManyArgs` が型で強制している） select: { id: true, section_id: true, end_at: true }, }); return rows.map((row) => ({ id: Number(row.id), section_key: `section:${row.section_id.toString()}`, planned_end_at: jstIsoFromDb(row.end_at), })); }, /** * ★施設名 → 施設ID の解決★用の最小限の一覧（指示書AC 段階2 D-6）。 * * ★★`facilities()` を流用しないこと★★ — あちらは `where: { deleted_at: null }` を付けている。 * ★論理削除された施設のログは `cleanLogs()` にいま出ている★ので、ここで絞ると * ★その施設名で検索したときにログが静かに消える★（★罠7★）。 * ★読み取り（`where` を付けない理由を含む）は `loadFacilityNameIndex()` に閉じ込めてある★。 */ async facilityNameIndex() { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); return loadFacilityNameIndex(prisma); }, /** * ★分類（ホールディングス／屋号）→ 施設ID の解決★用の最小限の一覧（指示書AK 段階3 §6-3）。 * * ★★`facilities()` を流用しないこと★★ — あちらは `where: { deleted_at: null }` を付けている。 * ★論理削除された施設のログは `cleanLogs()` にいま出ている★ので、ここで絞ると * ★屋号やホールディングスで絞った瞬間にそのログが静かに消える★（★罠7★）。 * ★読み取り（`where` を付けない理由・`group_id` の 0 → null 変換を含む）は * `loadFacilityGroupIndex()` に閉じ込めてある★。 */ async facilityGroupIndex() { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); return loadFacilityGroupIndex(prisma); }, /** * エリア別完了率（F-02 のエリアモーダル。GET /clean-logs/{id}/areas）。 * * ★出所★: TeamWorks 第8回 A9-2（2026-09-11 受領）— * 「エリア毎の清掃完了率は取得可能。正確に言えば清掃ロボット毎の清掃率だが、 * 清掃ロボットはエリアに紐づいている」。つまり ★1エリア（=1ロボット）につき1つの完了率★ * であり、★1回の清掃の中を売り場・通路・レジ前に区切った区域別の内訳ではない★ * （確認事項#10 の本来の問いは未解決のまま。第9回で聞き直し中）。 * * ★★データ元は `clean_task_reports`★★（指示書AQ 決定2/3。2026-09-30。 * ★旧: `clean_status_histories`。指示書Z 決定6 の「`clean_task_reports` は読まない」は * ★取得元の一本化で失効した★）。 * ★`cleanLogs()` が読んでいるのと**同じテーブル・同じ規則**で完了率を作る★という理由は * 変わっていない — 別テーブルから作ると、★同じ画面（一覧の行 → そこから開くモーダル）に * 定義の違う2つの完了率が並ぶ★。★両方を同時に `clean_task_reports` へ切り替えた★。 * * ★★行と全体の完了率★★: * - ★各行の `completion_rate` は `completionRateFromReport()`＝1回ごとの完了率（`runCompletionRate()`）★。 * ★`cleanLogs()` と同じ関数を通す★（別の書き方をすると `cleanLogs()` の完了率と食い違う）。 * - ★全体率は行の `completion_rate` の単純平均（清掃1回＝1票。未実施の行は除く）★ — * ★計算しているのは APIルート側の `buildAreaCompletions()`（`lib/clean-logs/areas.ts`）★。 * ここでは行を返すだけで、全体率は出さない。 * - ★この層が運んでいる面積（`clean_area` / `task_area`）は表示用★。全体率の分子・分母ではない * （行の完了率は面積から作るが、それは `completionRateFromReport()` の中で1回ずつ行う） * （`CLAUDE.md` §4.2。★以前は全体率だけ面積ベースの「意図した非対称」だった（指示書Z 決定7）が、 * 2026-09-30 に単純平均へ揃えた。D-151 / 指示書AQ §5-5★）。 * * ★`cleanLogs()` と同じ作法で書いてある★（新しい読み方を発明しない）: * `section` はリレーションがあるので `include`、`clean_task_reports` は * ★FK も KEY も無いので別クエリ＋手動 join★、レポートの1件への絞り込みは * ★`latestReportByTimetableId()`（同じ関数）★、未来の予定は ★`isFutureSchedule()`★ で除外。 * * ★★`cleanLogs()` のような「ロボット0台なら例外」の処理は入れない★★ — * この API は ★ロボットではなくエリアを列挙する★ので、`section_name` があれば足りる * （`AreaCompletionRow` は `serial_number` を持たない）。★ロボット0台の施設を落とさないこと★。 * * ★★性能（指示書AC 段階3 で解決）★★: 以前は引数を取らず ★全期間・全件★ を読んでいた * （実測 1,582行。しかもエリアモーダルは ★1施設の1日ぶんしか使わない★）。 * ★★いまは施設ID・日付1日ぶん・本清掃（`precheck = 0`）を SQL に降ろしている★★。 * ★索引は最初から張られている★（`@@index([facility_id])` / `@@index([start_at])`）。 * * ★★連続日数は関係しない★★ — この API は連続日数を返さないので、 * `cleanLogs()` のような「全期間を読み続ける1本」（C-2 / C-3）は要らない。 */ async areaCompletions(query: AreaCompletionDbQuery) { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); // ★★`query.date` の生の文字列から `Date` を作らないこと★★ — DB の DATETIME は // 日本時間の壁時計値なので9時間ずれる（指示書AC C-6）。★変換は `dbDateRange()` の1箇所★。 // ★1日ぶんなので `from` と `to` に同じ日を渡す★（`to` はその日を含む＝翌日 00:00 未満）。 const range = dbDateRange(query.date, query.date); // ★予定は2表から読む（指示書AU 段階3b。`findTimetables()`）★ const timetables = await findTimetables(prisma, { where: { // ★事前チェック行を混ぜない（本清掃だけ）★ — ★メモリ側の filter をやめて SQL に降ろした★ // ★★SQL 側の `where` から `precheck` を外さないこと★★（`cleanLogs()` と同じ。 // 外すと事前チェック行がエリアとして並ぶ。`section` が同じなので例外にもならない） precheck: CLEAN_TIMETABLE_PRECHECK.main, // ★★`!== null` で分岐すること★★（罠1と同じ理由）。 // ★`clean_timetables.facility_id` は `BigInt` 列なので包む★ // （理由は `cleanLogs()` の `query.id` と同じ） ...(query.facility_id !== null ? { facility_id: BigInt(query.facility_id) } : {}), ...(range.gte || range.lt ? { start_at: range } : {}), }, // ★リレーションがある結合先は include してよい（FK が無いのはレポート側）★ include: { section: true }, }); // ★FK が無いテーブルは別クエリ＋メモリ上の手動 join★（`cleanLogs()` と同じ）— // ★★全件読みに戻さないこと★★。★引いた本清掃の id で引き直す★（指示書AC D-4 / §E-5。 // `in` の要素数の上限と分割は `chunkForInClause()` に閉じ込めてある）。 // ★塊が0個（本清掃が0件）ならクエリを1本も撃たない★。 // ★取得元は `clean_task_reports`★（指示書AQ 決定2/3。`cleanLogs()` と同時に切り替えた） const reportChunks = await Promise.all( chunkForInClause(timetables.map((row) => row.id)).map((ids) => prisma.cleanTaskReport.findMany({ where: { clean_timetable_id: { in: ids } }, }) ) ); // ★レポートを1件に絞る規則は `latestReportByTimetableId()` の1箇所★（D-107 / 指示書AQ §1-4） const reportByTimetableId = latestReportByTimetableId(reportChunks.flat()); // ★`now` は1回だけ作って全行で使い回す★（行ごとに作ると境界の行の扱いがぶれる） const now = new Date(); return timetables .filter( (row) => // ★★外すと未来の予定が「未実施」として並ぶ★★（D-107 / D-109。`cleanLogs()` と同じ理由） // ★★`precheck === main` の絞り込みは SQL に降ろした★★ので、 // ここに残っているのは ★未来の予定を外す条件だけ★。 !isFutureSchedule(fromDbJst(row.start_at), now) ) .map((row): AreaCompletionRow => { const report = reportByTimetableId.get(row.id.toString()); return { clean_log_id: Number(row.id), facility_id: Number(row.facility_id), // ★DBのDATETIMEは日本時間の壁時計値（指示書Y / D-115）★。 // ★★`row.start_at` の生の `Date` で日付を作らないこと★★（9時間ずれる） date: jstIsoFromDb(row.start_at).slice(0, 10), section_id: Number(row.section_id), // ★`sections.section_name` の生値。当方で整形しない★ section_name: row.section.section_name, // ★未実施は `null`（`0`＝「0%で実施した」と混ぜない）★（D-107 落とし穴1） completion_rate: completionRateFromReport(report), // ★DBの値をそのまま足す（未実施だからといって当方で 0 に潰さない）★ // ★`aggregateCleanStatsByFacility()` と**同じ扱い**★（指示書Z 決定13）。 // ★★`??` を `||` にしないこと★★ — 面積は `0` が正当な値 // ★面積は残す（指示書AQ §1-3）。★全体率の分子・分母には使わない★ // （行の完了率は上の `completionRateFromReport()` が面積から1回ずつ出す。D-155） clean_area: report?.clean_area ?? 0, task_area: report?.task_area ?? 0, }; }); }, /** * アラート（事前チェック）一覧（F-03）。 * * ★★2種類の行を1つの配列にまとめて返す★★: * * 1. `severity: "precheck"` … ★事前チェック行に紐づく `robot_error_reports` の行★ * 2. `severity: "launch_failed"` … ★本清掃が実施されなかったこと★ * （★対応する `clean_task_reports` の行が無い★。D-103 / D-107 / 指示書AQ §1-1。 * ★旧取得元 `clean_status_histories` の `clean_error === 1` の分岐は、列が無いので消えた★） * * ★2番目がエラー行由来でない点に注意★ — `launch_failed` は * `cleanLogs()` の `departed === false` と ★同じ出来事★ なので、 * ★同じ判定（`notExecutedFromReport()`）を共有する★（D-103。指示書S の B案）。 * ★「本清掃行を指すエラー行」を `launch_failed` に読み替えてはいけない★ — * それをすると「エラー行があること」が出発失敗の条件になり、`departed` と別定義になる。 * * ★★`include` が使えないので手動 join する★★（`cleanLogs()` と同じ。指示書S 落とし穴1） * `robot_error_reports.clean_timetable_id`（`prisma/schema.prisma:322`）には * ★FK も KEY も無く（しかも `BigInt?`）★、Prisma のリレーションが張られていないため * `include` で `clean_timetables` を辿れない。そこで別クエリで取得し、 * `clean_timetables.id` をキーにメモリ上で突き合わせている。 * ★D-094 で TeamWorks に FK 追加を再依頼中★。FK が付いたら `include` に書き換えられる。 * * ★`robot_error_reports` に `deleted_at` は無い★（`prisma/schema.prisma:309-353`）ので * 論理削除で絞らない。`clean_timetables.inactive` でも絞らない（第1〜3歩と同じ方針）。 * * ★フィルタ・ソート・ページングはここでやらない★（`DataSource` の設計方針）— * `app/api/prechecks/route.ts` が `sortPrechecks()`（D-052）等で行う。 * * ★★性能（指示書AC 段階4 で解決）★★: 以前は引数を取らず ★全期間・全件★ を読んでいた * （`robot_error_reports` 49 + `clean_timetables` 1,044 + `clean_status_histories` 538 * ＝ ★実測 1,631行★。指示書AC B-3）。★★いまは日付範囲・施設ID・本清掃 * （`precheck = 0`）を SQL に降ろしている★★。★索引は最初から張られている★ * （`@@index([start_at])` / `@@index([facility_id])` / `@@index([parent_id])`）。 * * ★★2種類の行を**同じ期間**で絞る★★（指示書AC 段階4。★片方だけ絞ると静かに壊れる★）: * ★どちらの行も期間の基準は「本清掃行の `start_at`」★（`PrecheckDbQuery` の型コメント） * なので、★★本清掃行を1回絞れば両方に効く★★。引く順は * ★本清掃行（期間・施設で絞る）→ その子の事前チェック行（`parent_id`）→ * そのエラー行（`clean_timetable_id`）★。 * ★★エラー行を `errored_at` で絞らないこと★★ — `scheduled_at` に入るのは * ★親の本清掃行の `start_at`★（指示書S 3-2 項5）なので、 * `filterPrechecksByDate()`（`scheduled_at` で絞る）と食い違う。 * * ★★連続日数は関係しない★★ — この API は連続日数を返さないので、 * `cleanLogs()` のような「全期間を読み続ける1本」（C-2 / C-3）は要らない。 */ async prechecks(query: PrecheckDbQuery) { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); // ★★`query.date_from` の生の文字列から `Date` を作らないこと★★ — DB の DATETIME は // 日本時間の壁時計値なので9時間ずれる（指示書AC C-6）。★変換は `dbDateRange()` の1箇所★。 // ★★ローカルDB（深夜0〜3時のデータしか無い）では付け忘れを検出できない★★ので、 // 合成データのテストで固定している（`app/api/prechecks/__tests__/route.test.ts`）。 const range = dbDateRange(query.date_from, query.date_to); // ★★本清掃行だけを、期間・施設で絞って引く★★（`cleanLogs()` と同じ作法）— // ★★SQL 側の `where` から `precheck` を外さないこと★★。外すと事前チェック行が // 下の `launch_failed` のループに入り、★1回の清掃につき3件の出発失敗★ が並ぶ // （`section.robots[0]` が同じなので例外にもならない）。 // ★予定は2表から読む（指示書AU 段階3b。`findTimetables()`）★ const timetables = await findTimetables(prisma, { where: { precheck: CLEAN_TIMETABLE_PRECHECK.main, // ★`gte` も `lt` も無いときは `start_at` のキーごと付けない★ ...(range.gte || range.lt ? { start_at: range } : {}), // ★★`!== null` で分岐すること★★（★罠1★）— // ★`in: undefined` は**条件が消えて全件を返す**★（生成SQL が `WHERE 1=1`）。 // ★`in: []` なら `WHERE 1=0` で0件★＝「分類で絞ったが1件も当たらなかった」。 // ★★`query.facility_ids?.length ? ... : {}` と書かないこと★★ // （`cleanLogs()` と同じ理由。0件ヒットが全件表示に化ける）。 // ★`clean_timetables.facility_id` は `BigInt` 列なので1件ずつ包む★ ...(query.facility_ids !== null ? { facility_id: { in: query.facility_ids.map((id) => BigInt(id)) } } : {}), }, include: { facility: true, // 出発失敗の行の `serial_number` に必要（エラー行が無いので報告側から取れない） section: { include: { robots: { where: { deleted_at: null } } } }, }, }); // BigInt はキーとして === で比較できないので文字列化して引く const key = (id: bigint) => id.toString(); // ★★`timetableById` は**本清掃行だけ**を持つ★★（以前は全行を持っていた）— // 下の `mainRow` の引き当てはこの Map で行う。★期間の外の本清掃行は入らない★ので、 // ★親が期間外のエラー行は結果に出ない★（＝2種類の行が同じ期間で絞られる）。 const timetableById = new Map(timetables.map((row) => [key(row.id), row])); // ★引いた本清掃の id で、関連する行を引き直す★（★全件読みに戻さないこと★）。 // ★`in` の要素数の上限と分割は `chunkForInClause()` に閉じ込めてある★（§E-5）。 // ★塊が0個（本清掃が0件）ならクエリを1本も撃たない★。 const mainIdChunks = chunkForInClause(timetables.map((row) => row.id)); // ★事前チェック行は `parent_id` で別クエリに分けて引く★（`cleanLogs()` と同じ。指示書AC D-4）— // ★★1回のクエリで `precheck` 混在のまま引いて、あとでメモリで分けるやり方に // 戻さないこと★★（それだと期間の絞り込みが SQL で効かない）。 // ★読む列は3つだけ★ — 下で使うのは `id` / `parent_id` / `precheck` のみ。 // ★★2表から読み、全塊を合わせてから1回だけ id で重複を落とす★★（`cleanLogs()` と同じ。指示書AU 段階3b-3） const precheckRows = await findTimetablesByChunks(prisma, mainIdChunks, (ids) => ({ where: { parent_id: { in: ids } }, select: { id: true, parent_id: true, precheck: true }, })); const precheckRowById = new Map(precheckRows.map((row) => [key(row.id), row])); const [errorReportChunks, reportChunks] = await Promise.all([ // ★エラー行は**事前チェック行の id**でしか引かない★ — // ★本清掃行を指すエラー行は `launch_failed` に読み替えない★（D-104）ので要らない。 // ★facility は FK があるので include してよい（落とし穴1 は FK が無い列の話）★ Promise.all( chunkForInClause(precheckRows.map((row) => row.id)).map((ids) => prisma.robotErrorReport.findMany({ where: { clean_timetable_id: { in: ids } }, // ★`robot_id` / `robot` を読まない（NULL の行で落ちないため。指示書AU 段階0-4）★ select: ROBOT_ERROR_PRECHECK_ROW_SELECT, }) ) ), // ★清掃結果（`clean_task_reports`）は**本清掃の id**でしか引かない★ // （下で本清掃行の id でしか Map を引かない）。★取得元は指示書AQ 決定2/3 で差し替えた★ Promise.all( mainIdChunks.map((ids) => prisma.cleanTaskReport.findMany({ where: { clean_timetable_id: { in: ids } }, }) ) ), ]); const errorReports = errorReportChunks.flat(); const taskReports = reportChunks.flat(); // ★★`cleanLogs()` と**同じ関数**でレポートを1件に絞る★★（D-107。落とし穴2 / 指示書AQ §1-4）— // 以前はここが `new Map(histories.map(...))`（＝DB返却順の後勝ち）で、 // `cleanLogs()` の「ended_at 最新」と規則が違っていた。 // ★いまの判定は「行があるか」だけなのでどの行を選んでも答えは同じだが★、 // ★規則を1箇所にしておかないと、判定材料が増えた瞬間に `/detail-log` と `/alerts` で // 出発失敗の件数が食い違う★（D-103 が禁じた状態） const reportByTimetableId = latestReportByTimetableId(taskReports); const items: PrecheckItem[] = []; // ---- 1. 事前チェック行のエラー → severity: "precheck" for (const report of errorReports) { // ★nullable（清掃タイムテーブルに紐づかないエラーがありうる。`prisma/schema.prisma:322`）★ // ★事前チェックのアラートではないので対象外にする★（指示書S 3-2 項6 の推奨）。 // `scheduled_at`（本清掃の予定時刻）を決められないため、そもそも行を作れない。 // ★★`in: [...]` で引いているので SQL 側でも落ちるが、この行は残す★★ — // 型の絞り込み（`bigint | null` → `bigint`）に要るうえ、規則を1箇所で読めるようにする。 if (report.clean_timetable_id === null) continue; // ★★引くのは**事前チェック行**の Map★★（本清掃行の Map ではない）— // `precheckRows` は `parent_id: { in: 期間で絞った本清掃の id }` で引いた行なので、 // ★ここに当たる時点で「親が期間内」が保証される★。 const row = precheckRowById.get(key(report.clean_timetable_id)); // ★FK が無いため、参照先が消えている／存在しないことが起こりうる★ // 例外にすると1行の不整合で `/alerts` 全体が落ちるので、対象外として飛ばす if (!row) continue; // ★本清掃行を指すエラーは `launch_failed` に読み替えない（D-104）★ // 出発失敗は下の 2. で本清掃行のレポートの有無から作る。ここで拾うと二重計上になる。 // `precheckMinutesFromCode()` は本清掃コードに対して null を返す const precheckMinutes = precheckMinutesFromCode(row.precheck); if (precheckMinutes === null) continue; // ★`scheduled_at` は事前チェック行の `start_at` ではなく親の本清掃行の値★（指示書S 3-2 項5） // 画面は「予定」として清掃の開始時刻を出すので、60分前の時刻を入れてはいけない。 // ★★期間の基準もこの値★★（指示書AC 段階4。`errored_at` ではない）— だから // ★上の SQL は本清掃行を期間で絞り、そこから子を辿っている★。 const mainRow = timetableById.get(key(row.parent_id)); if (!mainRow) { // 事前チェック行の `parent_id` は必ず本清掃行を指す設計（D-092 項1）。 // 指していなければデータが構造的に壊れているので、静かに別の時刻を出さず気づけるようにする。 // ★★段階4 以降、`precheckRows` は `parent_id: { in: 本清掃の id }` で引いているので // 構造上ここには来ない★★。★それでもこの行を消さないこと★ — // 引き方を変えたときに「親が見つからない行を静かに落とす」状態へ戻さないための歯止め。 throw new Error( `[db] prechecks: clean_timetables(id=${row.id}) の parent_id=${row.parent_id} に対応する本清掃行がありません` ); } // ★行の組み立ては `precheckItemFromErrorRow()` の1本★（指示書AT 段階4-1）— // `precheckItemById()`（PATCH の前後の読み取り）も同じ関数を使う。★ここに書き戻さないこと★ // ★親の本清掃のレポートは上で本清掃の id でまとめて引いた Map から取る★ // （`main_run_succeeded`。D-171。★1行ずつクエリしないこと★＝N+1） items.push( precheckItemFromErrorRow( report, precheckMinutes, mainRow, reportByTimetableId.get(key(mainRow.id)) ) ); } // ---- 2. 出発しなかった本清掃 → severity: "launch_failed"（D-103 / D-104） // ★`now` は1回だけ作って全行で使い回す★（行ごとに作ると境界の行の扱いがぶれる） const now = new Date(); for (const row of timetables) { // ★★`precheck === main` の絞り込みは SQL に降ろした★★（指示書AC 段階4）ので、 // ここに残っているのは ★未来の予定を外す条件★ と ★出発したかの判定★ だけ。 // ★★まだ予定時刻が来ていない清掃は「出発しなかった」とは言えないので対象外★★ // `clean_timetables` には1週間分の予定がまとめて登録される（ユーザー回答 2026-09-10）ため、 // これを外さないと最大7日先までの予定が全部「出発失敗・未対応」として並ぶ。 // ★猶予（`LAUNCH_GRACE_MINUTES`）は足さない★（D-091 項1）。判定材料は `start_at` だけ if (isFutureSchedule(fromDbJst(row.start_at), now)) continue; // ★`cleanLogs()` の `departed` と同じ判定を共有する★（D-103 項1 / D-107）— // ★★出発失敗 ＝ 対応する `clean_task_reports` の行が無い★★（指示書AQ §1-1）。 // ★「レポートが無ければスキップ」を足さないこと★（D-107 設計3-C）— // レポートの行が無い行は `notExecutedFromReport()` が true を返すので、 // そのまま `launch_failed` になる（★消さずに画面へ出す★。fail-loud）。 // ★`clean_timetable_id` が NULL のレポートしか無い清掃もここに来る★（指示書AQ 罠1 / 決定5） const mainReport = reportByTimetableId.get(key(row.id)); if (!notExecutedFromReport(mainReport)) continue; // ★結果待ち（レポートがまだ届いていないだけかもしれない清掃）は出発失敗として出さない★ // （表2 C9。ユーザー判断 2026-10-07。D-173）。判定は `cleanLogs()` の `result_pending` と同じ // `isResultPending()` の1本（★D-091 項1 はこの件に限りユーザー判断で上書き★）。 // ★確定した出発失敗（待ち時間を過ぎた）は今までどおり出す★ if ( isResultPending({ startAt: fromDbJst(row.start_at), endAt: fromDbJst(row.end_at), now, hasReport: false, }) ) { continue; } // ★P1は1清掃エリア=1ロボットの前提（CLAUDE.md §8）★。`cleanLogs()` と同じ作法で // 0台なら静かに空文字を返さず例外にする const robot = row.section.robots[0]; if (!robot) { throw new Error( `[db] prechecks: clean_timetables(id=${row.id}) の section(id=${row.section_id}) にロボットが見つかりません。P1は1清掃エリア=1ロボットの前提です。` ); } const scheduledAt = jstIsoFromDb(row.start_at); items.push({ // ★本清掃行の `clean_timetables.id`★（D-104）— `CleanLogItem.id` と同じ値なので、 // 清掃詳細ログ（F-02）とアラート（F-03）に同じ清掃について同じ番号が出る。 // ★`BigInt` を `Number()` に通してから文字列化する★（`PrecheckItem.id` は string） id: String(Number(row.id)), severity: "launch_failed", // ★出発失敗は「何分前のチェックか」を持たない★（D-105） precheck_minutes: null, serial_number: robot.serial_number, facility_id: Number(row.facility_id), facility_name: row.facility.facility_name, scheduled_at: scheduledAt, // ★エラー行が0件のときの値（`Standby.`）★ — 自分で文字列を書かず、 // 既存の純粋関数に空配列を渡して得る（D-098 / D-104） robot_status: robotStatusFromErrors([]), // ★予定時刻をそのまま検知時刻にする★ — // エラー行が無いので `errored_at` が存在せず、`detected_at` は nullable でない。 // ★「予定＋猶予30分」を当方で計算しない★（D-091 項1。`LAUNCH_GRACE_MINUTES` を読まない） // ため、予定時刻を採る。★fixtures も同じ（`lib/fixtures/prechecks.ts` の // `launch_failed` 2件は `detected_at === scheduled_at`）★ detected_at: scheduledAt, // ★`unresolved` 固定★（D-104）— エラー行が無いので状態を持てない。 // ★「その他」「不明」のような語は使わない★（D-089 項3） resolution_status: "unresolved", // ★すべて null★（D-104）— 備考も日時も存在しない。 // ★将来「対応状況の更新機能」を作るときは書き込み先が無い★（申し送り。D-105） // ★`PATCH /prechecks/{id}/status` は出発失敗の id に 404 を返す（指示書AT §3-3）★ responded_at: null, resolved_at: null, note: null, battery_level: null, // ★出発失敗は常に false★（D-171 の M6）— レポート行が無いので `mainRunSucceededFromReport()` が false を返す。 // ★`false` を直書きせず同じ関数を通す★（成功の定義を1箇所に保つ） main_run_succeeded: mainRunSucceededFromReport(mainReport), }); } return items; }, /** * ★条件は `DataSource.precheckItemById()` の docstring★（指示書AT §3-3）。 * ★`prechecks()` が事前チェック行を作る条件と同じ★ — 条件を自前で書き直さず、 * 同じ関数（`precheckMinutesFromCode()` / `precheckItemFromErrorRow()`）を使う。 */ async precheckItemById(id: string) { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); // 1. `error_id` は UNIQUE（`prisma/schema.prisma` の `RobotErrorReport`）。主キーは無い const report = await prisma.robotErrorReport.findUnique({ where: { error_id: id }, // ★`prechecks()` と同じ列。`robot_id` / `robot` を読まない（指示書AU 段階0-4）★ select: ROBOT_ERROR_PRECHECK_ROW_SELECT, }); if (!report) return null; // ★★DB の照合順序は大小文字を区別しない（ci）★★ — `rer-1` で `RER-1` が当たる。 // ★当たり外れは JS の `===` で決める★（D-4。`dsDeviceExists()` と同じ）。 // ★書き込みの WHERE も同じ照合順序なので、ここで弾かないと別の文字列で同じ行を書き換えられる★ if (report.error_id !== id) return null; // 2. 予定に紐づかないエラー（N-5 の D-S制御盤・セキュリティの行を含む）は対象外 if (report.clean_timetable_id === null) return null; // 3. 事前チェック行であること（本清掃行を指すエラーは `launch_failed` に読み替えない。D-104） // ★予定は2表から引く（本表 → 無ければ履歴。指示書AU 段階3b-2 の 5）★ — // ★履歴の予定に紐づくエラー行も PATCH で書けるようになる（§3b-7 Q4。実在するアラートなので、それでよい）★ const row = await findTimetableById(prisma, report.clean_timetable_id, { id: true, parent_id: true, precheck: true, }); if (!row) return null; const precheckMinutes = precheckMinutesFromCode(row.precheck); if (precheckMinutes === null) return null; // 4. 親の本清掃行（`scheduled_at` に使う）。★無ければ例外★（`prechecks()` と同じ。データが構造的に壊れている） // ★旧: `findFirst({ id: parent_id, precheck: 本清掃 })`★ — 2表から id で引き、`precheck` は JS で確かめる // （条件は同じ。★本表に同じ id があれば本表が勝つ★ので、本表の行が本清掃でなければ履歴を見ずに例外） const parentRow = await findTimetableById(prisma, row.parent_id, { id: true, precheck: true, start_at: true, }); const mainRow = parentRow && parentRow.precheck === CLEAN_TIMETABLE_PRECHECK.main ? parentRow : null; if (!mainRow) { throw new Error( `[db] precheckItemById: clean_timetables(id=${row.id}) の parent_id=${row.parent_id} に対応する本清掃行がありません` ); } // 5. 親の本清掃のレポート（`main_run_succeeded`。D-171）。★`prechecks()` と同じ関数で1件に絞る★ // （`latestReportByTimetableId()`。★`orderBy` で別の順序キーを書かないこと★。D-107） const mainReports = await prisma.cleanTaskReport.findMany({ where: { clean_timetable_id: mainRow.id }, }); const mainReport = latestReportByTimetableId(mainReports).get(mainRow.id.toString()); return precheckItemFromErrorRow(report, precheckMinutes, mainRow, mainReport); }, async updatePrecheckErrorColumns(errorId: string, patch: PrecheckStatusPatch) { // ★書き込み用の接続★（`DATABASE_WRITE_USER` / `DATABASE_WRITE_PASSWORD`。未設定なら参照用と同じ接続。指示書AT §3-2） const { getWritePrisma } = await import("./prisma"); const client = await getWritePrisma(); const { matched } = await writeRobotErrorColumns(client, errorId, patch); return { matched }; }, /** * エラー一覧（指示書AW 段階3-5）。★2段階で読む★（D8）。 * * ★なぜ SQL で並べ替え・ページ分けしないのか★ — 並びの基準は `errored_at ?? created_at`（D3）だが、 * Prisma の `orderBy` は ★列ごとの並べ替えしか書けず `COALESCE` を書けない★（生SQL は禁止。`CLAUDE.md` §3）。 * `[{ errored_at: { sort: "desc", nulls: "last" } }, { created_at: "desc" }]` で近似すると、 * ★`errored_at` が NULL の行（表1 E7）が検知時刻に関係なく最後に回る★（例外もテスト失敗も出ない）。 * そこで 1段目 = キーだけを SQL で `status IN`・`facility_id IN`・期間に絞って全件読み、 * アプリで ★絞り込みの正（`filterSortErrorReportKeys()`）→ 並べ替え → ページ分け★、 * 2段目 = ★そのページの `error_id` だけ★ 列を足して読み直す（最大 `PAGINATION.maxPerPage` 件）。 */ async errorReports(query: ErrorReportDbQuery) { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); // 1段目: キーだけ（★SQL で status / 施設 / 期間を絞る。並べ替え・ページ分けはしない★）。 // ★`robot_id` / `robot` を読まない（NULL の行で落ちないため。指示書AU 段階0-4）★ const keyRows = await prisma.robotErrorReport.findMany({ where: errorReportListWhere(query), select: ROBOT_ERROR_LIST_KEY_SELECT, }); const keys = filterSortErrorReportKeys(keyRows.map(errorReportKeyFromRow), query); const pageIds = errorReportPageIds(keys, query); // ★0件なら2段目も予定も撃たない★ if (pageIds.length === 0) return { items: [], total: keys.length }; // 2段目: そのページの行だけ列を足して読む（`in` の分割は `chunkForInClause()`） const rows = ( await Promise.all( chunkForInClause(pageIds).map((ids) => prisma.robotErrorReport.findMany({ where: { error_id: { in: ids } }, select: ROBOT_ERROR_LIST_ROW_SELECT, }) ) ) ).flat(); // 予定は2表から id で（D5。★同じ id は本表が勝つ★）。★id が0件なら塊も0個でクエリを撃たない★ const timetableIds = [ ...new Set( rows.flatMap((row) => (row.clean_timetable_id === null ? [] : [row.clean_timetable_id.toString()])) ), ].map((id) => BigInt(id)); const timetables = await findTimetablesByChunks(prisma, chunkForInClause(timetableIds), (ids) => ({ where: { id: { in: ids } }, select: { id: true, precheck: true }, })); // ★pageIds の順に並べ、2段目で見つからない error_id は飛ばす（指示書AW 4-15。理由は関数の docstring）★ return { items: errorReportItemsInPageOrder(pageIds, rows, timetables), total: keys.length }; }, /** ★条件は `DataSource.errorReportById()` の docstring★（指示書AW 段階3-5） */ async errorReportById(id: string) { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); // `error_id` は UNIQUE。★一覧の2段目と同じ列（`robot_id` / `robot` を読まない）★ const report = await prisma.robotErrorReport.findUnique({ where: { error_id: id }, select: ROBOT_ERROR_LIST_ROW_SELECT, }); if (!report) return null; // ★★DB の照合順序は大小文字を区別しない（ci）★★ — `rer-1` で `RER-1` が当たる。 // ★当たり外れは JS の `===` で決める★（D-4。`precheckItemById()` と同じ）。 // ★書き込みの WHERE も同じ照合順序なので、ここで弾かないと別の文字列で同じ行を書き換えられる★ if (report.error_id !== id) return null; // 予定は本表 → 無ければ履歴（`findTimetableById()`。本表が勝つ。D5） const timetable = report.clean_timetable_id === null ? undefined : ((await findTimetableById(prisma, report.clean_timetable_id, { id: true, precheck: true })) ?? undefined); return errorReportItemFromRow(report, timetable); }, async updateErrorReportColumns(errorId: string, patch: PrecheckStatusPatch) { // ★`updatePrecheckErrorColumns()` と同じ中身★ — 書き込み用の接続 → `writeRobotErrorColumns()`（`updateMany` の1文）。 // ★`updatePrecheckErrorColumns()` の挙動を変えないため、共通化せずに並べて置く★（指示書AW D12 と同じ考え方） const { getWritePrisma } = await import("./prisma"); const client = await getWritePrisma(); const { matched } = await writeRobotErrorColumns(client, errorId, patch); return { matched }; }, /** * D-S制御盤の一覧（F-06）。★最終通信（`last_reported_at`）は `groupBy` で取る★。 * * ------------------------------------------------------------------------ * ★★なぜ `control_reports` の入れ子 include をやめたか（指示書AH 段階1 / D-1）★★ * ------------------------------------------------------------------------ * 以前はこう書いていた: * `include: { control_reports: { orderBy: { reported_at: "desc" }, take: 1 } }` * * ★★この `take: 1` は1文字もSQLに出ない★★（★実測★）。Prisma は * ★制御盤ぶんの `control_reports` を**全行**取り寄せてから、アプリ側（JS）で1件に切っている★。 * ★`relationLoadStrategy`（LATERAL JOIN）は Prisma 7.10.0 / MySQL adapter に存在しない★ので * 書き換えでは回避できない。 * * ★★破綻の性質は「遅い」ではなく「メモリ」★★（実測）: * - 100万行 … 8.6秒 / ヒープ 2.7GB * - ★300万行 … `JavaScript heap out of memory` でプロセス即死★ * Node の既定ヒープ上限は 4,288MB（実測）で、★想定1,100万行はその4倍★。 * ★`groupBy` なら戻りは制御盤数（実測11〜12行）で固定★＝行数総量に依存しない。 * ★往復数は増えない★（include も裏で複数本発行していた）。 * * ★画面が使うのは `reported_at` 1個だけ★（`DsDevice.last_reported_at`。 * `d-watch-api.yaml` も `components/features/ds-logs/DsLogScreen.tsx` も同じで、 * フィルタ・ソート・サマリはどれも `control_reports` を見ていない）。 * * ------------------------------------------------------------------------ * ★★なぜ時間で足切り（`reported_at >= X`）しないか（D-2。★足さないこと★）★★ * ------------------------------------------------------------------------ * ★`reported_at` に索引が無い★ため、`EXPLAIN` 実測で ★`key_len` が `control_id` の * 8バイトのまま増えず、走査行数も足切り無しと同じ★だった（＝後段フィルタでしかない）。 * ★`groupBy` の戻りはもともと制御盤数なので、足切りを足す意味が無い★。 * ★★そのうえ新しいバグを作る★★ — ★足切りの外にしか心拍が無い制御盤は最終通信が空欄になり、 * 「いつから切れているか」が見えなくなる★（通信断の判定自体は `controls.status` なので狂わない）。 * * ------------------------------------------------------------------------ * ★★なぜ `MAX(id)` を使わないか（D-3。★変えないこと★）★★ * ------------------------------------------------------------------------ * InnoDB の二次索引には主キーが暗黙に付くので `control_reports_control_id_foreign` は * 物理的に `(control_id, id)` であり、★`MAX(id)` なら `Using index for group-by` が効く★ * （実測: `type=range` / `rows=3`。`MAX(reported_at)` は `type=index` / `rows=14`）。 * ★★しかし `id` の大小順と `reported_at` の大小順が一致する保証はどこにも無い★★ — * 書き込むのは TeamWorks のデータ収集処理で、★その順序は仕様として確認していない★ * （`CLAUDE.md` §7「仕様が不明な箇所を推測で実装しない」）。 * ★確認が取れるまで `MAX(reported_at)` を使うこと★。 * ★根本的な手当ては複合索引 `(control_id, reported_at)` の依頼★（`docs/handoff.md`）。 */ async dsDevices() { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); // ★deleted_at IS NULL でのみ絞る。inactive では絞らない★ // inactive は「無効化」であって削除ではなく、画面が見せ分ける可能性がある // （lib/schedules/query.ts:108-112 に前例あり。仕様が未確定な箇所。指示書P 禁止事項10 / D-086）。 const controls = await prisma.control.findMany({ where: { deleted_at: null }, include: { facility: true }, }); // ★制御盤ごとの最終通信だけを取る（行は運ばない）★ // ★`control_id IN (...)` は制御盤数ぶん（実測11〜12）★。 // ★200台を超えたら実行計画を測り直すこと★（`docs/handoff.md` の申し送り）。 const latest = await prisma.controlReport.groupBy({ by: ["control_id"], where: { control_id: { in: controls.map((c) => c.id) } }, _max: { reported_at: true }, }); // ★★キーは `String()` で揃えること★★（★罠1★）— // `BigInt` をそのまま Map のキーにすると `1n` / `"1"` / `1` が別のキーになり、 // ★全制御盤が「心拍0件」に見えて例外になる★。 const byControl = new Map(latest.map((g) => [String(g.control_id), g._max.reported_at])); return controls.map((row): DsDevice => { const lastReportedAt = byControl.get(String(row.id)); if (!lastReportedAt) { // ★シードは全controlsにcontrol_reportsを1件以上入れる想定（指示書P 1-3）★ // 0件が来た場合は黙って空文字を返すより、例外で気づけるほうを選ぶ // （★「一覧に出るのに最終通信が無い」の検知。メッセージも含めて変えないこと★） throw new Error( `[db] dsDevices: controls(id=${row.id}) に control_reports が1件もありません` ); } return { serial_number: row.serial_number, facility_id: Number(row.facility_id), facility_name: row.facility.facility_name, // ★controls.status（0/1） → connection_status（"ok"/"error"）。D-065 Q1-2★ connection_status: connectionStatusFromControlStatus(row.status), // ★control_reports.reported_at は TIMESTAMP だが、実測（指示書Y 段階3）で // DATETIME と同じ往復（9時間ずれ）をすることを確認した（ローカルの // @@system_time_zone が実質JST相当のため）。DATETIME と同じ補正でよい★ last_reported_at: jstIsoFromDb(lastReportedAt), // ★note は常に null を返す。DBに対応カラムが無い（D-065 Q1-1）ため、実値は // app/api/ds-devices/route.ts:75-78 がJSONストア（data/settings/ds-device-notes.json）から // マージする。ここで埋めようとしないこと（後任が「実装漏れ」と誤解しないように明記）★ note: null, }; }); }, /** * ★シリアル1件の実在確認★（指示書AH 段階2 / D-4）。 * * ------------------------------------------------------------------------ * ★★なぜ `dsDevices()` を呼ばないか★★ * ------------------------------------------------------------------------ * 以前は `PATCH /ds-devices/{serial_number}/note` が `db.dsDevices()` を呼んでいた。 * ★シリアル1件の実在を確かめるためだけに、全制御盤＋全施設（＋当時は全心拍）を読む★。 * ★実在確認に施設名も最終通信も要らない★。 * ★さらに、無関係な1台に心拍が0件だと例外が飛んで**全台の備考保存が500になる**★ * （段階1 で心拍は読まなくなったが、★経路を分けること自体に価値がある★）。 * * ------------------------------------------------------------------------ * ★★当たり外れは JS の `===` で決める（★罠4★ / D-4。★変えないこと★）★★ * ------------------------------------------------------------------------ * ★DBの既定の照合順序は大小文字を区別しない（ci）★。SQL の一致をそのまま答えにすると: * `ds-001` が `DS-001` に当たって 404 → 200 * → ★保存キーはリクエストの生文字列 `ds-001`★（`lib/settings/ds-device-notes.ts`） * → 一覧は `notes["DS-001"]` で引く * → ★★保存されたのに一生表示されない孤児行が残る★★ * つまり ★実在チェックが防ぐはずの事故が、実在チェックのせいで起きる★。 * ★★SQL には絞り込みだけさせ、最後は `row.serial_number === serialNumber` で判定する★★。 * * - ★`findFirst` ではなく `findMany`★ — ci 照合で複数行が当たったとき、 * `findFirst` が「別の行」を返して ★偽404★ になる * - ★`select` は `serial_number` だけ★（実在確認に他の列は要らない） * - ★`take` は付けない★（★罠8★。段階1 と同じ「SQL に降りない」問題を踏みうる） * - ★`deleted_at: null` を `dsDevices()` と揃える★（★罠7★。上の `dsDeviceExists()` の * インターフェース側コメント参照） * * ★`controls.serial_number` に索引は無い★が、★`controls` は実測11〜12行★なので * 索引の依頼はしない（`docs/handoff.md` の申し送り対象外）。 */ async dsDeviceExists(serialNumber: string) { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); const rows = await prisma.control.findMany({ where: { deleted_at: null, serial_number: serialNumber }, select: { serial_number: true }, }); // ★ここが「当たり外れ」を決める唯一の場所★（SQL の一致に任せない。D-4） return rows.some((row) => row.serial_number === serialNumber); }, /** * ★このメソッドは disconnected（制御盤の生死報告なし）しか返しません★。 * ★理由★: `security_off`（セキュリティ解除されたまま）に対応するカラムが * `security_statuses` / `security_status_histories` に無いためです（D-090 項3-9）。 * `DsAlert` が要求する `id` / `device_serial` / `resolution_status` / `responded_at` / * `resolved_at` / `memo` の6フィールドに対応するカラムが両テーブルどちらにも存在しません。 * また `security_statuses.reported_at` は `@updatedAt` のため、`detected_at` * （いつからセキュリティが解除されたままか）も取れません（D-090 項3-10）。 * ★帰結★: `/ds-alerts` の件数が fixtures より少なくなり（security_off分が返らない）、 * `/dashboard` のセキュリティバナー（`lib/dashboard/aggregate.ts` の `computeSecurityBanner()`）が * 出なくなります。★これは意図した挙動であり、実装漏れではありません★。 * `security_off` 側は第3歩（`docs/decisions.md` D-090 項2 の分割表）で扱います。 */ async dsAlerts() { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); // ★control_error_histories には deleted_at が無い → 絞らない（段階3-5）★ // controls 側の deleted_at は結合先として絞ってよい const rows = await prisma.controlErrorHistory.findMany({ where: { control: { deleted_at: null } }, include: { control: true, facility: true, section: true, }, }); return rows.map((row): DsAlert => ({ id: Number(row.id), // ★control_error_histories は制御盤異常（生死報告なし）しか持たない（D-067 項1）★ alert_type: "disconnected", device_serial: row.control.serial_number, facility_id: Number(row.facility_id), facility_name: row.facility.facility_name, section_name: row.section.section_name, detected_at: jstIsoFromDb(row.occurred_at), // ★control_error_histories.status（0/1/2） → resolution_status。D-065 Q1-3★ resolution_status: resolutionStatusFromControlErrorStatus(row.status), responded_at: row.responded_at ? jstIsoFromDb(row.responded_at) : null, resolved_at: row.resolved_at ? jstIsoFromDb(row.resolved_at) : null, // ★書き込み許可4カラムの1つ（D-042）★ memo: row.comment, })); }, /** * ホールディングス一覧（`GET /groups`。指示書AK 段階1）。 * * ★`deleted_at IS NULL` でのみ絞り、`inactive` では絞らない★（`facilities()` と同じ判断）。 * ★並べ替えはルート側（`sortGroups()`）★ — 規則の「正」を純粋関数に置いたまま * （指示書AC C-5。ここでの `orderBy` はその写しになるので書かない）。 */ async groups() { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); const rows = await prisma.group.findMany({ where: { deleted_at: null } }); return rows.map( (row): Group => ({ id: Number(row.id), group_name: row.group_name, }) ); }, /** * 屋号一覧（`GET /customers`。指示書AK 段階1）。 * * ★★`contract` を読んでいないこと★★ — `customers.contract` は削除依頼済み * （D-010 / 落とし穴5）。そもそも `prisma/schema.prisma` の `model Customer` に列が無い。 * * ★`group_id` の 0 → `null` は `groupIdFromDb()` に任せる★（D-011 / 落とし穴3）— * ★ここに `=== 0` を書かないこと★。`BigInt` のままだと `0n === 0` が `false` で * 静かに外れるので、先に `Number()` に落としてから渡す。 * * ★★`orderBy` を付けてある★★（指示書AL 段階3 §4-4。★`groups()` と違う点★）— * `GET /customers` はルート側の `sortCustomers()` で並べ替えるので、そちらだけを見ると * ここの `orderBy` は写しに見える。★だが `GET /reports/kpi` の 422 は * `db.customers()` の並びをそのまま `details.customer_ids` に流す★ので、 * ★無いと候補の並びがDB任せになる★。★テストはスタブの順序で通ってしまい気づけない★。 */ async customers() { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); const rows = await prisma.customer.findMany({ where: { deleted_at: null }, orderBy: { id: "asc" }, }); return rows.map( (row): Customer => ({ id: Number(row.id), customer_name: row.customer_name, group_id: groupIdFromDb(Number(row.group_id)), }) ); }, async facilities() { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); // ★deleted_at IS NULL でのみ絞る。inactive では絞らない★ // inactive は「無効化」であって削除ではなく、画面が見せ分ける可能性がある // （lib/schedules/query.ts:108-112 に前例あり。仕様が未確定な箇所。指示書M 3-4 / D-086）。 const rows = await prisma.facility.findMany({ where: { deleted_at: null }, include: { robots: { where: { deleted_at: null }, include: { device: true }, }, // ★所属（屋号・ホールディングス）は施設の行と一緒に読む★（指示書AK 段階5 §8-2）。 // ★施設マスタは実測12件なので N+1 にはならない★（`loadFacilityGroupIndex()` と同じ判断）。 // ★`deleted_at` で絞らないこと★ — 屋号側を絞ると、論理削除された屋号に属する施設が // 静かに落ちる（`lib/db/facility-group-source.ts` の docstring と同じ理由）。 customer: { include: { group: true } }, }, }); return rows.map((row): Facility => { const { monitoring_enabled, d_security_enabled } = parseContract(row.contract); // ★0 → null の変換を知っているのは `groupIdFromDb()` だけ★（D-011 / ★落とし穴3★）— // ★ここに `=== 0` を書かないこと★。`BigInt` のままだと `0n === 0` が `false` で // 静かに外れるので、先に `Number()` に落としてから渡す。 const group_id = groupIdFromDb(Number(row.customer.group_id)); return { id: Number(row.id), facility_name: row.facility_name, customer_id: Number(row.customer_id), customer_name: row.customer.customer_name, group_id, // ★「所属なし」のときは名前も `null`★ — センチネル（`group_id = 0`）に対応する // `groups` の行は存在しないので、名前を出す相手がいない。 // `?? null` は保険（FKが緩い環境で参照先を欠いた行が来ても「グループ0」を出さない）。 group_name: group_id === null ? null : (row.customer.group?.group_name ?? null), prefecture: row.prefecture_name, address: formatAddress(row.addr1, row.addr2), phone: row.phone, manager_name: row.manager_name, charger_name: row.charger_name, email: row.email, monitoring_enabled, d_security_enabled, robots: row.robots.map((robot) => ({ id: Number(robot.id), maker: MAKER_NAMES[robot.device.maker_id] ?? String(robot.device.maker_id), model: robot.device.model_name, serial_number: robot.serial_number, })), }; }); }, async schedules() { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); const rows = await prisma.cleanSchedule.findMany({ where: { deleted_at: null }, include: { facility: true, section: { include: { robots: { where: { deleted_at: null } }, }, }, }, }); return rows.map((row): Schedule => { // ★P1は1清掃エリア=1ロボットの前提（CLAUDE.md §8）★ // 0台の section が来た場合は、静かに空文字を返すより例外で気づけるほうを選ぶ // （指示書M 4-2）。段階2のシードで施設12（ロボット0台）のスケジュールを // 構造的に除外しているため、通常運用ではここには到達しない。 const robot = row.section.robots[0]; if (!robot) { throw new Error( `[db] schedules: clean_schedules(id=${row.id}) の section(id=${row.section_id}) にロボットが見つかりません。P1は1清掃エリア=1ロボットの前提です。` ); } return { id: Number(row.id), serial_number: robot.serial_number, facility_id: Number(row.facility_id), facility_name: row.facility.facility_name, weekdays: row.weeks, weekdays_label: weekdaysLabel(row.weeks), start_time: formatStartTime(row.start_time), // ★inactiveの論理は反転している（0=有効）。Boolean(row.inactive)は書かない★ // （lib/schedules/query.ts:15-19 の警告どおり。全件逆になる典型的な地雷） end_time: formatEndTime(row.end_time), active: row.inactive === 0, }; }); }, async inspections() { return notImplemented("inspections"); }, async inspectionDetail() { return notImplemented("inspectionDetail"); }, /** * 要レスキュー店舗（F-01。指示書AI 段階4）。 * * ★★新しい全期間クエリを書いていない★★ — 入力は * ★`loadConsecutiveInputs()`（`lib/db/consecutive-source.ts`）の1本★ から取る * （★4本目の呼び出し元★。`cleanLogs()` / `facilityPerformance()` / * `continuousProblems()` と同じ1本。D-109 / D-103 の再発防止）。 * * ★★遡り幅を要レスキュー用に縮めないこと★★（指示書AI §6-2 / §13-7）— * R-1 は3スケジュール日、R-3 は1スケジュール日で足りるが、 * ★R-2（L3）は既存の遡り幅をそのまま必要とする★。縮めると ★L3 が L1 に化ける★ * （例外もテスト失敗も出ない）。 * * ★★`date_from` にも `date_to` にも対象日を渡す★★ — 遡りぶんは * `loadConsecutiveInputs()` が足す（★ここで足さないこと★。3経路で食い違う）。 * ★当該日に予定が無い施設を拾えるのは、この遡りぶんに前日以前の行が入るから★ * （絞り込みは `buildRescueRequired()` が「当該日以下」で行う。指示書AI §6-3）。 * * ★施設名は `loadFacilityNameIndex()`★（`facilityNameIndex()` と同じ1本）— * ★`facilities()` で代用しないこと★（あちらは `deleted_at` で絞るので、 * 論理削除された施設が要レスキューから静かに消える。★罠7★）。 */ async rescueRequired(query: RescueDbQuery) { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); // ★`now` は1回だけ作って両方の読み取りで使い回す★（未来の予定の除外基準を揃える） const now = new Date(); const [inputs, facilityNames] = await Promise.all([ loadConsecutiveInputs(prisma, now, { date_from: query.date, date_to: query.date, }), loadFacilityNameIndex(prisma), ]); // ★判定は fixtures と同じ1本を通す（`USE_FIXTURES` で分岐させない）★ // ★件数の上限は渡さない★（指示書AJ 段階1。該当する施設を全部返す） // ★★分類の絞り込みは fixtures 版と同じ場所（入力の行）にかける★★（指示書AK 段階4b）。 // ★★`loadConsecutiveInputs()` に `facility_id` の条件を足していない★★のは、 // ★あの1本を `cleanLogs()` / `facilityPerformance()` / `continuousProblems()` と // 共有しており、引数を増やすと3経路の遡り幅の約束（D-109 の再発防止）に触るため★。 // ★読み込み量は段階4b 以前と同じ（絞り込みで増えていない）★。 // ★★申し送り: SQL に降ろすなら4経路まとめて直すこと★★ — // ★そのときも `null`（絞らない）と `[]`（0件ヒット）の区別を崩さないこと★。 return buildRescueRequired( filterRowsByFacilityIds(inputs, query.facility_ids), facilityNames, query.date ); }, /** * 清掃面積（`GET /clean-area`。指示書AN 段階3 §6-2 / §6-3）。 * * ------------------------------------------------------------------------ * ★★面積は `groupBy` + `_sum`（行を運ばない）、完了率・実施回数は行を運ぶ★★（指示書AN §2-5 / 指示書AS 段階4） * ------------------------------------------------------------------------ * ★面積の合計は最大でも施設数ぶん（200行程度）★で、★期間の広さに関係しません★。 * ★集計元は `clean_task_reports`★（指示書AQ 決定2/3。2026-09-30 に `clean_status_histories` * から差し替えた）。★旧取得元は保持2年で約26万行★と見積もっていた。 * ★★完了率・実施回数の材料だけは行を取り寄せる★★（2026-10-02。D-155 / 指示書AS 段階4）— * 1回ごとの完了率の上限100・小数第1位の切り捨て（`runCompletionRate()`）は `groupBy` で書けず、 * ★生SQL（`$queryRaw`）は禁止★（`CLAUDE.md` §3）のため。★運ぶのは `clean_timetable_id` が * NULL でない行の5列だけ★（`facility_id` / `clean_timetable_id` / `clean_area` / `task_area` / `clean_ratio`）。 * ★★期間を指定しないと全期間（保持2年）を運ぶ★★ — 「行を取り寄せてJSで足すと期間を広げた瞬間に * 破綻する」懸念はこの取り寄せには当てはまる。★取り寄せた行数（`rate_rows`）と所要時間は * ルート層が `judge.clean_area` ログに出す★（D-156 論点2。実データで重ければ別途手当てする）。 * 予定（本清掃か）は id を集めて `chunkForInClause()` で分けて別クエリで引く（`include` は使わない）。 * * ★`started_at` に索引が無い★（指示書AN §1-5。第9回 1-4 で依頼中）ため全走査になりますが、 * ★★1本の集計クエリの全走査であり、詳細ログのような「塊ごとに全走査 × N回」ではありません★★。 * * ★★`include` を使わないこと★★（§6-2 / 落とし穴8）— ★親行の数ぶん `IN` が膨らむ★ * （D-136 で実測済み）。★施設マスタは `loadCleanAreaFacilityMasters()` で1回読み、 * JSで突き合わせる★（突き合わせ自体は `aggregateCleanArea()` の仕事）。 * * ------------------------------------------------------------------------ * ★★番人（§2-5 / §6-3 / 落とし穴2）★★ * ------------------------------------------------------------------------ * ★1つの `clean_timetable_id` にレポートが2行以上あると `SUM()` が同じ清掃を2回数える★。 * ★数え方（NULL 除外を含む）の正は `countDuplicatedTimetables()`★（指示書AQ §5-3）。 * ★例外もテスト失敗も出ず、数字が大きくなるだけ★なので、件数だけ数えて返します。 * * ★★`having` で「2行以上のものだけ」をDB側に絞らせること★★ — * ★絞らないと `clean_timetable_id` ごとに1行（＝最大26万行）返ってきます★。 * ★異常が無ければ0行しか運びません★。 * ★★集計と同じ `where` を使うこと★★（対象期間・対象施設に絞る。§6-3）— * ★全期間・全施設を毎回数え直さない★。 * * ★★ログはここで出さない★★ — `DataAnomalyLogEvent` の `route` / `method` はルート層なら必ず埋めるもので * （型は D-178 で任意になったが、ルートを載せられる層で出すのが原則）、 * ★データ層はどのルートから呼ばれたかを知らない★（★不明な情報を書かない★）。 * ★件数を返し、`reportCleanAreaAnomalies()`（`lib/clean-area/anomaly.ts`）を * ルート層が呼ぶ★（段階2 の `unmatched_facility_ids` と同じ分担）。 */ async cleanArea(query: CleanAreaDbQuery): Promise { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); // ★★`date_from` / `date_to` から直接 `Date` を作らないこと★★ — `started_at` は // DATETIME ＝ ★日本時間の壁時計値★なので9時間ずれる（指示書AC C-6）。 // ★変換は `dbDateRange()` の1箇所★。★どちらも `null` なら絞らない★（§2-3。上限も設けない）。 const range = dbDateRange(query.date_from, query.date_to); // ★★集計と番人で**同じ `where`** を使う★★（§6-3）— 別々に書くと、 // ★片方だけ期間を絞り忘れても誰も気づけない★。 const where: CleanAreaWhere = { // ★`gte` も `lt` も無いときは `started_at` のキーごと付けない★（`cleanLogs()` と同じ） // ★`started_at` は `clean_task_reports` にも同じ名前で在る（NOT NULL）★ ...(range.gte || range.lt ? { started_at: range } : {}), // ★★必ず `!== null` で分岐すること★★（★罠1 / 落とし穴3★）— // ★`in: undefined` は条件が消えて**全件**、`in: []` は `WHERE 1=0` で0件★。 // ★`query.facility_ids?.length ? ... : {}` と書くと「0件ヒット」が「全件」に化けます★。 // ★`facility_id` は `BigInt` 列なので1件ずつ包む★（`CleanAreaWhere` が `bigint[]` を要求。 // `prechecks()` と同じ作法） ...(query.facility_ids !== null ? { facility_id: { in: query.facility_ids.map((id) => BigInt(id)) } } : {}), }; // ★★`groupBy` をここに直書きしないこと★★（指示書AQ §5-3）— // ★集計元（`clean_task_reports`）と番人の `clean_timetable_id IS NOT NULL` 除外は // `lib/db/clean-area-source.ts` の2関数にしか無い★。直書きすると除外が落ち、 // ★NULL の行が1グループにまとまって番人が毎回1件を誤報する（偽陽性）★。 const [statsLoad, duplicatedTimetableCount, facilityMasters] = await Promise.all([ // ★面積の合計・実施回数・完了率の材料（`BigInt` の `Number()` 変換と `_sum` の `null` 吸収は // 向こうで済ませる）★。★取り寄せた行数もログ用に受け取る★（D-156 論点2） loadCleanAreaFacilityStatsWithRowCount(prisma, where), // ★番人★: ★2行以上ある `clean_timetable_id` の件数★（★NULL を除いて数える★） countDuplicatedTimetables(prisma, where), // ★施設マスタは1回だけ読む★（★`deleted_at` で絞らない理由は // `lib/db/clean-area-source.ts` の docstring★） loadCleanAreaFacilityMasters(prisma), ]); return { stats: statsLoad.stats, facilities: facilityMasters, duplicated_timetable_count: duplicatedTimetableCount, rate_rows: statsLoad.rate_rows, }; }, /** * レポートKPI（全社の4指標 + 前期比）。 * * ★確定期間: `customer_summaries` をそのまま読む。履歴から再計算しない（D-102）★ * ★当期（今週・今月）: 詳細テーブルからその場集計する★（インターフェース定義の * コメント参照。D-090項14/項15の解決） * * ★★性能（指示書AC 段階5 で解決）★★: 以前は引数を取らず ★サマリ全件 ＋ 詳細テーブル全件★ を * 読んでいた（`customer_summaries` 2 + `clean_timetables` 1,044 + * `clean_status_histories` 538 + `robot_error_reports` 49 ＝ ★実測 1,633行★）。 * ★★いまは「要求された期間 ＋ その1つ前」の2期間ぶんしか読まない★★。 */ async reportKpis(query: ReportKpiDbQuery) { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); // ★★期間の範囲を自分で計算しないこと★★（指示書AC 段階5「月跨ぎ週の地雷」）— // 週は月境界で切られ、★長さが1〜7日で変わる★（D-071 / `CLAUDE.md` §4.7）。 // ★帰属ルールを知っているのは `weekOfMonth()` だけ★なので、範囲は必ず // `periodRange()` に作らせる。★`null` ＝ その月に存在しない週★（5週しかない月の第6週。 // 当期にはなりえないので当期の集計は走らない）。 const range = periodRange(query.period, query.year, query.month, query.week); // ★★前期比のために1つ前の期間の行も要る★★（`shiftPeriod()`）— // ★2行ぶんだけ引く。全件読みに戻さないこと★（指示書AC 段階5）。 // ★★サマリの粒度は `week` が 0 かどうかで判別する★★（`week=0` が月次、 // `month=0 AND week=0` が年次。`CLAUDE.md` §4.7）ので、期間キー3つの一致で // 粒度まで決まる（`period` を別に渡す必要は無い）。 const prevKey = shiftPeriod(query.period, query.year, query.month, query.week, -1); const summaryRows = await prisma.customerSummary.findMany({ where: { // ★★対象顧客で絞る（指示書AK ★段階6★ / §2-1）★★ — // ★`OR`（当期 or 前期）と**同じ階層**に置くこと★。Prisma は同階層のキーを // ★AND で畳む★ので、これで「対象顧客 AND（当期 or 前期）」になる。 // ★★`OR` の各要素に `customer_id` を書き足す形にしないこと★★ — 同じ意味だが、 // ★条件が2箇所に散ると、片方だけ直したときに静かに全顧客へ戻る★。 // ★`customer_id` は `BigInt` 列★（`prisma/schema.prisma`）なので包む // （★`Number` のまま渡すと型が合わない★。`cleanLogs()` の `facility_id` と同じ作法）。 customer_id: BigInt(query.customer_id), OR: [ { year: query.year, month: query.month, week: query.week }, { year: prevKey.year, month: prevKey.month, week: prevKey.week }, ], }, }); // ★★年次（month=0 && week=0）も読む★★（指示書AQ 決定1。2026-09-30 解禁）— // ★以前はここで年次行を除外していた（「P1では読まない」D-072項4）が、 // 確定期間のサマリに週・月・年の3粒度が入るようになったので filter を外した★。 // ★外せる前提★: `periodOfSummaryRow()` が `month` も見るようになった（指示書AQ 罠2）ので、 // ★年次行が「月次」として混入して `customerSummariesByPeriodKey()` が 500 になることはない★。 // ★`where` は期間キー3つの完全一致なので、週次/月次の要求に年次行が混ざることもない★。 // ★★安全弁は残してある（D-5 / 指示書AH 段階3。指示書AK 段階6 でも**残す**と決めた）★★ — // ★`where` で顧客を絞ったので「複数顧客が混ざる」枝は通常もう発火しない★が、 // ★★同じ期間キーの重複は同一顧客でも起こりうる★★（`customer_summaries` に一意制約が無い。 // 期待値表 6-8）。★後勝ちで不定になるので、検知したら止める★。 // ★検知の中身（「全行の customer_id が1種類か」＋ 期間キーの衝突）は // `customerSummariesByPeriodKey()` が正★ — ここで手書きのループに戻さないこと。 const byPeriodKey = customerSummariesByPeriodKey(summaryRows); // ★要求された期間の行だけを組み立てる★（前期の行は `KpiValue.prev` の材料であって、 // ★それ自体を返り値の行にしない★。fixtures 版も同じ） // ★`periodOfSummaryRow()` には行（`prevKey`）をそのまま渡す★ — // `month` / `week` を位置引数で渡すと取り違えても型エラーにならない（同関数の docstring） const confirmedKpiRows: ReportKpiRow[] = summaryRows .filter( (row) => row.year === query.year && row.month === query.month && row.week === query.week ) .map((row) => { const period = periodOfSummaryRow(row); const prevRow = byPeriodKey.get( periodMapKey( periodOfSummaryRow(prevKey), prevKey.year, prevKey.month, prevKey.week ) ); return { period, year: row.year, month: row.month, week: row.week, kpi: kpiFromSummaryRatios(row, prevRow), }; }); // ★★当期（進行中の週・月）でなければ詳細テーブルを1行も読まない★★ — // 確定期間はサマリが正であり、★履歴から再計算しない（D-102 / `CLAUDE.md` 禁止事項1）★。 // ★`isCurrentPeriod()` は中で `todayJst()` を使う（当期判定の「正」はあちら1箇所）★ if (!range || !isCurrentPeriod(query.period, query.year, query.month, query.week)) { return confirmedKpiRows; } // ★当期: clean_timetables × clean_task_reports × robot_error_reports を // ★★`periodRange()` が返した範囲で SQL 側から絞って★★その場集計する // （`cleanLogs()` が既に読んでいるものと同じテーブル・同じ絞り方）★。 // ★清掃結果の取得元は `clean_task_reports`★（指示書AQ 決定2/3。旧: `clean_status_histories`）。 // ★★年次の当期（今年）もここを通る★★（指示書AQ 決定1）— 範囲が ★1月1日〜12月31日★ になるので、 // ★本清掃行と `in` の塊の数が週次の約50倍になる★（`chunkForInClause()` で分割はされる） // ★★`parseDate()` の「真の瞬間」を直接渡さないこと★★ — DB の DATETIME は // 日本時間の壁時計値なので9時間ずれる（指示書AC C-6）。★変換は `dbDateRange()` の1箇所★。 const dbRange = dbDateRange(range.from, range.to); /** * ★★当期は「対象顧客の施設」だけを集計する★★（指示書AL ★段階1★）。 * * ★確定期間は上の `customer_summaries` を `customer_id` で絞っている★のに対し、 * ★当期は詳細テーブルなので軸が**施設**になる★。★同じ顧客から解決した施設IDが * 降りてくる契約★（`toReportKpiDbQuery()` / `app/api/reports/kpi/route.ts`）なので、 * ★2つの経路は同じ母集団を指す★。 * * ★★`!== null` で分岐すること★★（★罠1 / 落とし穴3★）— * ★`?.length` で分岐すると `[]`（0件ヒット）が「条件なし＝全社合算」に化ける★。 * ★`in: undefined` も条件ごと消える★。★例外もテスト失敗も出ない★。 */ const facilityIdWhere = query.facility_ids !== null ? { in: query.facility_ids } : undefined; // ★予定は2表から読む（指示書AU 段階3b。`findTimetables()`。★`where` は1回だけ書く★）★ const mainRows = await findTimetables(prisma, { where: { // ★本清掃だけを引く（メモリ側の filter をやめて SQL に降ろした）★ precheck: CLEAN_TIMETABLE_PRECHECK.main, ...(dbRange.gte || dbRange.lt ? { start_at: dbRange } : {}), ...(facilityIdWhere !== undefined ? { facility_id: facilityIdWhere } : {}), }, // ★読む列は `CleanStatsTimetableLike`（`lib/db/report-mapping.ts`）が要求する4つだけ★ // （★`end_at` は結果待ちの判定用。D-173★） select: { id: true, facility_id: true, start_at: true, end_at: true }, }); // ★引いた本清掃の id で関連行を引き直す★（★全件読みに戻さないこと★）。 // ★`in` の要素数の上限と分割は `chunkForInClause()` に閉じ込めてある★（指示書AC §E-5）。 // ★塊が0個（本清掃が0件）ならクエリを1本も撃たない★。 const mainIdChunks = chunkForInClause(mainRows.map((row) => row.id)); const [reportChunks, errorReportChunks] = await Promise.all([ Promise.all( mainIdChunks.map((ids) => prisma.cleanTaskReport.findMany({ where: { clean_timetable_id: { in: ids } } }) ) ), Promise.all( mainIdChunks.map((ids) => prisma.robotErrorReport.findMany({ where: { clean_timetable_id: { in: ids } }, // ★`robot_id` / `robot` を読まない（NULL の行で落ちないため。指示書AU 段階0-4）★ select: ROBOT_ERROR_COUNT_SELECT, }) ) ), ]); // ★レポートを1件に絞る規則は `latestReportByTimetableId()` の1箇所★（指示書AQ §1-4） const reportByTimetableId = latestReportByTimetableId(reportChunks.flat()); // ★エラー率の分子は★本清掃行を指す★robot_error_reports（TeamWorks 第8回 A7。D-114 項2）★ — // 事前チェック行を指すものは含めない。`null` / dangling も入らない（決定3）。 // ★★上の `in` で既に「本清掃行を指すもの」だけを引いているが、判定の「正」は // `errorCountByMainTimetable()` のまま★★（SQL 側はその写し。指示書AC C-5） const mainStartAtById = mainTimetableStartAtById(mainRows); const errCountByMainId = errorCountByMainTimetable(errorReportChunks.flat(), mainStartAtById); // ★1回の集計で同じ now を使い回す（指示書V 落とし穴3。行ごとに作らない）★ // ★未実施の判定は `notExecutedFromReport()` を注入する★（`cleanLogs()` / `prechecks()` と // 同じ1本。★ここにラムダで規則を書かないこと★ — 規則が2箇所に散る。D-103 項1） const now = new Date(); const bucket = sumCleanStatsBuckets( aggregateCleanStatsByFacility( mainRows, reportByTimetableId, notExecutedFromReport, errCountByMainId, range, now ).values() ); // ★当期のprevは「1つ前の期間」＝確定期間のサマリ行から取る★ // （当期の前は先週/先月/★前年★なのでサマリに存在するはず。無ければ prev=null になるだけ） const prevRow = byPeriodKey.get( periodMapKey( periodOfSummaryRow(prevKey), prevKey.year, prevKey.month, prevKey.week ) ); const currentKpiRow: ReportKpiRow = { period: query.period, year: query.year, month: query.month, week: query.week, kpi: kpiFromCleanStats(bucket, prevRow), }; // ★確定期間の行があればそれが先（`selectKpiRow()` は最初の一致を採る）★ — // 当期にサマリ行がある（先方のバッチが先走った）場合の優先順位を段階0 と揃える。 return [...confirmedKpiRows, currentKpiRow]; }, /** * 施設別パフォーマンス。 * * ★確定期間: `facility_summaries` をそのまま読む。履歴から再計算しない（D-102）★ * ★当期（今週・今月）: 詳細テーブルからその場集計する★（`reportKpis()` と同じ方針。 * `CleanStatsBucket`（`lib/db/report-mapping.ts`）は元々「施設ごと」の集計を返すので、 * `reportKpis()` のように合算せずそのまま1施設1行として使う。指示書T 3-3の「共通化」） */ async facilityPerformance(query: FacilityPerformanceDbQuery) { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); // ★★範囲を自分で計算しないこと★★（`reportKpis()` と同じ。月跨ぎ週の地雷。D-071） const range = periodRange(query.period, query.year, query.month, query.week); /** * ★施設名の条件は「解決済みの施設ID配列」で降りてくる★（指示書AC C-1 / 段階5）。 * ★★`!== null` で分岐すること★★（★罠1★）— `in: undefined` は条件が消えて全件になる。 * ★`[]`（1件も当たらなかった）はそのまま `in: []` として渡し、0件を返させる★。 */ const facilityIdWhere = query.facility_ids !== null ? { in: query.facility_ids } : undefined; // ---- 施設マスタ（facility_name / serial_number の結合元）---- // ★facility_summariesにserial_numberが無いのでrobotsを結合して引く（facilities()と同じ形）★ // ★★ロボットが0台の施設（fixturesの施設12）は行ごと除外する★★（推奨案。指示書T 3-1）— // `cleanLogs()` / `schedules()` は例外を投げるが、レポートは「一覧の1行が欠ける」で // 済むので例外にしない（一覧APIが1施設の欠落で丸ごと500になるのは重い）。 // ★★`deleted_at: null` を外さないこと★★ — 段階0 から付いている条件で、 // ★論理削除された施設はもともとこの一覧に出ない★（施設名で解決したIDが論理削除済みでも、 // ここで落ちて段階0 と同じ結果になる。★罠7 の扱いは `cleanLogs()` とは事情が違う★）。 const facilityRows = await prisma.facility.findMany({ where: { deleted_at: null, ...(facilityIdWhere !== undefined ? { id: facilityIdWhere } : {}), }, include: { robots: { where: { deleted_at: null } } }, }); const facilityById = new Map< string, { facility_name: string; serial_number: string } >(); for (const facility of facilityRows) { const robot = facility.robots[0]; if (!robot) continue; // ロボット0台の施設は除外 facilityById.set(facility.id.toString(), { facility_name: facility.facility_name, serial_number: robot.serial_number, }); } // ---- 確定期間: facility_summaries をそのまま読む ---- // ★★「要求された期間 ＋ その1つ前（前期比の材料）」の2期間ぶんだけ引く★★ // （指示書AC 段階5。★全件読みに戻さないこと★）。粒度は `week` が0かどうかで決まる // （`CLAUDE.md` §4.7）ので、期間キー3つの一致で足りる。 const prevKey = shiftPeriod(query.period, query.year, query.month, query.week, -1); const summaryRows = await prisma.facilitySummary.findMany({ where: { ...(facilityIdWhere !== undefined ? { facility_id: facilityIdWhere } : {}), OR: [ { year: query.year, month: query.month, week: query.week }, { year: prevKey.year, month: prevKey.month, week: prevKey.week }, ], }, }); // ★★年次（month=0 && week=0）も読む★★（指示書AQ 決定1。2026-09-30 解禁）— // ★以前はここで年次行を除外していた（「P1では読まない」D-072項4）★。 // ★`periodOfSummaryRow()` が `month` も見るようになった（指示書AQ 罠2）ので、 // 年次行が月次のキーで Map に入って月次の行を上書きすることはない★（`reportKpis()` と同じ理由） const confirmedSummaryRows = summaryRows; const byFacilityPeriodKey = new Map(); for (const row of confirmedSummaryRows) { const period = periodOfSummaryRow(row); byFacilityPeriodKey.set( `${row.facility_id}/${periodMapKey(period, row.year, row.month, row.week)}`, row ); } // ---- 連続問題日数（★着手前確認A案。D-103。分割キーはfacility_id。指示書V 不具合B★）---- // `computeConsecutiveProblemDays()`（`cleanLogs()` と同じ関数・同じ入力の作り方）で // 施設単位・同一日OR畳み込み済みの連続日数を出し、`consecutiveProblemDaysAtPeriodEnd()` で // 「期間内でその施設の最終清掃ログ」の値を1施設1期間ぶん選ぶ。 // ★`ConsecutiveInput`は`facility_id`を持つのでFacilityConsecutiveEntryの代わりに使える★ // （以前あった`serial_number: String(facility_id)`という詰め替えは不要になった） // ★★入力の作り方は `loadConsecutiveInputs()` の1本に集約してある★★（指示書AC 段階1）— // `cleanLogs()` / `continuousProblems()` と同じ1本。★ここに書き下さないこと★（D-109 の再発防止）。 // ★`now` は下の `aggregateCleanStatsByFacility()` とも共有する（指示書V 落とし穴3）★ // ★★`loadConsecutiveInputs()` には「★要求された期間そのもの★」を渡すこと★★ // （★★指示書AC C-2 の地雷★★）— 連続日数は期間の手前まで遡って数えるので、 // ★期間で切り落とすと前日のデータが消えて連続が途切れ、L3 が L1 に化ける // （例外もテスト失敗も出ない）★。★遡りぶん（保存された表示上限 +1日）は同関数が足す★ // （段階6。★ここで足さないこと★ — 3経路で遡り幅が食い違う。D-109）。 // ★`range` が `null`（その月に存在しない週）なら下限なし＝全期間のまま★ const now = new Date(); const consecutiveEntries: ConsecutiveInput[] = await loadConsecutiveInputs( prisma, now, { date_from: range?.from ?? null, date_to: range?.to ?? null } ); const consecutiveById = computeConsecutiveProblemDays(consecutiveEntries); /** * 施設マスタ・判定・連続日数の組み立てを確定期間/当期で共有する。 * ★引数名を `range` にしないこと★ — 外側の `range`（要求された期間）を隠してしまう。 */ const buildItem = ( facilityId: number, kpi: ReportKpi, itemRange: { from: string; to: string } ): FacilityPerformance | null => { const facility = facilityById.get(String(facilityId)); if (!facility) return null; // ロボット0台の施設は除外 return { facility_id: facilityId, facility_name: facility.facility_name, serial_number: facility.serial_number, operation_rate: kpi.operation_rate, launch_rate: kpi.launch_rate, completion_rate: kpi.completion_rate, error_rate: kpi.error_rate, // ★status は judgeFacilityStatus() 経由で決める。直書きしない（CLAUDE.md §7）★ status: judgeFacilityStatus(kpi.operation_rate.value), // ★consecutive_problem_days はA案。期間内に清掃ログが無ければ0★（着手前確認。D-103） consecutive_problem_days: consecutiveProblemDaysAtPeriodEnd( consecutiveEntries, consecutiveById, facilityId, itemRange ), }; }; /** 前期のサマリ行（前期比の材料）を施設ごとに引く。★確定期間と当期で同じキーを使う★ */ const prevRowOf = (facilityId: bigint | number) => byFacilityPeriodKey.get( `${facilityId}/${periodMapKey( periodOfSummaryRow(prevKey), prevKey.year, prevKey.month, prevKey.week )}` ); // ---- 確定期間の行を組み立てる ---- // ★引いた2期間のうち「要求された期間」の行だけを行にする★ // （前期の行は `prevRowOf()` の材料であって、それ自体は返さない） const confirmedRows: FacilityPerformanceRow[] = []; for (const row of confirmedSummaryRows) { if ( row.year !== query.year || row.month !== query.month || row.week !== query.week ) { continue; } const period = periodOfSummaryRow(row); if (!range) { // ★サマリ行が持つ期間キーは既に妥当なはず（DB由来。API入力の検証とは別）★ // ★行があるのに `periodRange()` が解けない＝先方のサマリかこちらの週の数え方が // 食い違っている★ので fail-loud のまま残す（行が無ければここには来ない）。 // ★★年次の解禁（指示書AQ 決定1）でも条件は緩めない★★ — `periodRange("yearly", …)` は // ★整数の年なら必ず範囲を返す★（担当A。`lib/format/period.ts`）ので、年次の行はここに来ない。 // ★週次・月次で null が返るのは本当に異常★（存在しない週の行がサマリにある等）。 throw new Error( `[db] facilityPerformance: facility_summaries(id=${row.id})の期間範囲を算出できませんでした` ); } const item = buildItem( Number(row.facility_id), kpiFromSummaryRatios(row, prevRowOf(row.facility_id)), range ); if (!item) continue; confirmedRows.push({ period, year: row.year, month: row.month, week: row.week, item, }); } // ★★当期（進行中の週・月）でなければ詳細テーブルを1行も読まない★★ — // 確定期間はサマリが正であり、★履歴から再計算しない（D-102 / `CLAUDE.md` 禁止事項1）★ if (!range || !isCurrentPeriod(query.period, query.year, query.month, query.week)) { return confirmedRows; } // ---- 当期: 詳細テーブルを ★`periodRange()` の範囲で絞って★ その場集計する ---- // ★変換は `dbDateRange()`（`toDbJst()` を通す）の1箇所★（指示書AC C-6）。 const dbRange = dbDateRange(range.from, range.to); // ★予定は2表から読む（指示書AU 段階3b。`findTimetables()`。★`where` は1回だけ書く★）★ const mainRows = await findTimetables(prisma, { where: { // ★本清掃だけを引く（メモリ側の filter をやめて SQL に降ろした）★ precheck: CLEAN_TIMETABLE_PRECHECK.main, ...(dbRange.gte || dbRange.lt ? { start_at: dbRange } : {}), // ★★`!== null` の分岐は `facilityIdWhere` に閉じ込めてある★★（罠1） ...(facilityIdWhere !== undefined ? { facility_id: facilityIdWhere } : {}), }, // ★読む列は `CleanStatsTimetableLike` が要求する4つだけ★（★`end_at` は結果待ちの判定用。D-173★） select: { id: true, facility_id: true, start_at: true, end_at: true }, }); // ★引いた本清掃の id で関連行を引き直す★（`reportKpis()` と同じ作法。★全件読みに戻さない★） const mainIdChunks = chunkForInClause(mainRows.map((row) => row.id)); // ★清掃結果の取得元は `clean_task_reports`★（指示書AQ 決定2/3。`reportKpis()` と同じ）。 // ★★年次の当期（今年）もここを通る★★（指示書AQ 決定1。範囲が1年ぶんになる） const [reportChunks, errorReportChunks] = await Promise.all([ Promise.all( mainIdChunks.map((ids) => prisma.cleanTaskReport.findMany({ where: { clean_timetable_id: { in: ids } } }) ) ), Promise.all( mainIdChunks.map((ids) => prisma.robotErrorReport.findMany({ where: { clean_timetable_id: { in: ids } }, // ★`robot_id` / `robot` を読まない（NULL の行で落ちないため。指示書AU 段階0-4）★ select: ROBOT_ERROR_COUNT_SELECT, }) ) ), ]); // ★レポートを1件に絞る規則は `latestReportByTimetableId()` の1箇所★（指示書AQ §1-4） const reportByTimetableId = latestReportByTimetableId(reportChunks.flat()); // ★エラー率の分子は★本清掃行を指す★robot_error_reports（TeamWorks 第8回 A7。D-114 項2）★ — // 事前チェック行を指すものは含めない。`null` / dangling も入らない（決定3）。 // ★判定の「正」は `errorCountByMainTimetable()` のまま（SQL 側はその写し。C-5）★ const mainStartAtById = mainTimetableStartAtById(mainRows); const errCountByMainId = errorCountByMainTimetable( errorReportChunks.flat(), mainStartAtById ); // ★段階2の`CleanStatsBucket`は元々「施設ごと」のMapを返す。ここでは合算せず、 // 施設ごとにそのまま1行へ変換する（指示書T 3-3の「共通化」）★ // ★now は上（連続日数の算出）で作った同じインスタンスを使い回す（指示書V 落とし穴3）★ // ★未実施の判定は `notExecutedFromReport()` を注入する（`reportKpis()` と同じ1本）★ const buckets = aggregateCleanStatsByFacility( mainRows, reportByTimetableId, notExecutedFromReport, errCountByMainId, range, now ); const currentRows: FacilityPerformanceRow[] = []; for (const [facilityId, bucket] of buckets) { const item = buildItem( facilityId, kpiFromCleanStats(bucket, prevRowOf(facilityId)), range ); if (!item) continue; currentRows.push({ period: query.period, year: query.year, month: query.month, week: query.week, item, }); } return [...confirmedRows, ...currentRows]; }, /** * 連続問題施設（監視側の最後の未実装。指示書W）。 * * ★対応するサマリテーブルが無い（D-102項4）ため、確定期間（先週・先月）も当期 * （今週・今月）もどちらも詳細テーブルから算出する（決定2）。★`todayJst()` / * `isCurrentPeriod()` を使った当期の場合分けは書かない★ — ★どちらも同じ1本の処理★。 * * ★★2026-09-13（指示書AC 段階5）: 期間キーを「データの日付から列挙する」のをやめた★★ — * ★引数で期間が決まるので、その1期間だけを組み立てる★（以前は全期間ぶんの行を作り、 * ルート側の `selectContinuousProblemRows()` が1期間を選んでいた）。 * ★`reportPeriodKeysFromDates()`（`lib/db/report-mapping.ts`）はこの経路では * 呼ばなくなった★（純粋関数とテストは残してある。理由はあちらの docstring）。 */ async continuousProblems(query: ReportDbQuery) { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); // ★★範囲を自分で計算しないこと★★（`reportKpis()` と同じ。月跨ぎ週の地雷。D-071）— // ★`null` ＝ その月に存在しない週★（5週しかない月の第6週など）。 // ★★段階0 もその期間の行を1件も作っていない（データの日付から列挙していたため）★★ので、 // ★例外にせず空配列を返す★（ルート側は `items: []` を返す。404 にしない）。 const range = periodRange(query.period, query.year, query.month, query.week); if (!range) return []; // ★robots を join しない（ContinuousProblem に serial_number は無い。決定5）★ // ロボット0台の施設を除外すると、機体を撤去・交換中の施設のエスカレーションが // 画面から消える（fail-silent）。facilityPerformance() の buildItem() とは事情が違う。 // ★★分類の絞り込みはここにかける★★（指示書AK 段階4b）— // ★`continuousProblemsInPeriod()` は `facilityNameById` を回して行を作る★ので、 // ★ここで母集団が決まる★（`facilityPerformance()` が `facilityById` で決めているのと同じ形）。 // ★★`!== null` で分岐すること★★（★罠1★。`in: undefined` は条件が消えて全件になる）。 // ★`[]`（1件も当たらなかった）はそのまま `in: []` として渡し、0件を返させる★。 const facilityIdWhere = query.facility_ids !== null ? { in: query.facility_ids } : undefined; const facilityRows = await prisma.facility.findMany({ where: { deleted_at: null, ...(facilityIdWhere !== undefined ? { id: facilityIdWhere } : {}), }, }); const facilityNameById = new Map( facilityRows.map((f) => [Number(f.id), f.facility_name]) ); // ★★`ConsecutiveInput` の作り方は `loadConsecutiveInputs()` の1本に集約してある★★ // （`cleanLogs()` / `facilityPerformance()` と同じ1本。★2画面で連続日数が食い違わない // ようにするため、ここに書き下さないこと★。D-103 / D-109 の再発防止。指示書AC 段階1）。 // ★`now` は1回だけ作って使い回す（行ごとに作ると境界の行の扱いがぶれる）★ // ★★`isFutureSchedule()` を外さないこと — 外すと未来7日ぶんが全部「出発失敗」になり // 全施設が常時L3になる（D-106 / D-107 / D-110）★★（除外は同関数の中で行っている） // ★★段階6: 「★要求された期間そのもの★」を渡す★★（★遡りぶんは同関数が足す★）。 // ★`range` はこの上で `null` を弾いてあるので、ここでは必ず期間が決まっている★ const now = new Date(); const entries: ConsecutiveInput[] = await loadConsecutiveInputs(prisma, now, { date_from: range.from, date_to: range.to, }); const consecutiveById = computeConsecutiveProblemDays(entries); // ★確定期間も当期も詳細から算出する（対応するサマリが無い。D-102項4 / 決定2）★ // ★要求された1期間ぶんだけ組み立てる（指示書AC 段階5）★ const key: ReportPeriodKey = { period: query.period, year: query.year, month: query.month, week: query.week, }; return continuousProblemsInPeriod( entries, consecutiveById, facilityNameById, range ).map((item): ContinuousProblemRow => ({ ...key, item })); }, /** * エラー種別内訳（全社の発生件数・rate）。 * * ★facility版で確定（D-102項4の解決）★ — `customer_error_summaries` は読まない。 * `facility_error_summaries`（`facilityPerformance()` と同じテーブル系統）を読み、 * 同一期間・同一 `error_type` を全施設ぶん足し上げる（`errorBreakdownRowsFromSummary()`）。 * ★確定期間: サマリの `error_count` をそのまま合算する。履歴から再計算しない（D-102）★ * ★当期（今週・今月）: ★★本清掃行を指す★★ `robot_error_reports` を期間で絞って * `error_type` ごとに数える★（`countMainErrorTypesInRange()`）— * ★事前チェック行を指すもの / `clean_timetable_id` が `null` のもの / dangling は数えない★ * （TeamWorks 第8回 A7。2026-09-11。D-114 項2。決定2・決定3）。 * ★★率（`reportKpis()` / `facilityPerformance()`）と分子の集合を同じにするため★★ — * 同じレポート画面に定義の違う2つの数字を並べない。 * ★★期間判定は「そのエラーが指す本清掃行の `start_at` の JST 日付」★★（決定7）— * ★以前は `detectedAtFromError()`（`errored_at ?? created_at`）だった★。 * エラー率の分母が清掃予定回数（P-6=B）なので、分子も予定（本清掃）を基準にする。 * ★`type` / `label` は生値のまま。7分類・日本語への変換はしない（D-077/D-088）★ */ async errorBreakdown(query: ReportDbQuery) { const { getPrisma } = await import("./prisma"); const prisma = await getPrisma(); // ★★範囲を自分で計算しないこと★★（`reportKpis()` と同じ。月跨ぎ週の地雷。D-071） const range = periodRange(query.period, query.year, query.month, query.week); // ★★施設の条件（分類）を `where` に降ろす★★（指示書AK ★段階4b / §7-3★）— // ★D-133 の申し送り③「`facility_error_summaries` を `facility_id` で絞っていない」を // ここで解消している★。★★`!== null` で分岐すること★★（★罠1★。 // `in: undefined` は条件が消えて全件になる）。★`[]` はそのまま `in: []` で0件★。 // ★`rate`（全エラー件数に対する割合）の分母も絞ったあとの母集団で計算される★ — // ★それが正しい★（「この屋号のエラーのうち何%」が見たい）。 const facilityIdWhere = query.facility_ids !== null ? { in: query.facility_ids } : undefined; // ---- 確定期間: facility_error_summaries を読み、施設ぶん足し上げる ---- // ★★要求された期間の行だけを引く★★（指示書AC 段階5。★全件読みに戻さないこと★）。 // ★★前期の行は要らない★★ — エラー種別内訳に前期比は無い（`ErrorBreakdownItem` に // `prev` が無い）ので、`reportKpis()` / `facilityPerformance()` のような2期間読みはしない。 const summaryRows = await prisma.facilityErrorSummary.findMany({ where: { year: query.year, month: query.month, week: query.week, ...(facilityIdWhere !== undefined ? { facility_id: facilityIdWhere } : {}), }, }); // ★★年次（month=0 && week=0）も読む★★（指示書AQ 決定1。2026-09-30 解禁）— // ★以前はここで年次行を除外していた（「P1では読まない」D-072項4）★。 // ★`errorBreakdownRowsFromSummary()` は中で `periodOfSummaryRow()` を使い、 // それが `month` も見るようになった（指示書AQ 罠2）ので、★年次の件数が月次に // 足し込まれることはない★（`reportKpis()` と同じ理由） const confirmedGrouped = errorBreakdownRowsFromSummary(summaryRows); const confirmedRows: ErrorBreakdownRow[] = confirmedGrouped.flatMap((group) => group.items.map((item) => ({ period: group.period, year: group.year, month: group.month, week: group.week, item, })) ); // ★★当期（進行中の週・月）でなければ詳細テーブルを1行も読まない★★ — // 確定期間はサマリが正であり、★履歴から再計算しない（D-102 / `CLAUDE.md` 禁止事項1）★ if (!range || !isCurrentPeriod(query.period, query.year, query.month, query.week)) { return confirmedRows; } // ---- 当期: ★本清掃行を指す★ robot_error_reports を期間で絞って error_type ごとに数える ---- // ★期間帰属は「そのエラーが指す本清掃行の `start_at` の JST 日付」★（決定7）なので // `clean_timetables` も読む。★★その本清掃行を先に期間で絞れば、エラー行は // `clean_timetable_id` で引き直せる★★（全件読みに戻さない。指示書AC 段階5）。 // ★変換は `dbDateRange()`（`toDbJst()` を通す）の1箇所★（指示書AC C-6）。 const dbRange = dbDateRange(range.from, range.to); // ★予定は2表から読む（指示書AU 段階3b。`findTimetables()`。★`where` は1回だけ書く★）★ const mainRows = await findTimetables(prisma, { where: { // ★本清掃だけを引く（メモリ側の filter をやめて SQL に降ろした）★ precheck: CLEAN_TIMETABLE_PRECHECK.main, ...(dbRange.gte || dbRange.lt ? { start_at: dbRange } : {}), // ★★分類の絞り込み（指示書AK 段階4b）★★ — ★`facilityPerformance()` の当期と同じ形★。 // ★★`!== null` の分岐は `facilityIdWhere` に閉じ込めてある★★（罠1） ...(facilityIdWhere !== undefined ? { facility_id: facilityIdWhere } : {}), }, // ★読む列は `MainTimetableLike` が要求する3つだけ★ select: { id: true, facility_id: true, start_at: true }, }); const mainStartAtById = mainTimetableStartAtById(mainRows); const errorReportChunks = await Promise.all( chunkForInClause(mainRows.map((row) => row.id)).map((ids) => prisma.robotErrorReport.findMany({ where: { clean_timetable_id: { in: ids } }, // ★`robot_id` / `robot` を読まない（NULL の行で落ちないため。指示書AU 段階0-4）★ select: ROBOT_ERROR_TYPE_SELECT, }) ) ); // ★★分子は「本清掃行を指すエラー」だけ★★（D-118 / D-114 項2。★事前チェック行を数えない★）— // ★SQL 側の `in` で既にそうなっているが、判定の「正」は // `countMainErrorTypesInRange()` のまま★（SQL 側はその写し。指示書AC C-5） const currentItems = errorBreakdownItemsFromCounts( countMainErrorTypesInRange(errorReportChunks.flat(), mainStartAtById, range) ); const currentRows: ErrorBreakdownRow[] = currentItems.map((item) => ({ period: query.period, year: query.year, month: query.month, week: query.week, item, })); return [...confirmedRows, ...currentRows]; }, }; export const db: DataSource = USE_FIXTURES ? fixtureSource : prismaSource;