指示書AY — 制御盤（ラズパイ）のログを D-Sec ログ画面から取り出す（中継方式・サーバーに保存しない）

日付: 2026-10-19 / 担当: Cursor（または監督が指名する実装担当）/ 基点: ★指示書AX の実装の完了後の develop の先端★（着手時に git log --oneline -1 で記入: _______） 前提: ★D-179★（docs/decisions.md:12934 以降。★本書の作成と同時に監督がコミットする★）/ ★指示書AX の実装コミット★（担当ファイルが重なる。下記）/ ★監督判断 第2ラウンド（2026-10-19。M1〜M11。§11 に反映済み。ブリーフより優先）★ / 設計書 docs/handoff/設計_制御盤ログの取り出し_20261019.md（★作成済み・本書と突き合わせ済み（2026-10-19）。制御盤の常駐プログラムの仕様はそちら★）/ D-077（XFF の末尾）/ D-101（IP 制限・ALLOW_DIRECT_ACCESS）/ D-123（シリアルの文字種を絞らない）/ D-4（当たり外れは JS の ===）/ D-054（summary と meta.total）/ D-143（DFA が作るのはビューアー。サーバーの構築保守は TeamWorks）/ D-154（セキュリティはリリース直前）/ CLAUDE.md §3・§6・§7・§9.3・§9.5・§9.6

★ユーザー決定（§2-1 の U1〜U5）と監督の設計判断（§2-2 の D1〜D25）は確定仕様。変えないこと★（CLAUDE.md §0-1）。 ★期待値表（§3）は正。変えないこと★（CLAUDE.md §0-2）。★§11 Q1〜Q16 はすべて監督判断（第2ラウンドと追加）で確定し、本文に反映済み★（★Q14・Q15 は本書の案 P1・P2 をそのまま採用。§2-3★）。

★担当ファイルが指示書AX と重なる★: components/features/ds-logs/（AX 段階7 が DsLogScreen.module.css:83 のコメントを直す）・d-watch-api.yaml・lib/i18n.ts・lib/types/index.ts・lib/fixtures/index.ts。 ★AX の実装コミットが develop に入ってから着手する★。

★行番号は本書の作成時（2026-10-19）の作業ツリーで確かめたもの。develop の先端は AX のコミットで動いている（作成中にも動いた）★。 ★着手時に develop の先端で、本書に書いた行番号をすべて確かめ直すこと★（段階0-4）。ずれていたら関数名・文で探し直す。

★docs/decisions.md に足すのは「D-179 の末尾への『実装の記録』」だけ★（§13 の下書き）。★新しい D 番号は取らない★（★D-180 は指示書AX が予約済み★）。

0. 何をするか

★変えないもの★: D-Sec ログの一覧（GET /ds-devices・dsDevices()）と備考（PATCH /ds-devices/{serial_number}/note）の挙動／ 既存の cookie 認証・IP 制限の判定（authenticate() の今の分岐）／lib/settings/json-store.ts の中身／prisma/／メインDB（★本機能は DB に書かない。読むのは 404 の判定の dsDeviceExists() だけ★）。

1. 背景

• ★ユーザー要望（2026-10-19）★: 制御盤（ラズパイ）の中のログファイルを、ターミナルを使わずに、PUDU のログのエクスポート画面のように「種類（ファイル名の prefix）・期間で絞り、一覧から選んでダウンロード」したい。サーバーには上げたくない。
• ★いまの運用★: Raspberry Pi Connect（rpi-connect 2.7.0）の Remote shell から cat で見ている。★Pi Connect にはファイル転送・ポート転送・コマンド実行の公開 API が無い★（D-179 追記 項1。出典は D-179）。→ Pi Connect だけでは要望を満たせない。★Pi Connect は常駐プログラムの導入・更新に使う★。
• ★D-Watch の今★（コード実測 2026-10-19。出所: 構造（コード・node_modules））:
  • Next.js ★16.3.3★（package.json:18）。middleware は proxy に改名（proxy.ts:1-21）。★proxy は Node ランタイム固定★。
  • ★proxy が走るリクエストは、本体を clone してメモリにバッファする。既定の上限は 10MB。超えた分は切り捨てられ、★クライアントにはエラーにならず、サーバーに警告が1行出るだけ★★ — node_modules/next/dist/docs/01-app/03-api-reference/05-config/01-next-config-js/proxyClientMaxBodySize.md:7-9・:71-76。 本体を最後まで受け取ってからハンドラが動く — node_modules/next/dist/server/next-server.js:1197-1217（cloneBodyStream() → finalize()）・node_modules/next/dist/server/body-streams.js:52-118（bytesRead > bodySizeLimit で console.warn と push(null)）。 → ★proxy を通るパスで 100MB を1本の POST で流すことはできない★。
  • proxy.ts の matcher は静的ファイル以外の全パス（proxy.ts:112-114。/api を含む）。★「matcher で除外しない。関数の中で分岐する」方針★（proxy.ts:106-107）。
  • 判定は lib/proxy/authenticate.ts（★判定するだけ・同期・deps 引数でテスト可能★。:59-94）。順序は ★IP 制限（403）→ 認証（401 / redirect）★。公開パスは /login と /api/auth/login だけ（:25）。
  • 認証は共有トークン（env AUTH_TOKEN）を cookie dwatch_session に入れる方式。比較は verifyToken()（lib/auth/token.ts:22-41。timingSafeEqual）。
  • IP 制限: lib/config/allowed-ips.ts（ALLOWED_IPS 空 :24-26・ALLOW_ALL_WHEN_EMPTY = true :35・TRUSTED_PROXY_HOPS = 1 :63）。★このファイルは proxy のバンドルに judge 系を引き込まないため lib/config/index.ts から独立させてある★（:4-8）。
  • 動かし方は npm run build → npm run start（docs/deploy.md §2）。Docker の可能性あり（同 §1）。★PM2 / cluster の設定は無い → 1プロセス★。前段に nginx（XFF を追記。D-077。★既定の proxy_read_timeout は60秒★）。nginx の設定は TeamWorks 管理でリポジトリに無い。
  • DFA 独自ストアは createJsonStore()（lib/settings/json-store.ts:39。.tmp → rename、壊れたら .bak。★read() は非同期★ :45）。前例 lib/settings/ds-device-notes.ts（data/settings/…。/data は .gitignore:50）。
  • ログは logEvent(level, payload)（lib/logger/index.ts:112）。イベントは lib/logger/events.ts の型付き union（:456-471）に足す。★キー名に token / authorization / facility_name / note 等を使うと本番で消される★（lib/logger/redact.ts:12-46）。
  • ★既存のストリーミング応答の例は無い★（CSV 出力は文字列を丸ごと返している）。
  • 画面: components/features/ds-logs/DsLogScreen.tsx（表の <colgroup> :437-443・見出し :445-453・日時の整形 formatDateTime() :41）。★モーダルの共通部品は無い★。前例は components/features/detail-log/AreaModal.tsx:65（role="dialog" aria-modal="true"・自前の overlay）。ページ送り components/ui/Pagination.tsx（total / page / perPage / onPageChange。★per_page の選択は持たない★）。日付は <input type="date"> ＋ openDatePicker()（components/ui/date-picker.ts:11）。
  • API: /ds-devices（d-watch-api.yaml:1376）・/ds-devices/{serial_number}/note（:1413。path の maxLength: 100・文字種は絞らない）。パスの検証は parsePathSerialNumber()（lib/api/path-params.ts:70-79。★422 validation_failed★）。実在は db.dsDeviceExists()（lib/db/index.ts:370。fixtures :680・Prisma :1944）。
  • テスト: vitest（vitest.config.ts。★include は lib/** と app/** だけ★ — components/ は走らない）。ルートのテストは Prisma 経路と fixtures 経路の2ファイルに分ける流儀（app/api/ds-devices/[serial_number]/note/__tests__/route.test.ts / route.fixtures.test.ts。ストアは fs.mkdtemp ＋ __setDeviceNotesStoreForTesting()）。

2. 決定（実装担当は従うこと）

2-1. ユーザー決定（2026-10-19。確定。D-179）

2-2. 監督の設計判断（確定。D-179 追記 項4・第2ラウンド M1〜M11・追加の判断 D25）

2-3. 本書の案で採用されたもの（★確定。追加の監督判断 2026-10-19 で §11 Q14・Q15 を採用★）

3. ★期待値表（正）★

★表1〜表6 はブリーフ §5 の柱と第2ラウンドの監督判断から本書で具体化したもの★（★表1・表2・表4・表6 と表3 の関数の行は第1ラウンド、表5 と表3 の API の行は第2ラウンドで作り直した★）。 ★表3 KA4・KA7 は本書の案（P1・P2）が §11 Q14・Q15 で採用されて確定した行★。

表1（lib/ds-logs/query.ts の queryDeviceLogs()。入力の8件）

types（制御盤から来た順）= [{ key: "app", label: "アプリ" }, { key: "comm", label: "通信" }, { key: "sys", label: "システム" }]（★ダミー。本物の値はユーザーが後日教える★）

表2（lib/ds-logs/presets.ts。now = 2026-10-19T12:00:00+09:00）

表3（制御盤トークン。関数は lib/ds-agent/tokens.ts、API は app/api/ds-devices/[serial_number]/agent-token/route.ts。ストアは mkdtemp）

表4（lib/proxy/authenticate.ts。deps で IP・AUTH_TOKEN・トークン検証を差し替える）

表5（lib/ds-agent/relay.ts。★時刻とタイマーを注入★。t は秒。制限値はテストで小さく差し替えてよい）

★エクスポートの状態★: 準備中（POST が待っている）→ 準備完了（201 を返した。受け取り待ち）→ 送信待ち（GET。send を入れた）→ 流れ中 → 完了 / 失敗 / 取り消し / 失効。★準備中〜流れ中を「進行中」と数える★。

表6（lib/ds-logs/file-name.ts の exportFileName(serial, now)）

★テストの書き方の注意★:

• ★日時は +09:00 付きの ISO 文字列で書く★。new Date(2026, 9, 19) のような実行環境のタイムゾーンに依存する書き方をしない（表2 T10）
• 表5 は ★本物のタイマーで待たない★。createRelay({ now, setTimer, clearTimer, limits }) に偽の時計を渡し、advance(秒) で進める（vi.useFakeTimers() でもよいが、now と setTimer を両方とも同じ偽の時計から取ること）
• 表5 の 4MB・9MB は ★limits.chunkMaxBytes を小さく（例 16 バイト）差し替えて★ 同じ規則を確かめてよい。★ただし R13・R24 の境界（ちょうど・+1）と R11・R14・R18・R31・R32 の秒の境界は、差し替えた値で必ず書く★
• ★期待値は設定値から作る★（CHUNK_MAX_BYTES + 1・EXPORT_PREPARE_TIMEOUT_SEC 等）。★R21〜R23・R27 の「わざと違う値」だけは直書きし、コメントで理由を書く★
• 表4 の「正しい Bearer」は deps.verifyAgentToken のスタブで作る（ストアに触らない）。★A7 はスタブが呼ばれていないこと（toHaveBeenCalledTimes(0)）を見る★
• 表3 は __setAgentTokenStoreForTesting()（新規。ds-device-notes.ts の __setDeviceNotesStoreForTesting() と同じ形）で mkdtemp のストアに差し替える。★data/settings/ の実物に触らない★。KA1〜KA8 はルートのテスト（段階7-4）
• ★ディスクに書かないことのテスト★（D3）は 段階7-4 のとおり

4. ★落とし穴（全段階で読むこと）★

段階0 — 着手前

1. ★develop で作業する★（.claude/worktrees/ の中ではない。ワークツリーは main 基点で古い）。git pull で最新にし、★指示書AX の実装コミットが入っていること★を git log で確かめる。入っていなければ着手しない。基点のコミットを冒頭の欄に書く。
2. git status を控える。★自分が作っていない変更・未追跡ファイルは他のセッションの作業★。触らない・コミットに含めない。
3. ★docs/decisions.md に D-179 がコミット済みか★を確かめる。未コミットなら ★§13 の追記は D-179 のコミットを待つ★（git add -p で自分の塊だけを選ぶのでもよい）。
4. ★本書に書いた行番号を develop の先端ですべて確かめ直す★（特に d-watch-api.yaml・lib/types/index.ts・lib/i18n.ts・lib/fixtures/index.ts・DsLogScreen.tsx / .module.css — AX が触る）。ずれは作業報告に書く。
5. npx prisma generate → npx tsc --noEmit -p . → npm test が通ることを確かめ、★テストの件数を記録する★。通らなければ着手前に報告。
6. ★Next.js は版が新しい★。次を読む（CLAUDE.md 末尾）: node_modules/next/dist/docs/01-app/03-api-reference/03-file-conventions/proxy.md（async にできること :31）・…/05-config/01-next-config-js/proxyClientMaxBodySize.md・…/01-getting-started/15-route-handlers.md（★GET はキャッシュされない★。app/api/settings/display-limits/route.ts:27-35）・…/03-file-conventions/route.md（ストリーミング・request.signal）。

段階1 — 期待値表をテストにする（実装より先）

★この時点ではテストが落ちる（関数・型が無い）のが正しい★。★コミットはテストだけで1つ（「テストだけ。この時点では落ちる」と明記）★。 各ファイルの冒頭コメントに対応する表を写し、「指示書AY §3 表N。ブリーフ §5 と監督判断 第2ラウンドから本書で具体化。★P1・P2 の行は §11 Q14・Q15 の採用で確定★」と書く。

1. lib/ds-logs/__tests__/query.test.ts（新規）: 表1 Q1〜Q17（it.each）。★Q14〜Q16 は純粋関数を直接呼ぶ★
2. lib/ds-logs/__tests__/presets.test.ts（新規）: 表2 T1〜T10
3. lib/ds-logs/__tests__/file-name.test.ts（新規）: 表6 N1〜N4
4. lib/ds-agent/__tests__/tokens.test.ts（新規）: 表3 K1〜K12（mkdtemp。afterEach で消す）
5. lib/proxy/__tests__/authenticate.test.ts（★足す★）: 表4 A1〜A11。★既存のテストは無修正で通ること★
6. lib/ds-agent/__tests__/relay.test.ts（新規）: 表5 R1〜R43
7. lib/ds-logs/__tests__/validate.test.ts（新規）: 段階3-3 の V1〜V7 と、段階7-2 の W1〜W9

（表3 KA1〜KA8 のルートのテストは、ルートの形が段階7 で決まるので段階7 で書く）

段階2 — API 契約（d-watch-api.yaml。★実装より先。CLAUDE.md §6-1★）

2-1. 足すもの

1. components.securitySchemes（:1734 付近）に ★agentBearer★（type: http・scheme: bearer。description: 制御盤ごとのトークン。/ds-agent/ 配下だけ。cookie では通らない。D-179）
2. タグ ds-agent（制御盤向け）
3. パス（/ds-devices/{serial_number}/note の後ろ・/ds-alerts の前に置く）。★検証エラーはすべて ValidationError（422 validation_failed。D17）★:

1. スキーマ: DsLogType { key, label }・DsLogFile { file_id, name, type, size_bytes, modified_at }・DsAgentStatus { connected, last_seen_at, agent_version }・ DsLogListResponse { agent, types, items, truncated, meta }・DsLogExportRequest・DsLogExportResponse { export_id, download_url, total_bytes, file_count, expires_in_sec }・ DsAgentTokenStatus { issued_at }・DsAgentTokenIssued { token, issued_at }・ DsAgentCommand { command_id, kind: [list, export, send], params }・DsAgentListResult（{ types, items, truncated } または { error: { code, message } }）・DsAgentPrepared・DsAgentComplete・DsAgentFail
2. ★各パスの description に★: ★サーバーには保存しない（D-179）★／一覧は制御盤からもらい D-Watch が絞る（D8）／★1プロセス前提・再起動で進行中は失われる★／★チャンクが 4MB 以下である理由（proxy の 10MB バッファ）★／★エクスポートは準備 → 送信の2段（D14）★

2-2. 型とエラーコード — lib/types/index.ts

• 上のスキーマと同名の型を足す（CLAUDE.md §9.2。DsDevice（:1024 付近）の近く）
• ★ErrorCode（:31-45）に足す★: agent_offline / agent_timeout / agent_error / agent_busy / export_busy / export_not_found / chunk_invalid / chunk_out_of_order / export_cancelled / command_expired / result_invalid。★validation_error は足さない（D17）★

コミット（YAML と型で1つ）。

段階3 — 設定値と純粋関数

3-1. lib/config/ds-agent.ts（新規。★node: を import しない・lib/config/index.ts を import しない★）

各定数の docstring に ★「何の上限か・なぜその値か・出所（D-179・監督判断 第2ラウンド M1〜M5）」★ を書く。★リクエストを待たせる5つ（LIST_TIMEOUT_SEC 15・AGENT_POLL_WAIT_SEC 25・EXPORT_FIRST_CHUNK_TIMEOUT_SEC 30・EXPORT_IDLE_TIMEOUT_SEC 45・EXPORT_PREPARE_TIMEOUT_SEC 50）には「nginx の proxy_read_timeout（既定60秒）より短くすること」★ と書く。

3-2. lib/ds-logs/query.ts（新規。純粋関数）

export interface DeviceLogQuery {
  types: readonly string[] | null;   // null = 全種類
  from: number | null;               // 瞬間（ms）。from ≤ t
  to: number | null;                 // t < to
  sort: "date_desc" | "type_date_desc";
  page: number;                      // 1〜
  perPage: number;
}
/** 表1。★入力の配列を書き換えない★。並べ替えの同値は name の `<` / `>`（`localeCompare` を使わない） */
export function queryDeviceLogs(
  types: readonly DsLogType[], items: readonly DsLogFile[], query: DeviceLogQuery
): { items: DsLogFile[]; total: number }

• ★modified_at は Date.parse() で比べる★。出力の modified_at は ★toJstIso(new Date(ms))★（表1 Q17。秒まで）
• type_date_desc の種類の順は ★types 配列の添字★。★types に無い種類の項目は来ない★（段階7-2 の検証で弾く）

3-3. クエリ・本体の検証（lib/ds-logs/validate.ts。新規。lib/api/query-result.ts の QueryParseResult を返す。★エラーは 422 validation_failed★）

コミット。

段階4 — 制御盤トークン（lib/ds-agent/tokens.ts）

/** 32バイトの乱数を base64url。ストアには SHA-256 の16進だけを書く。★生の値は戻り値で1回だけ★ */
export async function issueAgentToken(serialNumber: string): Promise<{ token: string; issued_at: string }>
export async function revokeAgentToken(serialNumber: string): Promise<boolean>   // 無ければ false
export async function agentTokenIssuedAt(serialNumber: string): Promise<string | null>   // P1（Q14 採用）
/** `Authorization` ヘッダの生値 → serial または null。★全件と timingSafeEqual で比べ、途中で抜けない★ */
export async function verifyAgentAuthorization(header: string | null): Promise<string | null>
export function __setAgentTokenStoreForTesting(store: JsonStore<AgentTokens> | null): void

• 保存先は ★呼び出し時に★ path.join(process.cwd(), "data", "settings", "ds-agent-tokens.json")（ds-device-notes.ts:53-55 と同じ理由）。★再デプロイで消えないこと（Docker なら volume）は監督が docs/deploy.md に書く（§12-2）★
• ★lib/logger を import しない★（proxy から呼ぶため。json-store.ts:15-17 と同じ考え方）。壊れたストアの警告は onWarn で settings.store_corrupt を出す（呼び出し側。前例 ds-device-notes.ts:65-73）
• ヘッダの形は ★/^Bearer ([A-Za-z0-9_-]{43})$/★（表3 K5・K6）。形が違えば ★ストアを読まずに null★
• 比較は ★入力の SHA-256 とストアの各 token_sha256 を timingSafeEqual★。★見つかっても残りを比べ終えてから返す★
• ★キャッシュ（D22）★: 読んだ内容をメモリに持ち、★fs.stat の mtimeMs が変わったら読み直す★（表3 K12）。★発行・失効の後は自分のキャッシュを捨てる★
• issued_at は toJstIso(new Date())（+09:00）
• ★シリアルの実在（DB）はここでは見ない★（ルートが dsDeviceExists() で見る。表3 KA5）

コミット（表3 K1〜K12 が通ること）。

段階5 — 認証（lib/proxy/authenticate.ts と proxy.ts。D22）

1. authenticate.ts に ★isAgentPath(pathname)★（pathname === "/api/ds-agent" || pathname.startsWith("/api/ds-agent/")。表4 A8・A10）
2. ★authenticate()（同期）★: IP 判定の後、★agent パスなら cookie を見ずに unauthenticated★（表4 A2 の保険。proxy からは呼ばれない）。★それ以外の分岐は変えない★
3. ★authenticateAgent(pathname, forwardedFor, authorization, deps)（新規・async）★:
   1. ★IP 判定（authenticate() と同じ関数を共有。複製しない）★ → 拒否なら deny_ip（★トークン検証を呼ばない★。表4 A7）
   2. deps.verifyAgentToken ?? verifyAgentAuthorization → null なら unauthenticated、そうでなければ allow
   3. ★戻り値に serial を入れない★（後段へヘッダで渡さない。D5）
4. proxy.ts: ★export async function proxy★。isAgentPath(pathname) なら await authenticateAgent(…, request.headers.get("authorization"))、そうでなければ今の authenticate()。 ★401 の応答は今の API の 401 と同じ形★。agent パスの 401 では ★ds_agent.auth_failed（warn）を出す★（reason: "missing" | "invalid"・route。★ヘッダの値は出さない★）。 ★冒頭コメントの「実行順」と matcher のコメントは変えず、agent パスの分岐を1行足す★
5. ★lib/ds-agent/require-agent.ts（新規）★: requireAgent(request): Promise<{ ok: true; serial: string } | { ok: false; response: Response }>。★制御盤向けのルートの先頭で必ず呼ぶ★（D5）。★通ったら relay の touch(serial) で last_seen_at を更新する（D19。表5 R7）★

★既存の lib/proxy/__tests__/authenticate.test.ts が無修正で通ること★。コミット。

段階6 — relay（lib/ds-agent/relay.ts）

6-1. 形

export interface RelayDeps {
  now: () => number;                                   // ms
  setTimer: (fn: () => void, ms: number) => unknown;   // 既定は setTimeout（★unref() する★）
  clearTimer: (handle: unknown) => void;
  limits: RelayLimits;                                 // 既定は lib/config/ds-agent.ts
  onEvent?: (e: RelayEvent) => void;                   // ログの受け口（段階10）。relay は logger を import しない
}
export function createRelay(deps?: Partial<RelayDeps>): Relay
export function getRelay(): Relay            // globalThis.__dwatchDsAgentRelay（無ければ作る）
export function __setRelayForTesting(relay: Relay | null): void

6-2. 規則

• ★id（command_id / export_id）は crypto.randomUUID()★（推測できない値。パスに出る）
• ★エクスポートの流れ（D14）★: createExport で export の指示を入れ ★prepared を最大 50秒待つ★ → prepared の total_bytes を ★EXPORT_MAX_BYTES と比べる（D15）★ → 201 → claimExport で ★send の指示（{ export_command_id }）を入れる★ → 最初のチャンクを最大30秒 → 流す。★チャンク・complete・送信中の fail は export の指示の command_id に来る。send の指示は自分の id を持ち、params.export_command_id で export を指す（D25 ①）★。★prepared から送信・完了・失敗・失効までを進行中に数え、prepared から60秒 GET が無ければ失効させて進行中から外す（D25 ⑤）★。★list はエクスポートの進行中でも待ち行列に入れる（D25 ③）★
• ★complete で確かめること（D15）★: 受け取った合計 ＝ prepared の total_bytes ＝ complete の total_bytes、かつ 受け取ったバイト列の SHA-256 ＝ prepared の sha256 ＝ complete の sha256
• ★last_seen_at は touch()（すべての agent リクエスト）と poll の開始・終了で更新★。poll が待っている間は接続中（表5 R4〜R7）。★状態が変わったときだけ onEvent★（表5 R39。未接続への変化はタイマーで見つける）
• ★SHA-256 は node:crypto の createHash を逐次★（全体のハッシュのためにチャンクを溜めない）
• ★流量制御の保留とアイドルは 45秒（D20）★。超えたら 410 とエクスポートの失敗
• ★終わった・失効したエクスポートと指示は、タイマーで消す★（メモリに残し続けない）。消した後の id は not_found／失効の直後は gone（410）を返せるよう、★短い間（例 EXPORT_IDLE_TIMEOUT_SEC）だけ墓標を残す★
• ★タイマーは unref()★（テストとプロセスの終了を止めない）
• docstring に ★1プロセス前提・再起動で失われる・ディスクに書かない・待ちは nginx の60秒より短く★ を書く

コミット（段階1 の表5 が通ること）。

段階7 — ルート

7-1. ブラウザ向け（app/api/ds-devices/[serial_number]/）

• ★withRequestId(request, …) で包む★（既存のルートと同じ）。500 は logApiError()
• ★fixtures のときは relay を呼ぶ前に ensureFixtureAgent()（段階8）★。★それ以外の分岐をルートに書かない★（CLAUDE.md §9.5）

7-2. 制御盤の一覧の結果の検証（lib/ds-logs/validate.ts）

★1件でも形が違えば、結果全体を不正とする★（黙って落とさない）→ ブラウザには 502 agent_error（details.agent_code = ["result_invalid"]）、制御盤には 400 result_invalid。

prepared の本体（total_bytes は0以上の整数・sha256 は小文字の16進64桁・file_count は1以上の整数）・complete の本体・fail の本体も同じファイルで検証し、★形が違えばすべて 400 result_invalid（D25 ④）★。

7-3. 制御盤向け（app/api/ds-agent/）

★agent のルートは DB を読まない★（USE_FIXTURES に関係なく同じ動き）。

7-4. テスト

★ルート本体は静的 import★（it() の中で await import() しない。note/__tests__/route.test.ts の冒頭コメント）。コミット。

段階8 — fixtures の偽制御盤

1. lib/fixtures/ds-device-logs.ts（新規）:
   • fixtureDeviceLogTypes: 種類3つ（★ダミーの名前★。例 app / comm / sys、ラベル「アプリ」「通信」「システム」）
   • fixtureDeviceLogItems(now: Date): ★数百件（例 300）★を now から決まった間隔で作る。★now ちょうど・1時間前ちょうど・3時間前ちょうど・24時間前ちょうど・その1秒前★ の項目を必ず含める（画面の目視用。境界の正しさはテストが持つ）。大きさは 1KB〜50MB（★選択の合計が 100MB を超える組み合わせが作れること★）
   • FIXTURE_EXPORT_ZIP_BASE64: ★中身がダミーの文字だけの小さな正しい zip★。★中のパスは root の名前つき（例 fixture-logs/app_20261019_1100.log。D24）★（フォルダ fixture-logs を PowerShell の Compress-Archive で包み base64 にする。★実在の店名・ログを入れない★）
   • FIXTURE_AGENT_OFFLINE_SERIALS = ["DS-001"]（D10）
   • lib/fixtures/index.ts に export * from "./ds-device-logs";
2. lib/ds-agent/fixture-agent.ts（新規）: ensureFixtureAgent(relay, serial):
   • ★FIXTURE_AGENT_OFFLINE_SERIALS と fixtures に無いシリアルは何もしない★（→ 409 / 404 が本物と同じ経路で出る）
   • それ以外は ★relay.poll(serial, "fixture", AGENT_POLL_WAIT_SEC, …) を1本だけ待たせておき★、指示が来たら ★本物と同じメソッド★ で返す: list → submitListResult／★export → submitPrepared（fixtures の zip の長さ・SHA-256・選んだ件数）★／★send → 小さく（例 1KB）分けて pushChunk を複数回 → completeExport★（流量制御の経路を通す）
   • ★1シリアル1本★（globalThis の Set で二重起動を防ぐ）
3. ★docs/fixtures.md は監督が直す★（ブリーフ §7）。足すべきことは §12-2

コミット。

段階9 — 画面（モーダル）

★見た目は AreaModal.tsx / .module.css から借りる。新しい共通部品は作らない★（components/ui/ に Modal を作らない）。

9-1. components/features/ds-logs/DsLogScreen.tsx

• 表の右端に ★「ログ」列★（<colgroup> に .colLogs を足す・幅は固定 ★例 80px★、DsLogScreen.module.css の min-width も同じだけ広げる（:82 のコメントの規則））。各行に ログ ボタン → モーダルを開く（serial_number と facility_name を渡す）
• ★モーダルの開閉以外は今の画面を変えない★

9-2. components/features/ds-logs/DeviceLogsModal.tsx（新規）と .module.css

• ★選択の保持（D23）★: file_id → size_bytes の Map で持つ。★ページ送り・並べ替え・ページあたり件数では保持★、★種類・期間を変えたら消す★
• 取得中は「読み込み中…」（t() に通す）。★一覧の取得は毎回制御盤に問い合わせる★（最大15秒）ので、★前の応答が後から返って上書きしないよう、要求ごとの番号で古い応答を捨てる★
• ★role="dialog" aria-modal="true"・Esc で閉じる・背景のスクロールを止める★（AreaModal.tsx の作りを確かめて揃える）。★準備中に閉じたら POST を AbortController で取り消す★（サーバー側はエクスポートを取り消す。4-9）
• ★色は CSS 変数・固定幅のボタン（JP/EN で位置が動かない）★
• 日時の表示は既存の formatDateTime()（DsLogScreen.tsx:41）と同じ形

9-3. lib/i18n.ts

★足す前に grep する★（閉じる・キャンセル・読み込み中…・種類・日付 は既にある）。EN は ★暫定★。 例: 「ログ」"Logs"／「制御盤のログ」"Controller logs"／「接続中」"Connected"／「未接続」"Not connected"／「直近1時間」"Last 1 hour"／「直近24時間」"Last 24 hours"／「種類＋日付」"Type + date"／「このページをすべて選択」"Select all on this page"／「エクスポート」"Export"／「制御盤で準備中…」"Preparing on the controller…"／「制御盤トークン」"Controller token"／「発行（作り直し）」"Issue (regenerate)"／「失効」"Revoke"／「コピー」"Copy"／ほか 9-2 の文言すべて。

コミット（画面は vitest で走らないので段階11 で見る）。

段階10 — ログのイベント（lib/logger/events.ts）

• LogEvent の union（:456-471）に足す。★reason は固定の文字列の union★（制御盤から来た message を載せない。制御盤の code は agent_code として固定の長さで切って載せてよい）
• ★file_name / file_ids / token / authorization を載せない★。テストで「イベントの値に file_id・ファイル名・トークンが入っていない」ことを確かめる

コミット。

段階11 — 画面確認と通し確認

★アプリ内ブラウザ（mcp__Claude_Browser__*）を使う。Edge（ヘッドレス・CDP を含む）は使わない★（ユーザー指示 2026-10-16）。 ★ユーザーの :3000（next dev。ステージング向け）は止めない★。★next dev ではなく next build → next start で確かめる★（1プロセス・本番と同じ形。4-2）。

11-1. 全体

1. npx tsc --noEmit -p . 0件／npm run lint 0件／npm test 全件通過（★段階0 の件数から増えている★）
2. ★npm run build の出力で、足したルートがすべて ƒ（Dynamic）★であること
3. grep（★0件★）:

   grep -rn "node:fs\|from \"fs\"\|node:os\|tmpdir\|mkdtemp\|createWriteStream" lib/ds-agent/relay.ts lib/ds-logs app/api/ds-agent "app/api/ds-devices/[serial_number]/logs"
   grep -rn "proxyClientMaxBodySize" next.config.ts
   grep -rn "console.log" lib/ds-agent lib/ds-logs app/api/ds-agent
   grep -rn "validation_error" lib app

4. ★scripts/ds-agent-token.ts が無いこと★（D16）

11-2. fixtures（:3100）

1. 本体で USE_FIXTURES=true npm run build（PowerShell: $env:USE_FIXTURES='true'; npm run build）
2. ★テスト用の AUTH_TOKEN をその場で生成★し、★環境変数で渡して★ npx next start -p 3100。★トークンを文書・コミット・報告に書かない★
3. preview_start の url で http://localhost:3100 を開き、ログインする
4. 確かめること:
   • D-Sec ログの各行に「ログ」がある。DS-002 で開く → 接続中・種類3つ・既定の期間（直近24時間）で一覧が出る
   • 種類を外す・期間のボタン・日付の範囲・並べ替え・ページ送り・ページあたり件数で一覧が変わる。種類・期間を変えると選択が消える
   • 「このページをすべて選択」→ 合計の表示。★100MB を超えると警告とボタンの無効★
   • ★エクスポート → 「制御盤で準備中…」→ zip が落ちる・開ける・中が fixture-logs/…★
   • ★DS-001 で開くと「制御盤が接続されていません（最終接続: -）」★。★それでも制御盤トークンの部分は使える★
   • ★制御盤トークン★: 発行 → 確認 → 1回だけ表示・コピー → 閉じて開き直すと値は出ず、発行日時だけ → 作り直し → 失効 → 「未発行」（★ここで発行した値は確認後に失効させ、どこにも書かない★）
   • ★JP/EN 切替★でボタン・列の位置が動かない／★ダーク/ライト★で崩れない／Esc で閉じる
   • D-Sec ログの表で横スクロールが増えていない（resize_window 1440×900・JP/EN）。終わったら desktop に戻す
5. ★終わったら :3100 の listen プロセスを止める★（自分で起動したものだけ）

11-3. 非 fixtures の通し確認（★偽制御盤スクリプト★。ローカルDB dwatch_local）

1. npm run seed:local（★ローカル以外を拒否する★）。DS-002 が controls にあること
2. USE_FIXTURES=false で ★ホストが localhost・DB 名が dwatch_local であることを確かめてから★ npm run build → next start -p 3100。★ALLOW_DIRECT_ACCESS=true を環境変数で★（XFF が無いため）
3. ★画面のモーダル（DS-002）の「制御盤トークン」で発行★し、★その値を環境変数 DS_AGENT_TOKEN で偽制御盤に渡す★（★画面・ファイル・報告に残さない★）
4. ★偽制御盤 scripts/ds-agent-fake.ts（D23。コミットする）★を tsx で動かす:
   • --server http://localhost:3100・トークンは環境変数
   • ポーリング → list には ★固定の一覧（種類2つ・10件程度）★ → export には ★--zip <パス> のファイルの長さ・SHA-256・件数で prepared★ → send には ★そのファイルを 4MB ごとに送り complete★（★file_ids は見ない。中身の正しさは制御盤（Python）の仕様★）
   • zip は ★9〜10MB 程度★（★4MB を超えて3チャンクになる大きさ★）。★root の名前つき（D24）★: 乱数の中身のファイルを入れたフォルダ（例 fake-root）を Compress-Archive で包む（中のパスが fake-root/…）
   • ★チャンクの POST のタイムアウトは60秒★（D20。設計書と同じ）
5. 画面から一覧 → 選択 → エクスポート。★落ちたファイルの SHA-256 が --zip のファイルと一致★（Get-FileHash / certutil -hashfile）・★ブラウザに進捗（大きさ）が出る（Content-Length）★。サーバーのログに ds_logs.export_prepared と ds_logs.export_completed（total_bytes が一致）
6. ★準備の失敗★: 偽制御盤の --fail-prepare too_large で、画面に「選んだファイルが大きすぎます」（POST の 502）
7. ★切断★: エクスポートの途中でブラウザのダウンロードを取り消す → 偽制御盤に 410 が返り止まる・ds_logs.export_failed（stage: send）
8. ★偽制御盤を止める★ → 60秒後に画面で「未接続」・ds_agent.disconnected が1回
9. 応答のヘッダに X-Accel-Buffering: no・Cache-Control: no-store・Content-Length があり、★Content-Encoding が付いていない★こと（read_network_requests）
10. ★終わったら★ 画面で ★トークンを失効★、:3100 と偽制御盤を止める

★結果の報告には出所を書く★（「当方の fixtures 由来」「当方の偽制御盤スクリプト由来」「当方のシード由来」。CLAUDE.md §6-6）。

8. テスト一覧（本書で足す・直すもの）

9. 触ってよいもの・触ってはいけないもの

触ってよい

d-watch-api.yaml・lib/types/index.ts（足すだけ）・lib/config/ds-agent.ts（新規）・lib/ds-logs/**（新規）・lib/ds-agent/**（新規）・ lib/proxy/authenticate.ts・proxy.ts（段階5 の範囲だけ）・scripts/ds-agent-fake.ts（新規。開発用）・ app/api/ds-devices/[serial_number]/logs/**（新規）・★app/api/ds-devices/[serial_number]/agent-token/**（新規）★・app/api/ds-agent/**（新規）・lib/fixtures/ds-device-logs.ts（新規）・lib/fixtures/index.ts（1行）・ components/features/ds-logs/**・lib/i18n.ts（足すだけ）・lib/logger/events.ts（足すだけ）・ docs/decisions.md（★D-179 の末尾に「実装の記録」を足すだけ★）・§8 のテスト

触ってはいけない

• ★CLAUDE.md★（監督が直す）・★docs/decisions.md の D-179 の本文とそれ以前★・docs/spec.md・docs/handoff.md・docs/code-map.md・★docs/fixtures.md★・docs/deploy.md（★監督。§12-2★）
• ★設計書 docs/handoff/設計_制御盤ログの取り出し_20261019.md★ と docs/handoff/ の他の文書（他の担当の作業）
• ★scripts/ds-agent-token.ts を作ること★（D16）・package.json（★script を足さない★）
• ★prisma/schema.prisma / lib/generated/prisma/**★・★メインDBへの書き込み★（★本機能は DB に書かない★。4カラムの UPDATE も使わない）・生SQL
• lib/settings/json-store.ts・lib/settings/ds-device-notes.ts・lib/auth/**（使うだけ）・lib/config/allowed-ips.ts（★IP 制限の扱いはリリース時。D6★）・lib/config/index.ts（★ds-agent の値を足さない。D9★）
• next.config.ts（★proxyClientMaxBodySize を足さない。4-1★）・proxy.ts の matcher
• d-watch-mock.jsx（モックに無い画面。書き換えない）・components/ui/**（共通部品を作らない）
• GET /ds-devices・PATCH /ds-devices/{serial_number}/note の挙動・lib/fixtures/ds-devices.ts
• ★認証情報（AUTH_TOKEN・発行した制御盤トークン・DB の接続情報）を文書・コード・テスト・コミット・作業報告に書くこと★
• ★git add -A★・eslint-disable の追加

10. 範囲外（本書ではやらない）

• ★制御盤の Python の常駐プログラム★（設計書。DFA の制御盤ソフトの担当が作る）。★zip の中のパス（{root の name}/…。D24）・指示の値と設定ファイルの値の小さいほうを採ること・別スレッドでの処理・配布の方法も制御盤側★。本書の偽制御盤スクリプトは ★D-Watch 側の確認用★ で、その代わりにはならない
• ★TeamWorks の nginx の設定★（第13回 S-5: 制御盤から 443 で届くこと・/api/ds-agent/ の本体 5MB と一時ファイルに書かないこと・X-Accel-Buffering を効かせること・proxy_read_timeout を60秒より短くしないこと）。監督が照会する
• ★リリース時の IP 制限の扱い★（D6・D-154）と、★トークンの発行・失効の権限の絞り込み★（P1 は DFA 社内の cookie 認証の全員が使える）
• ★顧客への公開★（U3）・facilities.contract による出し分け
• 一覧の結果のキャッシュ（毎回制御盤に問い合わせる）・「前回のエクスポートをもう一度」
• 認証の失敗の回数制限（リリース時のセキュリティ強化。§12-2）

11. 質問と回答（2026-10-19）

★Q1〜Q13 は監督判断（第2ラウンド。M1〜M11）で確定し、本文に反映済み。Q14〜Q16 は追加の監督判断で確定（Q14・Q15 は本書の案 P1・P2 をそのまま採用）。未確定は無い★。 ★判断が変わったら、「直す場所」を本文と同時に直すこと★（本文と末尾の決定が食い違ったまま渡さない）。

11-1. 監督判断（第2ラウンド・2026-10-19）で確定したもの

11-2. 追加の監督判断（2026-10-19）で本書の案を採用したもの

12. 申し送り

12-1. 設計書（制御盤の常駐プログラム）の担当へ（★監督経由。本書の実装では設計書を直さない★）

1. ★D25（追加の監督判断）★は設計書側も同じ内容で直している（監督から連絡あり）。★実装の前に設計書と表5 R17・R19・R28・R33・R40〜R43 が一致しているかを確かめる★
2. ★チャンクの POST は、ブラウザ側が読むまで 204 が返らない（最大45秒、超えたら 410）★。制御盤の HTTP のタイムアウトは60秒
3. ★modified_at は必ずオフセット付き★（naive な isoformat() は結果ごと不正になる。W4）
4. ★X-Chunk-Sha256 は小文字の16進64桁★。seq は0から連番。409 / 410 が返ったら送信をやめる
5. ★prepared の本体★: total_bytes（0以上の整数）・sha256（小文字の16進64桁）・file_count（1以上）。★send が来たら同じ zip を送る（作り直さない）★ — complete の sha256 は prepared と同じでなければ 400
6. 一覧の結果は ★4MB 以下・2万件以下★・★items[].type は必ず types のどれか★・file_id は重複させない（W2〜W8）

12-2. 監督へ（本書の実装では直さないもの）

1. CLAUDE.md §3 の「リリース直前のセキュリティ強化」の対象に ★制御盤トークンの失敗の回数制限★・★agent パスの IP 制限の扱い（D6）★・★トークンの発行・失効を誰ができるか★ を足す
2. docs/fixtures.md に fixtures の制御盤のログ（種類3つ・約300件・境界の項目・未接続 DS-001・ダミーの zip（fixture-logs/…））を足す（ブリーフ §7）
3. docs/deploy.md に ★1プロセス前提★（PM2 / cluster にしない・再起動で進行中のエクスポートは失われる）と ★data/settings/ds-agent-tokens.json が再デプロイで消えないこと（Docker なら volume。M8）★
4. docs/spec.md / docs/code-map.md に機能とファイルの対応

13. 決定の記録（★D-179 の末尾に足す「実装の記録」の下書き★）

- ★実装の記録（20XX-XX-XX。指示書AY）★:
  1. ★コミット★: （段階ごとのハッシュを列挙）
  2. ★API★: ブラウザ向け6本（`GET /ds-devices/{serial_number}/logs`・`POST …/logs/exports`（準備。最大50秒・201）・`GET …/logs/exports/{export_id}`（送信。`Content-Length` 付き）・`GET / POST / DELETE …/agent-token`）と制御盤向け6本（`/ds-agent/commands`・`…/result`・`…/prepared`・`…/chunks/{seq}`・`…/complete`・`…/fail`。kind は list / export / send）。`d-watch-api.yaml` が正
  3. ★部品★: `lib/ds-agent/relay.ts`（メモリ内の中継。`globalThis`。1プロセス前提）・`lib/ds-agent/tokens.ts`（`data/settings/ds-agent-tokens.json` に SHA-256 だけ。mtime でキャッシュ）・`lib/ds-logs/{query,presets,file-name,validate}.ts`（純粋関数）・`lib/config/ds-agent.ts`（設定値。待ちは 15 / 25 / 30 / 45 / 50秒で nginx の60秒より短い）・`scripts/ds-agent-fake.ts`（開発用の偽制御盤）
  4. ★認証★: proxy を async にし、`/api/ds-agent/` 配下は `authenticateAgent()`（IP → Bearer）。cookie では通らない。ルートでも `requireAgent()` で再検証し、すべての agent リクエストで `last_seen_at` を更新。トークンの発行・失効は cookie のパス（API と画面）
  5. ★監督判断 第2ラウンド（M1〜M11）を反映★。★§11 Q14・Q15 は本書の案（P1 `GET …/agent-token`・P2 未発行の DELETE も 204）を監督判断で採用★
  6. ★確認★: テスト件数（前 → 後）／fixtures の画面確認（当方の fixtures 由来）／非 fixtures の通し確認（当方の偽制御盤スクリプト由来: zip の大きさ・チャンク数・SHA-256 の一致・準備の失敗・切断で 410・未接続）
  7. ★本書と違う判断をしたところ★: （あれば）

14. コミット

段階ごとに分ける（段階1 / 段階2 / 段階3 / 段階4 / 段階5 / 段階6 / 段階7 / 段階8 / 段階9 / 段階10 / D-179 の追記）。★git add はファイルパスを明示する★（git add -A 禁止）。 メッセージには ★何を変えたか★ と ★なぜ（D-179。制御盤のログを中継で取り出す・サーバーに保存しない）★ を書く。★段階1 は「テストだけ（この時点では落ちる）」と明記★。 ★docs/decisions.md は自分の塊だけをコミットする★（他のセッションの未コミットの差分を巻き込まない）。★PR の作成とマージは daichi がレビューしてから★（D-154）。

15. 完了条件

• 着手前に指示書AX の実装コミットが develop に入っていた。基点のコミットを冒頭に記入し、★本書の行番号を先端で確かめ直した★
• 検証エラーは 422 validation_failed（D17）。§11 Q14・Q15 の採用（P1 GET …/agent-token・P2 未発行の DELETE も 204）を実装した
• tsc 0件・lint 0件・npm run build 成功（足したルートが ƒ）
• npm test 全件通過: 前 件 → 後 件
• 段階11-1 の grep がすべて0件・scripts/ds-agent-token.ts が無い
• ★ディスクに書かないことをテストで確かめた★（スパイ0回・ソースの静的な検査）
• ★proxy の matcher・next.config.ts を変えていない★。/api/ds-agent/ は cookie で通らず、他のパスは Bearer で通らない（表4）
• ★エクスポートは準備 → 送信の2段★: 準備の失敗は POST の 502、prepared の total_bytes の上限・complete の合計と SHA-256 の照合、GET に Content-Length（表5）
• ★待ちは 15 / 25 / 30 / 45 / 50秒（すべて nginx の60秒より短い）★
• ★トークンの生の値がストア・ログ・文書・コミットに無い★。発行・失効は API と画面から（ds_agent.token_issued / token_revoked に serial_number だけ）
• fixtures（:3100）で: 一覧 → 絞り込み → 選択 → ★「制御盤で準備中…」→ zip が落ちる★／★DS-001 で 409 の表示（トークンの部分は使える）★／トークンの発行・作り直し・失効／JP/EN・ダーク/ライト
• ★非 fixtures で偽制御盤スクリプトによる通し確認★: ★4MB を超えるファイルが複数チャンクで届き、SHA-256 が一致★／準備の失敗が画面に出る／途中の切断で 410／止めて60秒で未接続
• docs/decisions.md の D-179 の末尾に「実装の記録」を足した（D-179 の本文・CLAUDE.md には触っていない）
• 作業報告に: コミット一覧／テスト件数（前後）／確認の結果（★出所を書き分ける。CLAUDE.md §6-6★）／本書と違う判断をしたところ／行番号のずれ／§12 の申し送り