@aiquants/daily-report 0.7.0 → 0.8.0

package/src/server/handlers.ids-stream.spec.ts

@@ -0,0 +1,362 @@
+/**
+ * NDJSON streaming tests for the `ids-stream` endpoint.
+ * `ids-stream` エンドポイントの NDJSON 配信テスト。
+ *
+ * ここで固定する不変条件のうち、特に重要なもの:
+ *
+ * - **旧 `ids` JSON エンドポイントは存在しない** (クリーンカットオーバーの回帰防止)。
+ * - **チャンク順序とカーソル連鎖が SQL の並び順 (営業日降順・ID 降順・NULL 営業日末尾) と
+ *   厳密に一致する。** ズレると再開時に行の欠落または重複が起きる。
+ * - **`total` は接続ごとの先頭行にのみ載る** (進捗分母の契約)。
+ * - **不正カーソルは fail-closed で 400** (DB アクセスなし)。
+ * - **`Cache-Control: no-transform`** — compression ミドルウェアのバッファリング防止が
+ *   ストリーミングの成立条件そのもの。
+ */
+import { describe, expect, it } from "vitest"
+import type { DailyReportIdsStreamChunkLine, DailyReportIdsStreamLine } from "../shared/ids-stream"
+import type { DailyReportItem } from "../shared/types"
+import { createDailyReportHandlers } from "./handlers"
+import { makeApiArgs, makeHandlersFixture, TEST_EXTERNAL_USER_ID } from "./test-helpers/handlers-config"
+
+/** ストリーム順 (営業日降順・ID 降順) の合成アイテムを count 件生成する。 */
+const makeItems = (count: number): DailyReportItem[] => {
+    // 10 件ごとに営業日を 1 日下げ、同日内は ID 降順になる (日付演算で常に正規形 YYYY-MM-DD を保つ)
+    const baseUtc = Date.UTC(2026, 6, 31)
+    return Array.from({ length: count }, (_, index) => ({
+        reportHubId: count - index,
+        businessDate: new Date(baseUtc - Math.floor(index / 10) * 86_400_000).toISOString().slice(0, 10),
+        sourceType: "Internal",
+    }))
+}
+
+/** レスポンス全体をドレインし、NDJSON 行の配列へパースする。 */
+const readNdjsonLines = async (response: Response): Promise<DailyReportIdsStreamLine[]> => {
+    const text = await response.text()
+    return text
+        .split("\n")
+        .filter((line) => line.trim() !== "")
+        .map((line) => JSON.parse(line) as DailyReportIdsStreamLine)
+}
+
+/** チャンク行だけを取り出す (エラー行が混じればテストを落とす)。 */
+const asChunks = (lines: DailyReportIdsStreamLine[]): DailyReportIdsStreamChunkLine[] => {
+    return lines.map((line) => {
+        expect(line).toHaveProperty("items")
+        return line as DailyReportIdsStreamChunkLine
+    })
+}
+
+describe("ids-stream / 入口の検証", () => {
+    it("未認証は 401 を返し、サービスを呼ばない", async () => {
+        const { config, calls } = makeHandlersFixture({ user: null })
+        const { api } = createDailyReportHandlers(config)
+        const response = await api.loader(makeApiArgs("ids-stream"))
+        expect(response.status).toBe(401)
+        expect(calls.getDailyReportIds).toHaveLength(0)
+    })
+
+    it("GET 以外は 405 を返す", async () => {
+        const { config } = makeHandlersFixture()
+        const { api } = createDailyReportHandlers(config)
+        const response = await api.loader(makeApiArgs("ids-stream", { method: "POST" }))
+        expect(response.status).toBe(405)
+    })
+
+    it("旧 ids エンドポイントは存在せず 404 を返す (クリーンカットオーバーの固定)", async () => {
+        const { config } = makeHandlersFixture()
+        const { api } = createDailyReportHandlers(config)
+        const response = await api.loader(makeApiArgs("ids"))
+        expect(response.status).toBe(404)
+    })
+
+    it("ストリーミング応答のヘッダー契約 (x-ndjson / no-transform / nosniff / Set-Cookie 伝搬)", async () => {
+        const { config } = makeHandlersFixture({ cookie: "session=abc", idsStreamItems: makeItems(1) })
+        const { api } = createDailyReportHandlers(config)
+        const response = await api.loader(makeApiArgs("ids-stream"))
+        expect(response.status).toBe(200)
+        expect(response.headers.get("Content-Type")).toBe("application/x-ndjson; charset=utf-8")
+        expect(response.headers.get("Cache-Control")).toBe("private, no-cache, no-transform")
+        expect(response.headers.get("X-Content-Type-Options")).toBe("nosniff")
+        expect(response.headers.get("Set-Cookie")).toBe("session=abc")
+    })
+
+    it("新規接続でサービス例外 (全量・先頭ページとも失敗) は定型エラー行 + 正常クローズ", async () => {
+        const { config } = makeHandlersFixture({ idsStreamError: new Error("db down: SanwaPython secret") })
+        const { api } = createDailyReportHandlers(config)
+        const response = await api.loader(makeApiArgs("ids-stream"))
+        // ストリーミングは開始済みなので 200 のままエラー行で通知する (クライアントは再開する)
+        expect(response.status).toBe(200)
+        const body = await response.text()
+        expect(body).not.toContain("SanwaPython")
+        const lines = body
+            .split("\n")
+            .filter((line) => line.trim() !== "")
+            .map((line) => JSON.parse(line) as Record<string, unknown>)
+        expect(lines).toHaveLength(1)
+        expect(lines[0]).toEqual({ error: "stream interrupted by server error" })
+    })
+
+    it("再開接続でサービス例外はストリーム開始前に 500 JSON へ落ちる", async () => {
+        const { config } = makeHandlersFixture({ idsStreamError: new Error("db down: SanwaPython secret") })
+        const { api } = createDailyReportHandlers(config)
+        const response = await api.loader(makeApiArgs("ids-stream", { query: "?cursor_report_hub_id=10&cursor_business_date=2026-07-31" }))
+        expect(response.status).toBe(500)
+        expect(response.headers.get("Content-Type")).toContain("application/json")
+        expect(await response.text()).not.toContain("SanwaPython")
+    })
+})
+
+describe("ids-stream / 高速先頭ページ (キャッシュミス時の初回描画短縮)", () => {
+    it("全量クエリが遅い場合、先頭ページが先に届き、全量確定後の行に total が載る", async () => {
+        const items = makeItems(1100)
+        let releaseFull: (() => void) | null = null
+        const fullGate = new Promise<void>((resolve) => {
+            releaseFull = resolve
+        })
+        const { config, calls } = makeHandlersFixture({ idsStreamItems: items, idsStreamFullGate: fullGate })
+        const { api } = createDailyReportHandlers(config)
+        const response = await api.loader(makeApiArgs("ids-stream"))
+        const reader = response.body?.getReader()
+        if (!reader) throw new Error("body must be a stream")
+        const decoder = new TextDecoder()
+
+        // 1 行目: 全量を待たずに先頭ページ (200 件・total 無し) が届く
+        const first = await reader.read()
+        const firstLine = JSON.parse(decoder.decode(first.value)) as DailyReportIdsStreamChunkLine
+        expect(firstLine.items).toEqual(items.slice(0, 200))
+        expect(firstLine.total).toBeUndefined()
+        expect(firstLine.isLast).toBe(false)
+        expect(firstLine.nextCursor).toEqual({ businessDate: items[199].businessDate, reportHubId: items[199].reportHubId })
+        expect(calls.getDailyReportIdsFirstPage).toEqual([[TEST_EXTERNAL_USER_ID, 200]])
+
+        // 全量を解放すると、続きの行 (先頭ページの続きから) に total が載る
+        releaseFull?.()
+        let rest = ""
+        while (true) {
+            const { done, value } = await reader.read()
+            if (done) break
+            rest += decoder.decode(value, { stream: true })
+        }
+        const restLines = rest
+            .split("\n")
+            .filter((line) => line.trim() !== "")
+            .map((line) => JSON.parse(line) as DailyReportIdsStreamChunkLine)
+        expect(restLines[0].total).toBe(1100)
+        expect(restLines.slice(1).every((line) => line.total === undefined)).toBe(true)
+        // 先頭ページ + 続きの連結が全量と厳密一致 (欠落・重複なし)
+        expect([...firstLine.items, ...restLines.flatMap((line) => line.items)]).toEqual(items)
+        expect(restLines[restLines.length - 1].isLast).toBe(true)
+    })
+
+    it("先頭ページが上限未満なら全量クエリを待たずに完結する (小規模データセットの最速経路)", async () => {
+        const items = makeItems(5)
+        // 全量は永遠に解決しない (待っていないことの証明)
+        const { config } = makeHandlersFixture({ idsStreamItems: items, idsStreamFullGate: new Promise<void>(() => {}) })
+        const { api } = createDailyReportHandlers(config)
+        const lines = asChunks(await readNdjsonLines(await api.loader(makeApiArgs("ids-stream"))))
+        expect(lines).toHaveLength(1)
+        expect(lines[0]).toEqual({ items, nextCursor: null, isLast: true, total: 5 })
+    })
+
+    it("先頭ページ送出後に全量クエリが失敗したら、定型エラー行 + 正常クローズ (受信済みの続きから再開できる)", async () => {
+        const items = makeItems(1100)
+        // 全量クエリだけを失敗させる (先頭ページは成功して 200 件が届いている)。
+        // 生成直後に catch を付けて未処理拒否警告を防ぐ (await 側では正しく throw される)
+        const failedGate = Promise.reject(new Error("full query down: SanwaPython secret"))
+        failedGate.catch(() => {})
+        const { config } = makeHandlersFixture({ idsStreamItems: items, idsStreamFullGate: failedGate })
+        const { api } = createDailyReportHandlers(config)
+        const response = await api.loader(makeApiArgs("ids-stream"))
+        expect(response.status).toBe(200)
+        const body = await response.text()
+        expect(body).not.toContain("SanwaPython")
+        const lines = body
+            .split("\n")
+            .filter((line) => line.trim() !== "")
+            .map((line) => JSON.parse(line) as Record<string, unknown>)
+        // 1 行目: 先頭ページ (200 件・total 無し・isLast 無し)
+        expect((lines[0] as DailyReportIdsStreamChunkLine).items).toHaveLength(200)
+        expect((lines[0] as DailyReportIdsStreamChunkLine).isLast).toBe(false)
+        expect((lines[0] as DailyReportIdsStreamChunkLine).total).toBeUndefined()
+        // 2 行目: 内部情報を含まない定型エラー行 (クライアントはカーソル再開する)
+        expect(lines[1]).toEqual({ error: "stream interrupted by server error" })
+        expect(lines).toHaveLength(2)
+    })
+
+    it("キャッシュヒット相当 (全量が即時) では従来どおり先頭行に total が載る", async () => {
+        const items = makeItems(5)
+        const { config } = makeHandlersFixture({ idsStreamItems: items })
+        const { api } = createDailyReportHandlers(config)
+        const lines = asChunks(await readNdjsonLines(await api.loader(makeApiArgs("ids-stream"))))
+        expect(lines[0].total).toBe(5)
+    })
+
+    it("再開接続は先頭ページクエリを発行しない (受信済みの続きだけを読む)", async () => {
+        const items = makeItems(5)
+        const { config, calls } = makeHandlersFixture({ idsStreamItems: items })
+        const { api } = createDailyReportHandlers(config)
+        await (await api.loader(makeApiArgs("ids-stream", { query: `?cursor_report_hub_id=${items[1].reportHubId}&cursor_business_date=${items[1].businessDate}` }))).text()
+        expect(calls.getDailyReportIdsFirstPage).toHaveLength(0)
+    })
+})
+
+describe("ids-stream / チャンク分割と total", () => {
+    it("空データセットは total 0 の単一終端行になる", async () => {
+        const { config } = makeHandlersFixture({ idsStreamItems: [] })
+        const { api } = createDailyReportHandlers(config)
+        const lines = asChunks(await readNdjsonLines(await api.loader(makeApiArgs("ids-stream"))))
+        expect(lines).toHaveLength(1)
+        expect(lines[0]).toEqual({ items: [], nextCursor: null, isLast: true, total: 0 })
+    })
+
+    it("小規模データは 1 行で全件 + total + isLast", async () => {
+        const items = makeItems(5)
+        const { config, calls } = makeHandlersFixture({ idsStreamItems: items })
+        const { api } = createDailyReportHandlers(config)
+        const lines = asChunks(await readNdjsonLines(await api.loader(makeApiArgs("ids-stream"))))
+        expect(lines).toHaveLength(1)
+        expect(lines[0].items).toEqual(items)
+        expect(lines[0].total).toBe(5)
+        expect(lines[0].isLast).toBe(true)
+        expect(lines[0].nextCursor).toBeNull()
+        expect(calls.getDailyReportIds).toEqual([[TEST_EXTERNAL_USER_ID, false]])
+    })
+
+    it("9000 件は 200/4000/4000/800 の 4 チャンクに割れ、total は先頭行のみ、カーソルが連鎖する", async () => {
+        const items = makeItems(9000)
+        const { config } = makeHandlersFixture({ idsStreamItems: items })
+        const { api } = createDailyReportHandlers(config)
+        const lines = asChunks(await readNdjsonLines(await api.loader(makeApiArgs("ids-stream"))))
+
+        expect(lines.map((line) => line.items.length)).toEqual([200, 4000, 4000, 800])
+        expect(lines[0].total).toBe(9000)
+        expect(lines.slice(1).every((line) => line.total === undefined)).toBe(true)
+
+        // カーソルは各チャンク末尾アイテムのキーと一致する
+        expect(lines[0].nextCursor).toEqual({ businessDate: items[199].businessDate, reportHubId: items[199].reportHubId })
+        expect(lines[1].nextCursor).toEqual({ businessDate: items[4199].businessDate, reportHubId: items[4199].reportHubId })
+        expect(lines[2].nextCursor).toEqual({ businessDate: items[8199].businessDate, reportHubId: items[8199].reportHubId })
+        expect(lines[3].nextCursor).toBeNull()
+        expect(lines.map((line) => line.isLast)).toEqual([false, false, false, true])
+
+        // 全チャンクの連結が元配列と厳密一致する (欠落・重複なし)
+        expect(lines.flatMap((line) => line.items)).toEqual(items)
+    })
+
+    it("forceRefresh=true はサービスへ透過する", async () => {
+        const { config, calls } = makeHandlersFixture({ idsStreamItems: makeItems(1) })
+        const { api } = createDailyReportHandlers(config)
+        await (await api.loader(makeApiArgs("ids-stream", { query: "?forceRefresh=true" }))).text()
+        expect(calls.getDailyReportIds).toEqual([[TEST_EXTERNAL_USER_ID, true]])
+    })
+})
+
+describe("ids-stream / カーソル再開", () => {
+    it("中間カーソルからの再開は「厳密に後」の行から欠落・重複なく続く", async () => {
+        const items = makeItems(1100)
+        const { config } = makeHandlersFixture({ idsStreamItems: items })
+        const { api } = createDailyReportHandlers(config)
+
+        const cursorItem = items[199]
+        const query = `?cursor_report_hub_id=${cursorItem.reportHubId}&cursor_business_date=${cursorItem.businessDate}`
+        const lines = asChunks(await readNdjsonLines(await api.loader(makeApiArgs("ids-stream", { query }))))
+
+        const resumed = lines.flatMap((line) => line.items)
+        expect(resumed).toEqual(items.slice(200))
+        // 再開接続でも先頭行に最新の total が載り直す
+        expect(lines[0].total).toBe(1100)
+    })
+
+    it("NULL 営業日領域は cursor_report_hub_id 単独で再開できる", async () => {
+        const dated = makeItems(3)
+        const nullRegion: DailyReportItem[] = [
+            { reportHubId: 900, businessDate: null, sourceType: "NI" },
+            { reportHubId: 800, businessDate: null, sourceType: "NI" },
+            { reportHubId: 700, businessDate: null, sourceType: "NI" },
+        ]
+        const { config } = makeHandlersFixture({ idsStreamItems: [...dated, ...nullRegion] })
+        const { api } = createDailyReportHandlers(config)
+
+        const lines = asChunks(await readNdjsonLines(await api.loader(makeApiArgs("ids-stream", { query: "?cursor_report_hub_id=900" }))))
+        expect(lines.flatMap((line) => line.items)).toEqual([
+            { reportHubId: 800, businessDate: null, sourceType: "NI" },
+            { reportHubId: 700, businessDate: null, sourceType: "NI" },
+        ])
+    })
+
+    it("末尾以降を指すカーソルは空チャンク + isLast で正常終端する", async () => {
+        const items = makeItems(5)
+        const { config } = makeHandlersFixture({ idsStreamItems: items })
+        const { api } = createDailyReportHandlers(config)
+        const last = items[items.length - 1]
+        const query = `?cursor_report_hub_id=${last.reportHubId}&cursor_business_date=${last.businessDate}`
+        const lines = asChunks(await readNdjsonLines(await api.loader(makeApiArgs("ids-stream", { query }))))
+        expect(lines).toHaveLength(1)
+        expect(lines[0]).toEqual({ items: [], nextCursor: null, isLast: true, total: 5 })
+    })
+
+    it.each([
+        ["営業日のみ (位置を決められない)", "?cursor_business_date=2026-07-31"],
+        ["日付形式違反 (スラッシュ)", "?cursor_report_hub_id=10&cursor_business_date=2026/07/31"],
+        ["日付形式違反 (桁欠け)", "?cursor_report_hub_id=10&cursor_business_date=2026-7-31"],
+        ["非整数 ID", "?cursor_report_hub_id=abc"],
+        ["小数 ID", "?cursor_report_hub_id=12.5"],
+        ["ゼロ ID", "?cursor_report_hub_id=0"],
+        ["負数 ID", "?cursor_report_hub_id=-1"],
+        ["先頭ゼロ ID (正規形でない)", "?cursor_report_hub_id=007"],
+    ])("不正カーソル (%s) は 400 で、サービスを呼ばない", async (_label, query) => {
+        const { config, calls } = makeHandlersFixture({ idsStreamItems: makeItems(3) })
+        const { api } = createDailyReportHandlers(config)
+        const response = await api.loader(makeApiArgs("ids-stream", { query }))
+        expect(response.status).toBe(400)
+        expect(calls.getDailyReportIds).toHaveLength(0)
+    })
+})
+
+describe("ids-stream / 逐次配信", () => {
+    it("チャンクは 1 つの巨大な書き込みではなく複数回の enqueue で届く (pull 単位のバックプレッシャー)", async () => {
+        const items = makeItems(9000)
+        const { config } = makeHandlersFixture({ idsStreamItems: items })
+        const { api } = createDailyReportHandlers(config)
+        const response = await api.loader(makeApiArgs("ids-stream"))
+        const body = response.body
+        if (!body) throw new Error("body must be a stream")
+
+        // reader で読み、read() の回数 (= enqueue の粒度) を数える
+        const reader = body.getReader()
+        const decoder = new TextDecoder()
+        let readCount = 0
+        let text = ""
+        while (true) {
+            const { done, value } = await reader.read()
+            if (done) break
+            readCount += 1
+            text += decoder.decode(value, { stream: true })
+        }
+        // 200/4000/4000/800 の 4 チャンク = 4 回以上の read で届く (全体一括 1 回ではない)
+        expect(readCount).toBeGreaterThanOrEqual(4)
+        expect(text.split("\n").filter((line) => line.trim() !== "")).toHaveLength(4)
+    })
+
+    it("reader.cancel() は例外なく受理される (切断安全)", async () => {
+        const { config } = makeHandlersFixture({ idsStreamItems: makeItems(1100) })
+        const { api } = createDailyReportHandlers(config)
+        const response = await api.loader(makeApiArgs("ids-stream"))
+        const reader = response.body?.getReader()
+        if (!reader) throw new Error("body must be a stream")
+        await reader.read()
+        await expect(reader.cancel()).resolves.toBeUndefined()
+    })
+})
+
+describe("ids-stream / 中断", () => {
+    it("送出前に中断済みのリクエストは 1 行も流さずクローズする", async () => {
+        const { config } = makeHandlersFixture({ idsStreamItems: makeItems(50) })
+        const { api } = createDailyReportHandlers(config)
+        const abortController = new AbortController()
+        abortController.abort()
+        const response = await api.loader(makeApiArgs("ids-stream", { signal: abortController.signal }))
+        expect(response.status).toBe(200)
+        expect(await response.text()).toBe("")
+    })
+})

package/src/server/handlers.ts

@@ -7,8 +7,10 @@
  * - sse.loader: Redis Streams ベースのリアルタイム更新 SSE エンドポイント
  */
 import { normalizeBusinessDateKey } from "../shared/business-date"
+import { type DailyReportIdsStreamChunkLine, type DailyReportIdsStreamCursor, findIdsStreamResumeIndex } from "../shared/ids-stream"
 import { createLogger, type DailyReportLogger, LogLevel } from "../shared/logger"
 import { dailyReportSseMessageSchema } from "../shared/sse-schema"
+import type { DailyReportItem } from "../shared/types"
 import type { DailyReportAttachmentFailure, DailyReportAuthenticate, DailyReportEncodeUserId, DailyReportIdCodec, DailyReportReadAttachment, DailyReportRedisProvider } from "./ports"
 import { jsonResponseWithETag } from "./response"
 import type { DailyReportService } from "./service"
@@ -24,6 +26,171 @@ const jsonData = (payload: unknown, init?: { status?: number }): Response =>
         headers: { "Content-Type": "application/json" },
     })
 
+// ---------------- ids NDJSON ストリームの定数とヘルパー (純粋・モジュールスコープ) ----------------
+
+/**
+ * First-chunk size, tuned for time-to-first-render.
+ * 初回チャンクのアイテム数。最初の描画までの時間を優先して小さく保つ。
+ *
+ * 一覧の可視行 + オーバースキャンを一度に満たせる件数であればよい。
+ */
+const IDS_STREAM_FIRST_CHUNK_SIZE = 200
+
+/**
+ * 2 チャンク目以降のアイテム数。1 アイテムが数十バイト (id/日付/種別のみ) と軽いため
+ * 大きめに運ぶ。実データは 20 万件超に達するため、小さすぎると行数 (= pull 往復と
+ * クライアント側 publish 回数) が肥大する (4000 件 ≈ 240 KB/行、20 万件で約 50 行)。
+ */
+const IDS_STREAM_NEXT_CHUNK_SIZE = 4000
+
+/**
+ * Sanitized message for mid-stream failures (no internal details).
+ * ストリーム送出中の失敗をクライアントへ伝える定型文 (内部情報は載せない)。
+ */
+const IDS_STREAM_ERROR_CLIENT_MESSAGE = "stream interrupted by server error"
+
+/** 再開カーソルの営業日として受け付ける唯一の形式 (正規化済み YYYY-MM-DD)。 */
+const IDS_STREAM_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/
+
+/**
+ * Parses and validates resume-cursor query params (fail-closed).
+ * 再開カーソルのクエリパラメータを検証付きで解釈する処理 (不正は fail-closed)。
+ *
+ * - `cursor_report_hub_id` 単独 = 「営業日なし領域」のカーソル (businessDate: null)。
+ * - `cursor_business_date` は `cursor_report_hub_id` 無しでは意味を持たないため 400。
+ *
+ * @param url Request URL. リクエスト URL。
+ * @returns Cursor (null = 先頭から) か、検証失敗の印。
+ */
+const parseIdsStreamCursor = (url: URL): { cursor: DailyReportIdsStreamCursor | null } | { invalid: true } => {
+    const rawId = url.searchParams.get("cursor_report_hub_id")
+    const rawDate = url.searchParams.get("cursor_business_date")
+
+    if (rawId === null) {
+        // 営業日だけのカーソルは並び順上の位置を決められない
+        return rawDate === null ? { cursor: null } : { invalid: true }
+    }
+
+    const reportHubId = Number.parseInt(rawId, 10)
+    if (!Number.isSafeInteger(reportHubId) || String(reportHubId) !== rawId || reportHubId <= 0) {
+        return { invalid: true }
+    }
+
+    if (rawDate === null) {
+        return { cursor: { businessDate: null, reportHubId } }
+    }
+    if (!IDS_STREAM_DATE_PATTERN.test(rawDate)) {
+        return { invalid: true }
+    }
+    return { cursor: { businessDate: rawDate, reportHubId } }
+}
+
+/**
+ * Emits a finalized id array as chunked NDJSON lines from a resume position.
+ * 確定済み ID 配列を再開位置からチャンク行として送出するジェネレーター。
+ *
+ * `total` は最初に yield する行へ載せる (= 接続内で全量が確定した最初の行。
+ * キャッシュヒットの新規接続と再開接続では先頭行、高速先頭ページ経路では 2 行目)。
+ *
+ * @param items Stream-ordered full array. ストリーム順の全量配列。
+ * @param resumeKey Resume position (null = 先頭から)。
+ * @param firstChunkSize このジェネレーターの最初のチャンクサイズ。
+ */
+async function* streamLinesFromFullArray(items: DailyReportItem[], resumeKey: DailyReportIdsStreamCursor | null, firstChunkSize = IDS_STREAM_FIRST_CHUNK_SIZE): AsyncGenerator<DailyReportIdsStreamChunkLine> {
+    let position = resumeKey ? findIdsStreamResumeIndex(items, resumeKey) : 0
+    let isFirstYield = true
+    while (true) {
+        const chunkItems = items.slice(position, position + (isFirstYield ? firstChunkSize : IDS_STREAM_NEXT_CHUNK_SIZE))
+        position += chunkItems.length
+        const isLast = position >= items.length
+        const lastItem = chunkItems[chunkItems.length - 1]
+        yield {
+            items: chunkItems,
+            nextCursor: isLast || !lastItem ? null : { businessDate: lastItem.businessDate, reportHubId: lastItem.reportHubId },
+            isLast,
+            ...(isFirstYield ? { total: items.length } : {}),
+        }
+        isFirstYield = false
+        if (isLast) return
+    }
+}
+
+/**
+ * Wraps a line iterator into a pull-based NDJSON streaming Response.
+ * 行イテレーターを pull 駆動の NDJSON ストリーミング Response へ包む処理。
+ *
+ * - 切断検知時はイテレーターを畳んで (`return()`) DB 待ちを解放し、close する
+ *   (素の return は desiredSize > 0 のまま pull が再帰する)。
+ * - イテレーターの throw は内部情報を含まない定型エラー行 + 正常クローズへ倒す
+ *   (クライアントは「isLast 無し終端」をカーソル再開のシグナルとして扱う)。
+ */
+const buildIdsStreamResponse = (cookie: string | null, lines: AsyncGenerator<DailyReportIdsStreamChunkLine>, request: Request, logger: DailyReportLogger): Response => {
+    const encoder = new TextEncoder()
+    // cancel() の lines.return() は「pull が DB 待ちの next() を保留中」だと先取りできない。
+    // 待ちが明けた後の enqueue が閉じたストリームへ落ちて catch に入るため、切断は
+    // フラグで決定的に識別し、通常イベントとして静かに畳む (ERROR ログにしない —
+    // 全量クエリ中の離脱は日常イベントで、本物の送出失敗が雑音に埋もれる)
+    let cancelled = false
+    const stream = new ReadableStream<Uint8Array>({
+        async pull(controller) {
+            if (cancelled || request.signal.aborted) {
+                await lines.return(undefined).catch(() => {})
+                try {
+                    controller.close()
+                } catch {
+                    // cancel 済みコントローラーの close は失敗してよい
+                }
+                return
+            }
+            try {
+                const { value, done } = await lines.next()
+                if (done) {
+                    controller.close()
+                    return
+                }
+                // 保留中の next() の間に切断された場合はここで検知して静かに終える
+                if (cancelled || request.signal.aborted) {
+                    await lines.return(undefined).catch(() => {})
+                    try {
+                        controller.close()
+                    } catch {
+                        // cancel 済みコントローラーの close は失敗してよい
+                    }
+                    return
+                }
+                controller.enqueue(encoder.encode(`${JSON.stringify(value)}\n`))
+            } catch (error) {
+                if (cancelled || request.signal.aborted) {
+                    // 切断起因の enqueue/close 失敗はエラーではない
+                    return
+                }
+                logger.error(`ids-stream emission failed: ${error instanceof Error ? error.message : String(error)}`)
+                try {
+                    controller.enqueue(encoder.encode(`${JSON.stringify({ error: IDS_STREAM_ERROR_CLIENT_MESSAGE })}\n`))
+                    controller.close()
+                } catch {
+                    // 既に切断済みなら何もできない
+                }
+            }
+        },
+        cancel() {
+            cancelled = true
+            void lines.return(undefined).catch(() => {})
+        },
+    })
+
+    const headers = new Headers({
+        "Content-Type": "application/x-ndjson; charset=utf-8",
+        // no-transform: compression ミドルウェア/中間プロキシによるバッファリングを禁止する (SSE と同じ理由)
+        "Cache-Control": "private, no-cache, no-transform",
+        "X-Content-Type-Options": "nosniff",
+    })
+    if (cookie) {
+        headers.append("Set-Cookie", cookie)
+    }
+    return new Response(stream, { status: 200, headers })
+}
+
 // ---------------- 添付配信の定数とヘルパー (純粋・モジュールスコープ) ----------------
 
 /** 添付 1 件あたりの既定上限。サービス側のワイヤ上限 (既定 64 MiB) より必ず低く保つ。 */
@@ -370,13 +537,86 @@ export function createDailyReportHandlers(config: DailyReportHandlersConfig) {
             return jsonResponseWithETag(request, cookie, { businessDate: normalizedBusinessDate, reports }, 200)
         },
         /**
-         * Retrieves a list of all daily report IDs.
-         * 全ての日報 ID の一覧を取得する。
+         * Streams the full daily report id list as NDJSON chunks.
+         * 日報 ID 一覧全件を NDJSON チャンクとして逐次配信する。
+         *
+         * 全量クエリ (`SqlResultCache` の TTL / Redis epoch / in-flight コアレッシングを
+         * 素通しで維持) は常に即時に開始する。全量確定を待ってから送出するのは再開接続のみで、
+         * その場合の DB エラーはストリーム開始前に throw されて apiLoader の catch が
+         * 500 JSON を返す。新規接続はキャッシュ無しの TOP 200 高速先頭ページと競争させ、
+         * キャッシュミス時は全量確定前に最初のチャンクを送出する (最初の描画までの時間が
+         * 全体データ量に依存しない)。キャッシュヒット時は全量が即勝ちし、従来どおり
+         * 確定済み配列のメモリスライス送出になる。
          */
-        ids: async (url, cookie, request, user) => {
+        "ids-stream": async (url, cookie, request, user) => {
+            const parsed = parseIdsStreamCursor(url)
+            if ("invalid" in parsed) {
+                return jsonResponseWithETag(request, cookie, { error: { message: "Invalid cursor" } }, 400)
+            }
             const forceRefresh = url.searchParams.get("forceRefresh") === "true"
-            const dailyReportIds = await service.getDailyReportIdsByExternalId(user.id, { forceRefresh })
-            return jsonResponseWithETag(request, cookie, { ids: dailyReportIds }, 200)
+
+            // 全量 (SqlResultCache / epoch / コアレッシング維持) は常に即時に走らせ始める
+            const fullArrayPromise = service.getDailyReportIdsByExternalId(user.id, { forceRefresh })
+            // 拒否はイテレーターの await 側で扱う (ここで未処理拒否警告を出さない)
+            fullArrayPromise.catch(() => {})
+
+            if (parsed.cursor) {
+                // 再開接続: クライアントは高速先頭を受信済みなので全量確定を待つ (エラーは 500)
+                return buildIdsStreamResponse(cookie, streamLinesFromFullArray(await fullArrayPromise, parsed.cursor), request, apiLogger)
+            }
+
+            /**
+             * 新規接続: 「高速先頭ページ (TOP n・キャッシュ無し)」と「全量 (キャッシュ経由)」を
+             * 競争させ、先に確定した方で最初のチャンクを出す。キャッシュヒット時は全量が即勝ち
+             * (従来どおり先頭行に total)。キャッシュミス時は先頭ページが先に届き、最初の描画は
+             * 全量クエリの確定を待たない。total は全量確定後の最初の行に載る。
+             */
+            // キャッシュヒット時もこの TOP 200 クエリは走って結果が捨てられる (二重クエリ)。
+            // インデックス順の部分走査で ms 級と実測見積もりされており、ヒット判定のための
+            // キャッシュ同期 peek API を足す複雑さに見合わないため意図的に許容する
+            const firstPagePromise = service.getDailyReportIdsFirstPageByExternalId(user.id, IDS_STREAM_FIRST_CHUNK_SIZE)
+            firstPagePromise.catch(() => {})
+
+            const lineIterator = (async function* (): AsyncGenerator<DailyReportIdsStreamChunkLine> {
+                const winner = await Promise.race([
+                    fullArrayPromise.then(
+                        (items) => ({ kind: "full" as const, items }),
+                        (error) => ({ kind: "full-error" as const, error }),
+                    ),
+                    firstPagePromise.then(
+                        (items) => ({ kind: "page" as const, items }),
+                        () => ({ kind: "page-error" as const }),
+                    ),
+                ])
+
+                let resumeKey: DailyReportIdsStreamCursor | null = null
+                let fullItems: DailyReportItem[] | null = null
+
+                if (winner.kind === "full") {
+                    fullItems = winner.items
+                } else if (winner.kind === "page" || winner.kind === "full-error") {
+                    // 全量が先に死んでいても先頭ページが生きていれば、まずそれを届ける
+                    const pageItems = winner.kind === "page" ? winner.items : await firstPagePromise
+                    if (pageItems.length < IDS_STREAM_FIRST_CHUNK_SIZE) {
+                        // 先頭ページが上限未満 = データセット全量。全量クエリを待たずに完結する
+                        yield { items: pageItems, nextCursor: null, isLast: true, total: pageItems.length }
+                        return
+                    }
+                    const lastItem = pageItems[pageItems.length - 1]
+                    resumeKey = { businessDate: lastItem.businessDate, reportHubId: lastItem.reportHubId }
+                    // total は未知 (全量確定後の行に載せる)
+                    yield { items: pageItems, nextCursor: resumeKey, isLast: false }
+                }
+                // page-error は全量へフォールバック。full-error は上の分岐でページを出してから、ここで throw する
+                if (fullItems === null) {
+                    fullItems = await fullArrayPromise
+                }
+                // 高速先頭ページ経路 (resumeKey あり) はクライアントが既に 200 件を描画済み
+                // なので、続きは大きいチャンクで運ぶ。キャッシュヒット経路は従来どおり 200 件先頭
+                yield* streamLinesFromFullArray(fullItems, resumeKey, resumeKey ? IDS_STREAM_NEXT_CHUNK_SIZE : IDS_STREAM_FIRST_CHUNK_SIZE)
+            })()
+
+            return buildIdsStreamResponse(cookie, lineIterator, request, apiLogger)
         },
         /**
          * Retrieves details for a specific daily report.