管理画面（F-10 システム管理）設計検討 — 2026-09-10

位置づけ: 最終フェーズで作る管理画面の設計検討メモ。指示書ではない。実装はしていない。 前提のコミット: develop / 8381d3c（作業ツリーはクリーン、41ファイル 778テスト全パス、最終決定番号 D-101） 調査方法: 5本の調査エージェントの報告を、主要な主張だけ実コードで再検証したうえで統合した。

★出所についての注記★（2026-09-16 追記）

本メモは 2026-09-10 のセッション（8381d3c で指示書I / D-101 を記録した回）自身の成果物です。 その後の作業が繰り返し「★他作業の未コミット変更★」として回避してきましたが （docs/decisions.md:8961 / :9142 ほか）、★別の担当者の作業ではありません★。 同じ未追跡集合にあった README.md と docs/code-map.md は既にコミット済みで、 ★取り残されていたのは本ファイルだけ★でした。

★中身は当時のまま★です。前提コミット（8381d3c）・テスト数（41ファイル 778テスト）・ 最終決定番号（D-101）は ★2026-09-16 時点では古い★（実測 96ファイル 2141テスト / D-141）。 ★設計検討の結論そのものは未着手のため生きています★が、実測値は読み替えてください。

0. スコープ（2026-09-10 ユーザー確定）

ユーザー選択は 「F-10 の編集可能化 ＋ ユーザー管理系」。

★これは docs/spec.md §2.3 および D-032 の P1 スコープを超える★。両者は 「ユーザー管理 / 権限管理 / 監査ログ はスコープ外（ユーザー管理未実装のため。P2以降）」と 明記しているため、着手時に決定事項として上書きを記録する必要がある（§8 の T-0）。

★依存の向きは L2 → L3 → L1★。「誰が変えたか」を記録できるのは L2 が入ったあとなので、 L2 を先に作るほうが手戻りが少ない（§6 の段階分割）。

1. 現状の実測（推測なし）

1.1 画面

1.2 設定値の保持

1.3 永続化基盤 lib/settings/json-store.ts（D-075 で共通化済み）

• 原子性: あり（.tmp → fs.rename、失敗時は .tmp 掃除＋元エラー再スロー）
• 排他: なし。後勝ち（コード上に明示。「利用者が増えたらロックを入れる」）
• ファイル未存在（ENOENT）は静かに空を返す。ENOENT 以外は投げる
• 破損時はタイムスタンプ付き .bak へ退避。退避失敗時は例外
• ★値の型検証は無い★ — トップレベルがオブジェクトかしか見ない

1.4 認証（D-101 / 指示書I で実装済み）

1.5 既存の書き込み系 API の作法

• 書き込みは JSON body の PATCH のみ（/api/settings/advice、/api/ds-devices/{serial}/note、対応状況の更新）
• ★成功時のログが1行も出ていない★。api.error（失敗時）しか記録していない。 db.write イベント型は定義済みだが実コードからの呼び出しは0件

2. モックが定める「正」（d-watch-mock.jsx）

2.1 タブ構成（:1156-1164）

9件並んでいるが id は8種類。★ops（運用設定）が2回入っているバグ★があり、 そのまま移植すると React の duplicate key になり、かつ sysTab === "ops" で 2つの本文（:1221 と :1628）が同時に描画される。

2.2 表示設定タブ（:1187-1191）

トグルは 4つ、すべて既定 ON。保存ボタンは無く、トグル即時反映。

★数値カード4列がトグルに入っていない★。docs/spec.md:35「各ブロックはON/OFF可能」と食い違う（§8 の Q5）。

2.3 権限管理タブ（:1398-1504）— ★編集UIが無い★

ロール定義表（4行）とメニュー×ロールのアクセスマトリクス（18行）が静的に描かれているだけで、 追加・編集・保存のボタンは1つも無い。★つまり「権限管理」はロール定義の参照画面であって、 権限をデータとして編集する機能ではない★。これはスコープを大きく縮める。

ロール定義（モックが正）

→ ★今回作るのは上2つだけ★。下2つはロール定義表に「P2」バッジ付きで表示するに留める （モックがそう描いている）。P1 は DFA 社内のみという CLAUDE.md §1 の前提とも一致する。

アクセスマトリクスの要点（P1の2ロール分）

★矛盾★: マトリクスは施設ロボットマスタを「編集/登録」可としているが、 docs/spec.md §2.3 F-08 は★「登録・更新はD-Security側の画面で行うためD-WatchはGETのみ」★と確定している。 spec.md を正とし、マトリクスの当該セルは「閲覧」に読み替える（§8 の Q6 で確認）。

★実装上の意味★: P1 の2ロールの差は運用設定・ユーザー管理・権限管理の3箇所だけ。 それ以外は同一。つまり必要な認可判定は「管理者かどうか」の1ビットで足りる。

2.4 監査ログタブ（:1699-1734）

4列の読み取り専用テーブル: 日時 / 操作者 / アクション / 対象。フィルタ・ページングは無い。

★モックのサンプル行は「清掃開始（手動）」「スケジュール変更」「ロボット同期」「施設追加」で、 いずれも D-Watch には無い操作（D-Security 側 / Pudu Cloud 側の操作）★。 そのまま作ると空のテーブルになる。D-Watch が実際に記録できる操作に置き換える必要がある（§5.1）。

2.5 モックと確定仕様の食い違い（実装前に潰すもの）

3. L1 — 表示設定・運用設定の編集可能化

3.1 保存先: ★JSON ファイル継続（lib/settings/json-store.ts を包む）を推奨★

保存形式は overrides 方式（既定値との差分だけを保存）。advice.ts の前例を踏襲すると 「既定値へ戻す」がファイル削除／キー削除で表現でき、既定値の変更が自動で追従する。

3.2 ★最大の実装論点: 閾値を判定ロジックへ届ける方法★

現状 judgeGrade() は GRADE_THRESHOLDS をモジュール定数として import している。 JSON で上書きした値を届けるには関数シグネチャの変更が必要で、lib/judge/ 全体と全呼び出し元に波及する。

• ★採用: 純粋関数のまま、閾値を既定引数付きの引数で受ける★ （judgeGrade(rate, thresholds = GRADE_THRESHOLDS)）。既存テストは無変更で通り、 CLAUDE.md §9.4「判定関数は純粋関数にする」と整合する。
• ★採ってはいけない: モジュール変数を実行時に書き換える方式★。 Next.js のワーカー構成が不明で、プロセスごとに違う値を持つ／リクエスト間で不整合になる。
• 反映タイミング: プロセス再起動なしで効く（リクエストごとに JSON を読む）。 100バイト未満のファイルなので★初版はキャッシュしない★。入れるなら mtime 方式 （PATCH でのキャッシュ破棄は複数プロセスだと壊れる）。

3.3 ★クライアントが lib/config を直接 import している問題★

"use client" の11ファイルが閾値をビルド時定数として読んでいる。サーバ側だけ動的化すると 判定と画面の説明文が静かに食い違う。特に深刻な3箇所:

→ ★対処: 動的化する閾値は、画面には必ず API レスポンス経由で渡す★。 SystemScreen.tsx:20-22 がアドバイス文言についてすでに採っている流儀を、閾値にも広げるだけ。

3.4 ★「変えても何も起きない設定」を画面に出してはいけない★

→ ★モック :1637-1646 の「事前チェック設定」入力欄をそのまま実装してはいけない★。 SystemScreen.tsx:5-9 が自ら掲げた方針に真正面から反する。 ★保存できるが何も変わらない UI は、保存できない UI より悪い★。

★帰結: 実際に機能する編集対象は「完了率閾値3つ ＋ エスカレーション日数2つ ＝ 5項目」と アドバイス文言（既に編集API あり）と表示トグル4つだけ★。

3.5 バリデーション

• ★部分更新は「現在値へ重ねた結果の全体」を検証する★（単体では妥当でも、重ねると破綻する）
• excellent > good > poor と level3Days > level2Days は等値も拒否 （等値にすると ○ や L2 が例外もテスト失敗も出さずに消える）
• 範囲は 0〜100（整数か小数かは §8 Q7）
• error.code は既存の validation_failed を使い、新設しない
• ★ストア側でも再検証する★（ファイルを直接壊された場合。json-store.ts は型を見ない）

3.6 API 契約

★d-watch-api.yaml には表示設定・運用設定のエンドポイントが1本も無い★。 CLAUDE.md §6-1 により実装より先に YAML を直す。

• 命名案: /settings/thresholds ＋ /settings/dashboard （/settings/operations は既存の /settings/advice と守備範囲が重なるため回避）。§8 Q8 で確認
• 一覧ではないので meta は不要
• リセットは既存 /settings/advice の reset フラグの作法を踏襲。項目単位のリセットは作らない

3.7 表示設定の解決場所: ★サーバ保存・レスポンス同梱を推奨★

• DashboardScreen.tsx:93 は !loading && !error && data で本体を一括描画するため、 設定を /api/dashboard のレスポンスに同梱すれば★ちらつき（OFFのブロックが一瞬見えて消える）は構造的に起きない★
• ★ブラウザ保存は不可★: リポジトリ全体で localStorage の使用は0件、ThemeProvider.tsx:25-26 も useState 固定（リロードで dark/ja に戻る）。「テーマと同じ場所」という選択肢は存在しない
• ★ユーザーごとの設定にはしない★: L2 でユーザーが入っても、表示設定は アクセスマトリクス上 全ロール「閲覧/編集」＝ 全員共通の設定。個人設定にするとマトリクスと食い違う
• レイアウト崩れの危険2箇所:
  • DashboardScreen.module.css:34 の grid-template-columns: repeat(4, 1fr) 固定（カード個別OFFなら空き枠）
  • DashboardScreen.tsx:149-153 の下段グリッドが failure_breakdown ? "1fr 1fr" : "1fr" の三項演算子。 子2つを独立ON/OFFすると4通りになり表現できない（両方OFFで空 div が残る）
• ★「失敗の内訳」は D-048 で API がプロパティごと省略しており、ONにしても出ない★。 D-053「動かないUIを出さない」に抵触するため、トグルを出す前に API 側の整理が要る
• 契約フラグとの二重制御は現状発生しない: AppShell.tsx:8-29 は静的配列で contract を参照していない （docs/handoff.md:1797-1799「施設横断のグローバルUIでどの施設の契約か決まらないため P1 は全表示」）。 将来の原則は ★契約 > 未実装 > 表示設定 の AND 合成★

3.8 ★最重要の論点: 閾値変更で過去の判定が遡って変わる★

◎○△× も L1〜L3 も DB に保存されていない（lib/db/index.ts:307-309。 サマリテーブルにも grade カラムは無い ＝ prisma/schema.prisma:701-732）。毎回その場で計算される。

→ ★閾値を変えた瞬間、過去すべての清掃ログの判定が遡って書き換わる★。

具体例: ○の基準を 70 → 75 に上げる

変更前は3日とも ○ ＝ 問題なし・連続0。変更後は3日とも △ ＝ 連続3日 → ★L3「DFAオンサイト訪問を検討」が発火★。 レポートの「連続問題施設」に A店 が突然出現する。 ★9月1日の朝に「異常なし」と確認して閉じた日が、今日見ると「L3」に見える★。

TeamWorks のサマリとは食い違わない（先方は判定を持たず、件数・面積・率だけ）。 食い違うのは ★DFA 内部の時間軸★ ＝「確定した過去の期間の判定が、後から変わる」。

4. L2 — ユーザー管理・権限管理

★ここが今回のスコープ拡張の本体で、D-101 で作ったばかりの認証を作り替えることになる★。

4.1 いま何を作り替えるのか

4.2 ユーザーストアの置き場所

★メインDBには置けない★（CLAUDE.md §3・§7）。選択肢は3つ。

★推奨は B。ただし「本番 VM の Node バージョン」を確認してから決める★。 確認が取れないうちは A で始め、L3（監査ログ）着手時に B へ寄せる逃げ道がある。

4.3 パスワードの扱い

• ★新しい依存を足さずに済む★: node:crypto の scrypt が使える（bcrypt/argon2 のネイティブビルド不要）。 さくらクラウド VM でのビルド事故を避けられる
• 保存するのは scrypt ハッシュ＋ソルト＋パラメータ。★平文・可逆暗号は不可★
• 検証は timingSafeEqual（既存 lib/auth/token.ts が定数時間比較を採っている流儀に揃える）
• ★パスワードは lib/logger/redact.ts の秘匿対象に必ず追加する★（dwatch_session を足した前例あり）
• 初期管理者は環境変数から1人だけ作る（ブートストラップ）。画面から作れると誰でも管理者になれる

4.4 セッション

現状は cookie 値＝トークンなのでサーバ側にセッションの実体が無い。ユーザーが入ると 「ユーザーを削除／無効化したら、その人のセッションを切る」が要件になるため、 ★サーバ側セッション（ストアに session_id → user_id, created_at）を持つのが素直★。

★ここで CLAUDE.md §7 の解釈を確認する必要がある★:

❌ トークン期限/残日数の実装

この禁止の出所は D-030で、内容は★「D-Secログ・D-Secアラート（F-06/F-07）の D-Sデバイスのトークン有効期限表示・残日数列を実装しない」★という画面要件の話である。 ログインセッションの寿命の話ではない。 D-101 はこれを cookie の maxAge にも適用して★期限なし（ブラウザを閉じるまで有効）★としたが、 実ユーザーのアカウントを入れるとセッション寿命はセキュリティ統制そのものになる （席を離れた PC から設定を変えられる、が現に穴として残っている）。 → ★§8 Q3 で確認する論点★。

4.5 認可の実装箇所

P1 の2ロールの差は運用設定・ユーザー管理・権限管理の3箇所だけ（§2.3）なので、 ★必要なのは「管理者かどうか」の1ビット★。過剰な RBAC を作らない。

★d-watch-api.yaml に 403 のレスポンス定義を追加する必要がある★（現状は 401 系のみ）。

4.6 権限管理タブは「参照のみ」で作る

§2.3 のとおりモックに編集UIが無い。★ロール定義とアクセスマトリクスを静的な表として描くだけ★。 ただし ★画面の表と実際の認可コードが乖離すると嘘の表になる★ので、 表のデータは lib/config/roles.ts のような1箇所の定義から生成し、認可判定も同じ定義を読むこと。

5. L3 — 監査ログ

5.1 何を記録するか（★D-Watch が実際にできる操作だけ★）

モックのサンプル行（清掃開始・スケジュール変更・ロボット同期・施設追加）は すべて D-Watch のスコープ外なので採用しない。実際に記録できるのは次のとおり。

★先に直すべき前提★: 現状 成功時のログが1行も出ていない。 監査ログは「成功した操作の記録」なので、まず書き込み系 API に成功ログを入れるのが土台になる。 docs/logging-design.md:68 が★「P2スコープ外の監査ログ（説明責任トレイル）」と 「デバッグ用技術ログ」を別物と裁定済み★なので、両者の関係は整理してから作ること。

5.2 保存先と保持

• ★アプリログ（pino / ファイル）だけでは監査ログにならない★: logrotate で消える（★保持期間は現状不明★）、 検索・ページングができない、画面に出せない
• → ★追記専用のストアを別に持つ★。JSON 配列は追記のたびに全書き換えになり肥大化に弱いので、 SQLite（§4.2 案B）か JSONL（1行1レコード）が向く。★ユーザーストアと同じ選択に揃えるのが自然★
• 保持期間・上限件数・ローテーションを決めてから作る（決めないと際限なく増える）
• 画面はモックどおり4列（日時 / 操作者 / アクション / 対象）。★モックにはフィルタもページングも無いが、 件数が増えるので meta: { total, page, per_page } 付きの一覧 API にする★（CLAUDE.md §9.3）

5.3 既に半分用意されているもの

lib/logger/events.ts:96-100（judge.grade）と :148-154（judge.advice）は ★thresholds_used のスナップショットを持っており、コメントで F-10 の閾値編集を名指しで想定している★。

F-10（M5）でしきい値が編集可能になると、同じ入力でも判定日によって発火するルールが変わるため、結果だけでは後から再現できない

★ただし一覧側の judge.grade ロギングは未実装★。閾値変更後に「なぜこの行が◎なのか」を 後から検証できるのは、1件詳細と一覧の境界近傍の行だけ。 ★一覧側 judge.grade を settings.change とセットで入れると追跡が閉じる★。

6. 段階分割（指示書の割り方の案）

★依存の向きは L2 → L3 → L1★。「誰が変えたか」を後から足すと、L1 のログ設計をやり直すことになる。

★T-1 〜 T-9 を1本の指示書にしないこと★。docs/decisions.md の決定番号を取るため衝突する （2026-09-07 に D-068 が二重採番された事故がある）。

★実データ接続を待たずに全部進められる★。管理画面は主に DFA 側ストアの話で、 最大のブロッカーである「接続先ホスト名・ポートの未受領」の影響を受けない。

7. 実装前に潰しておくべき既存の不整合

CSRF について（結論: ★現状は追加対策不要。ただし条件つき★）

cookie は SameSite=Lax・Domain 指定なし（host-only）・HttpOnly・Secure。 書き込みは JSON body の PATCH のみで、HTML form は PATCH を送れず、 cross-origin fetch は CORS プリフライトで止まる（next.config.ts に CORS ヘッダなし）。

★この結論が崩れる唯一の条件は「設定変更を GET で作ること」★（Lax はトップレベル GET に cookie を送る）。 → ★CLAUDE.md §9.3 に「設定変更は必ず PATCH/POST + JSON body。GET に副作用を持たせない」を1行足すのが最も効く★。

SameSite=Strict は外部リンク遷移で毎回ログイン画面に飛ぶため非推奨。 Origin 検証は任意だが、★比較基準の Host を nginx が素通しするかが不明★（確認せず入れると全員 403。fail-closed なので即座に気づける）。

8. ★ユーザー判断が必要な論点★（帰結つき）

★着手前に最低限 Q1・Q2・Q4 の回答が要る★。Q1 が (b) なら L1 の大半が消え、Q2/Q4 は L2 の土台を決める。

9. ★不明な点（推測で埋めていない）★

10. 参照

• docs/spec.md §2.3 F-10 / §3 M5 — 機能一覧と P1 スコープ
• docs/decisions.md D-030（トークン期限）/ D-032（F-10 限定スコープ）/ D-048 / D-053 / D-075（JSONストア）/ D-076 / D-079 / D-080（contract）/ D-084 / D-091 / D-101（認証）
• d-watch-mock.jsx:1152-1734 — システム管理画面の全タブ
• d-watch-api.yaml:614- — 既存 /settings/advice（新設エンドポイントの雛形）
• docs/logging-design.md §3 / §5 / §6 — イベント一覧、未実装の judge.grade、「誰が」を設けない裁定
• docs/handoff/analysis/prismaSource実装前チェックリスト.md — 実データ接続時に静かに壊れる箇所