@aiquants/daily-report 0.8.0 → 0.9.1

package/src/client/contexts/daily-report-action-context.tsx

@@ -3,16 +3,64 @@
  * 日報の楽観的 CRUD と SSE 同期を提供するアクションコンテキスト。
  */
 import { type Context, createContext, type ReactNode, useCallback, useContext, useEffect, useRef, useState } from "react"
+import { compareIdsStreamOrder, isIdsStreamOrdered, upsertInIdsStreamOrder } from "../../shared/ids-stream"
 import { createLogger, LogLevel } from "../../shared/logger"
 import type { DailyReportSseMessage } from "../../shared/sse-schema"
 import type { DailyReportCommentItem, DailyReportDetail, DailyReportItem, DailyReportUser } from "../../shared/types"
 import { useDailyReportConfig } from "../config-context"
-import { acquireMutationLock, applyDailyReportServerUpdates, clearDailyReportCache, DailyReportCache, deleteDailyReportCache, getCachedReport, registerRecentDeletion, releaseMutationLock, subscribeCacheReady, updateDailyReportCache, writeCache } from "../hooks/use-daily-report"
+import {
+    acquireMutationLock,
+    applyBroadcastReportUpdate,
+    applyDailyReportServerUpdates,
+    clearDailyReportCache,
+    DailyReportCache,
+    deleteDailyReportCache,
+    getCachedReport,
+    registerRecentDeletion,
+    releaseMutationLock,
+    subscribeCacheReady,
+    updateDailyReportCache,
+    writeCache,
+} from "../hooks/use-daily-report"
 import { useDailyReportSseConnection } from "../hooks/use-daily-report-sse-connection"
 import { getDailyReportIdsStreamSessionUserKey, refreshDailyReportIdsStream, removeDailyReportIdsStreamItem, upsertDailyReportIdsStreamItem, useDailyReportIdsStream } from "../streaming/daily-report-ids-stream-session"
+import { SSE_INITIAL_CONNECT_DEFER_MS } from "../utils/constants"
+import { useDailyReportErrorSurface } from "./daily-report-error-context"
 
 const logger = createLogger(LogLevel.INFO, "daily-report-action-context")
 
+/**
+ * Operation intent -> default banner label (Japanese).
+ * 操作 intent -> 既定バナー用の日本語ラベル。ホストは config.onError で構造化情報 (operation)
+ * を受け取り独自メッセージへ差し替えできる。
+ */
+const OPERATION_LABELS: Record<string, string> = {
+    create: "日報の作成",
+    update: "日報の保存",
+    publish: "日報の公開",
+    delete: "日報の削除",
+    addComment: "コメントの投稿",
+    deleteComment: "コメントの削除",
+    toggleStar: "スターの更新",
+    toggleRead: "既読状態の更新",
+}
+
+/** intent から利用者向けの失敗メッセージを組み立てる。 */
+const describeOperationFailure = (intent: string): string => {
+    const label = OPERATION_LABELS[intent] ?? "操作"
+    return `${label}に失敗しました。時間をおいて再度お試しください。`
+}
+
+/**
+ * Stable empty default for the optional `initialItems` prop.
+ * 省略可能な `initialItems` の安定した空既定値。
+ *
+ * 既定を `= []` にすると毎レンダーで新しい配列参照になり、render-phase の
+ * `initialItems !== prevInitialItems` 判定が常に真になって setState が無限ループし、
+ * React が描画を中断する。単一の凍結参照を共有して同一性を保つ。
+ */
+const EMPTY_INITIAL_ITEMS: DailyReportItem[] = Object.freeze([]) as readonly DailyReportItem[] as DailyReportItem[]
+
 type ActionResponse = {
     status: string
     reportHubId: number
@@ -120,8 +168,13 @@ const getUserDisplayName = (user: DailyReportUser | undefined): string => {
  * 日報のアクション（コメント追加・削除、スター、既読）を管理するプロバイダー。
  * 楽観的UI更新とAPI通信の抽象化を提供します。
  */
-export const DailyReportActionProvider = ({ children, user, initialItems = [], userId }: { children: ReactNode; user?: DailyReportUser; initialItems?: DailyReportItem[]; userId?: string | null }) => {
+export const DailyReportActionProvider = ({ children, user, initialItems = EMPTY_INITIAL_ITEMS, userId }: { children: ReactNode; user?: DailyReportUser; initialItems?: DailyReportItem[]; userId?: string | null }) => {
     const { apiBasePath, draftLabelName } = useDailyReportConfig()
+    // ミューテーション失敗の通知シーム。executeAction の catch から呼び、失敗を可視化する。
+    // ref 経由で読み、executeAction の依存に載せない (通知参照は安定しているが防御的に)
+    const { notifyError } = useDailyReportErrorSurface()
+    const notifyErrorRef = useRef(notifyError)
+    notifyErrorRef.current = notifyError
     const pendingAddCommentIds = useRef<Map<number, Map<number, string>>>(new Map())
     const pendingDeleteCommentIds = useRef<Map<number, Set<number>>>(new Map())
     const pendingStarUpdates = useRef<Map<number, boolean>>(new Map())
@@ -129,7 +182,10 @@ export const DailyReportActionProvider = ({ children, user, initialItems = [], u
     const resolvedIdMap = useRef<Map<number, number>>(new Map())
     const [version, setVersion] = useState(0)
     const [items, setItems] = useState<DailyReportItem[]>(initialItems)
-    const [isSseEnabled, setIsSseEnabled] = useState(!!userId)
+    // SSE は初回描画とその最初の中身フェッチに接続枠を譲るため、少し遅らせて自動接続する
+    // (HTTP/1.1 の 6 接続のうち 1 枠を初回描画へ回す)。手動トグル済みなら自動接続しない
+    const [isSseEnabled, setIsSseEnabled] = useState(false)
+    const hasManualSseToggleRef = useRef(false)
     const pendingAddPromises = useRef<Map<number, Promise<number>>>(new Map())
     const manuallyTrackingIds = useRef<Set<number>>(new Set())
     /** 削除済み ID を記録し、マージロジックでの復活を防止する */
@@ -305,24 +361,39 @@ export const DailyReportActionProvider = ({ children, user, initialItems = [], u
             upsertDailyReportIdsStreamItem({ reportHubId, businessDate: businessDate ?? null })
         }
         setItems((prev) => {
-            const nextBusinessDate = businessDate ?? prev.find((item) => item.reportHubId === reportHubId)?.businessDate ?? null
-            const exists = prev.some((item) => item.reportHubId === reportHubId)
-            const merged = exists ? prev.map((item) => (item.reportHubId === reportHubId ? { ...item, businessDate: nextBusinessDate } : item)) : [{ reportHubId, businessDate: nextBusinessDate }, ...prev]
-
-            return merged.sort((a, b) => {
-                const left = a.businessDate ?? ""
-                const right = b.businessDate ?? ""
-                return right.localeCompare(left)
-            })
+            const existing = prev.find((item) => item.reportHubId === reportHubId)
+            const nextBusinessDate = businessDate ?? existing?.businessDate ?? null
+            // 正準比較器 (営業日降順 → ID 降順) の位置へ二分探索で upsert する。
+            // 以前は SSE 1 件ごとに全件を localeCompare でソートし直していた (O(n log n)
+            // かつ ID 降順の副キー無しで、同日内の新規作成が誤った位置に描画されていた)
+            return upsertInIdsStreamOrder(prev, { reportHubId, businessDate: nextBusinessDate, sourceType: existing?.sourceType })
         })
     }, [])
 
     // 未登録ユーザーは SSE を有効化できない
     const toggleSse = () => {
         if (!userId) return
+        // 手動操作後は自動接続タイマーに上書きさせない
+        hasManualSseToggleRef.current = true
         setIsSseEnabled((prev) => !prev)
     }
 
+    /**
+     * Defers the initial SSE auto-connect until just after first paint.
+     * 初回 SSE 自動接続を初回描画直後まで遅らせる副作用。
+     *
+     * 依存配列: userId (ユーザーごとに provider が key リマウントされるため、切替で張り直す)。
+     * クリーンアップ: タイマー解除 (アンマウント/再マウントでのリークと二重発火を防ぐ)。
+     */
+    useEffect(() => {
+        if (!userId) return
+        const timer = setTimeout(() => {
+            // 手動でトグルされていなければ自動接続する
+            if (!hasManualSseToggleRef.current) setIsSseEnabled(true)
+        }, SSE_INITIAL_CONNECT_DEFER_MS)
+        return () => clearTimeout(timer)
+    }, [userId])
+
     /**
      * Remove a stale item from the list as a safety net.
      * フェッチ後にレポートが見つからなかった場合の安全弁としてアイテムを除去する。
@@ -368,27 +439,14 @@ export const DailyReportActionProvider = ({ children, user, initialItems = [], u
                 mergedMap.set(item.reportHubId, item)
             }
         }
-        // businessDate 降順でソート。正規化済み YYYY-MM-DD は辞書順 = 時系列順なので
-        // 文字列比較で足りる (Date 構築はチャンク到着ごとの全件ソートで比較 1 回あたり
-        // 2 個生成され、数万件 × 数十チャンクで数百万回の構築になる)。null は末尾。
-        // ストリームはソート順どおりに届き末尾へ追記されるため、通常は整列済み —
-        // O(n) の検査で確認できたらソートを丸ごと省略する (20 万件級で毎 publish の
-        // O(n log n) を O(n) へ落とす)
+        // 並び順は正準比較器 (compareIdsStreamOrder: 営業日降順 → ID 降順、null 営業日は
+        // 末尾) に一本化する。ストリームはソート順どおりに届き末尾へ追記されるため通常は
+        // 整列済み — O(n) の検査で確認できたらソートを丸ごと省略する (20 万件級で毎 publish
+        // の O(n log n) を O(n) へ落とす)。以前は営業日のみの比較で ID 降順の副キーが無く、
+        // 前回全量走査以降に作成された日報が同日グループ内の誤った位置に描画されていた
         const merged = Array.from(mergedMap.values())
-        let isSorted = true
-        for (let i = 1; i < merged.length; i++) {
-            if ((merged[i - 1].businessDate ?? "") < (merged[i].businessDate ?? "")) {
-                isSorted = false
-                break
-            }
-        }
-        if (!isSorted) {
-            merged.sort((a, b) => {
-                const left = a.businessDate ?? ""
-                const right = b.businessDate ?? ""
-                if (left === right) return 0
-                return left < right ? 1 : -1
-            })
+        if (!isIdsStreamOrdered(merged)) {
+            merged.sort(compareIdsStreamOrder)
         }
         setItems(merged)
     }
@@ -552,7 +610,9 @@ export const DailyReportActionProvider = ({ children, user, initialItems = [], u
                 case "report-publish": {
                     // report はスキーマで必須なのでバリデーション通過後は必ず存在する（if ガード不要）
                     const { report } = payload
-                    applyDailyReportServerUpdates(report.reportHubId, report)
+                    // 全ユーザー放送: report の isRead/isStarred は操作者の状態なので、
+                    // 受信者自身の per-viewer 状態を保持するマージ経路を使う
+                    applyBroadcastReportUpdate(report)
                     if (payload.type === "report-create" || payload.type === "report-publish") {
                         manuallyTrackingIds.current.add(report.reportHubId)
                         upsertItem(report.reportHubId, report.date)
@@ -651,9 +711,11 @@ export const DailyReportActionProvider = ({ children, user, initialItems = [], u
         } catch (e) {
             logger.error(`${intent} failed:`, e)
             // 切替後の失敗も同様: onFailure のロールバックが旧値をモジュールキャッシュへ
-            // 書き戻すため放棄する (プロバイダー自身の state は key リマウントで破棄済み)
+            // 書き戻すため放棄する (プロバイダー自身の state は key リマウントで破棄済み)。
+            // 通知も同じ門で守る: ユーザー切替で捨てた継続の失敗は当人に見せない
             if (isSessionStillOurs()) {
                 callbacks.onFailure?.()
+                notifyErrorRef.current({ operation: intent, message: describeOperationFailure(intent), cause: e })
             }
             throw e
         } finally {
@@ -1028,7 +1090,8 @@ export const DailyReportActionProvider = ({ children, user, initialItems = [], u
             if (targetItem) {
                 setItems((prev) => {
                     if (prev.some((i) => i.reportHubId === id)) return prev
-                    return [targetItem, ...prev].sort((a, b) => (b.businessDate ?? "").localeCompare(a.businessDate ?? ""))
+                    // ロールバックも正準比較器の位置へ戻す (第 3 の比較器を持たない)
+                    return upsertInIdsStreamOrder(prev, targetItem)
                 })
             }
         }

package/src/client/contexts/daily-report-error-context.spec.tsx

@@ -0,0 +1,66 @@
+/**
+ * Tests for the mutation error-surface seam.
+ * ミューテーション通知シームのテスト。
+ */
+import { fireEvent, render, screen } from "@testing-library/react"
+import { describe, expect, it, vi } from "vitest"
+import { DailyReportConfigProvider } from "../config-context"
+import { DailyReportErrorProvider, useDailyReportErrorSurface } from "./daily-report-error-context"
+
+/** notifyError を発火するだけのプローブ。 */
+const Trigger = ({ label = "発火" }: { label?: string }) => {
+    const { notifyError } = useDailyReportErrorSurface()
+    return (
+        <button type="button" onClick={() => notifyError({ operation: "update", message: "日報の保存に失敗しました。" })}>
+            {label}
+        </button>
+    )
+}
+
+const renderWithConfig = (node: React.ReactNode, onError?: (info: { operation: string; message: string }) => void) =>
+    render(
+        <DailyReportConfigProvider config={onError ? { onError } : undefined}>
+            <DailyReportErrorProvider>{node}</DailyReportErrorProvider>
+        </DailyReportConfigProvider>,
+    )
+
+describe("DailyReportErrorProvider", () => {
+    it("shows a role=alert banner when no onError is injected", () => {
+        renderWithConfig(<Trigger />)
+        expect(screen.queryByRole("alert")).toBeNull()
+        fireEvent.click(screen.getByText("発火"))
+        const banner = screen.getByRole("alert")
+        expect(banner).toHaveTextContent("日報の保存に失敗しました。")
+    })
+
+    it("delegates to config.onError and does NOT render the default banner", () => {
+        const onError = vi.fn()
+        renderWithConfig(<Trigger />, onError)
+        fireEvent.click(screen.getByText("発火"))
+        expect(onError).toHaveBeenCalledWith(expect.objectContaining({ operation: "update", message: "日報の保存に失敗しました。" }))
+        // ホストへ委譲したときは内蔵バナーを出さない (二重表示防止)
+        expect(screen.queryByRole("alert")).toBeNull()
+    })
+
+    it("dismisses the banner via the close button", () => {
+        renderWithConfig(<Trigger />)
+        fireEvent.click(screen.getByText("発火"))
+        expect(screen.getByRole("alert")).toBeInTheDocument()
+        fireEvent.click(screen.getByLabelText("閉じる"))
+        expect(screen.queryByRole("alert")).toBeNull()
+    })
+
+    it("notifyError is a safe no-op outside the provider", () => {
+        // Provider の外でも購読できて壊れない (アクションコンテキストの防御的呼び出しを保証)
+        const Standalone = () => {
+            const { notifyError } = useDailyReportErrorSurface()
+            return (
+                <button type="button" onClick={() => notifyError({ operation: "delete", message: "x" })}>
+                    無所属
+                </button>
+            )
+        }
+        render(<Standalone />)
+        expect(() => fireEvent.click(screen.getByText("無所属"))).not.toThrow()
+    })
+})

package/src/client/contexts/daily-report-error-context.tsx

@@ -0,0 +1,98 @@
+/**
+ * Error-surface seam for daily-report mutations.
+ * 日報ミューテーション失敗を利用者へ可視化するための通知シーム。
+ *
+ * 保存・公開・削除・コメント等の失敗は、これまで握り潰されてボタンが成功したかのように
+ * 復帰していた。ここでミューテーションの失敗を一元的に受け取り、`config.onError` が
+ * 注入されていればホストへ委譲し、無ければパッケージ内蔵の `role="alert"` バナーで表示する。
+ * `notifyError` は Provider 外でも安全に呼べる (既定は no-op) ため、アクションコンテキストは
+ * 存在を前提にせず呼び出せる。
+ */
+import { createContext, type ReactNode, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react"
+import { type DailyReportErrorInfo, useDailyReportConfig } from "../config-context"
+
+/** バナーの自動消滅までの既定時間 (ms)。手動クローズでも消せる。 */
+const ERROR_BANNER_AUTO_DISMISS_MS = 8_000
+
+type DailyReportErrorSurface = {
+    /** ミューテーション失敗を通知する。 */
+    notifyError: (info: DailyReportErrorInfo) => void
+}
+
+/** 既定は no-op (Provider 外で呼んでも壊れない)。 */
+const DailyReportErrorContext = createContext<DailyReportErrorSurface>({ notifyError: () => {} })
+
+/**
+ * Returns the error-surface API (safe no-op outside the provider).
+ * 通知 API を返す処理 (Provider 外では no-op)。
+ */
+export const useDailyReportErrorSurface = (): DailyReportErrorSurface => useContext(DailyReportErrorContext)
+
+/**
+ * Provides the mutation error surface and renders the default alert banner.
+ * ミューテーション通知シームを供給し、既定のアラートバナーを描画するプロバイダー。
+ *
+ * `config.onError` があればホストへ委譲し、内蔵バナーは描画しない (二重表示防止)。
+ */
+export const DailyReportErrorProvider = ({ children }: { children: ReactNode }) => {
+    const { onError } = useDailyReportConfig()
+    const [banner, setBanner] = useState<DailyReportErrorInfo | null>(null)
+    // onError を ref 経由で読み、notifyError の参照を安定させる (毎回新関数だと購読側が再レンダー)
+    const onErrorRef = useRef(onError)
+    onErrorRef.current = onError
+    const dismissTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+    const notifyError = useCallback((info: DailyReportErrorInfo) => {
+        const host = onErrorRef.current
+        if (host) {
+            // ホストが通知 UI を持つ場合は委譲し、内蔵バナーは出さない
+            host(info)
+            return
+        }
+        setBanner(info)
+    }, [])
+
+    const dismiss = useCallback(() => {
+        if (dismissTimerRef.current !== null) {
+            clearTimeout(dismissTimerRef.current)
+            dismissTimerRef.current = null
+        }
+        setBanner(null)
+    }, [])
+
+    /**
+     * バナー表示中は一定時間で自動的に消す副作用。
+     * 依存配列: banner (新しい失敗が来るたびにタイマーを張り直す)。
+     * クリーンアップ: タイマー解除 (アンマウント/再通知でのリークと二重発火を防ぐ)。
+     */
+    useEffect(() => {
+        if (!banner) return
+        dismissTimerRef.current = setTimeout(() => setBanner(null), ERROR_BANNER_AUTO_DISMISS_MS)
+        return () => {
+            if (dismissTimerRef.current !== null) {
+                clearTimeout(dismissTimerRef.current)
+                dismissTimerRef.current = null
+            }
+        }
+    }, [banner])
+
+    const value = useMemo(() => ({ notifyError }), [notifyError])
+
+    return (
+        <DailyReportErrorContext.Provider value={value}>
+            {children}
+            {banner && (
+                <div
+                    // role="alert" で SR へ即時読み上げさせる。fixed トーストで操作を妨げない
+                    role="alert"
+                    data-testid="daily-report-error-banner"
+                    className="fade-in slide-in-from-bottom-2 fixed inset-x-0 bottom-4 z-[100] mx-auto flex w-fit max-w-[92vw] animate-in items-center gap-3 rounded-lg border border-red-300 bg-red-600 px-4 py-2.5 text-sm text-white shadow-lg duration-200 dark:border-red-500/60 dark:bg-red-700">
+                    <span className="font-medium">{banner.message}</span>
+                    <button type="button" aria-label="閉じる" onClick={dismiss} className="shrink-0 rounded px-1.5 py-0.5 font-bold text-white/90 transition-colors hover:bg-red-700 hover:text-white dark:hover:bg-red-800">
+                        ✕
+                    </button>
+                </div>
+            )}
+        </DailyReportErrorContext.Provider>
+    )
+}

package/src/client/hooks/use-daily-report.spec.ts

@@ -30,6 +30,7 @@ describe("DailyReportCache public API", () => {
     let getCachedReport: typeof import("./use-daily-report").getCachedReport
     let updateDailyReportCache: typeof import("./use-daily-report").updateDailyReportCache
     let applyDailyReportServerUpdates: typeof import("./use-daily-report").applyDailyReportServerUpdates
+    let applyBroadcastReportUpdate: typeof import("./use-daily-report").applyBroadcastReportUpdate
 
     beforeEach(async () => {
         // モジュールキャッシュをリセットして、getGlobal がカスタム TTL を読み込むようにする
@@ -44,6 +45,7 @@ describe("DailyReportCache public API", () => {
         getCachedReport = mod.getCachedReport
         updateDailyReportCache = mod.updateDailyReportCache
         applyDailyReportServerUpdates = mod.applyDailyReportServerUpdates
+        applyBroadcastReportUpdate = mod.applyBroadcastReportUpdate
     })
 
     afterEach(() => {
@@ -100,8 +102,9 @@ describe("DailyReportCache public API", () => {
         })
     })
 
-    describe("applyDailyReportServerUpdates", () => {
-        it("キャッシュ済みレポートを完全置換する", () => {
+    describe("applyDailyReportServerUpdates (信頼経路: 自分の HTTP 応答・自分宛 status-update)", () => {
+        it("キャッシュ済みレポートを完全置換する (per-viewer 値も配信値を採用)", () => {
+            // 信頼経路の値は受信者自身の状態なので、そのまま書いてよい
             writeCache(makeMockReport({ subject: "Old", content: "Old" }), Date.now() + 1000)
             applyDailyReportServerUpdates(1, makeMockReport({ subject: "Fresh", content: "Fresh" }))
             const cached = getCachedReport(1)
@@ -114,6 +117,51 @@ describe("DailyReportCache public API", () => {
             expect(getCachedReport(42)?.subject).toBe("New")
         })
     })
+
+    describe("applyBroadcastReportUpdate (放送経路: 全ユーザー宛 SSE)", () => {
+        it("共有フィールドは配信値で更新し、per-viewer (isRead/isStarred) は受信者の値を保持する", () => {
+            // SSE の report が運ぶ isRead/isStarred は送信者 (操作者) の状態であり、
+            // 受信者のキャッシュへそのまま書くと他人の既読/スター状態で上書きされる
+            writeCache(makeMockReport({ subject: "Old", content: "Old", isRead: true, isStarred: true }), Date.now() + 1000)
+            applyBroadcastReportUpdate(makeMockReport({ subject: "Fresh", content: "Fresh", isRead: false, isStarred: false }))
+            const cached = getCachedReport(1)
+            expect(cached?.subject).toBe("Fresh")
+            expect(cached?.content).toBe("Fresh")
+            // 受信者自身の per-viewer 状態が生き残る
+            expect(cached?.isRead).toBe(true)
+            expect(cached?.isStarred).toBe(true)
+        })
+
+        it("commentItems[].isMine は per-viewer: キャッシュ済みは保持、送信者由来の新規は false 化する", () => {
+            // isMine はサーバーが送信者視点で計算するため、そのまま取り込むと受信者に
+            // 他人のコメントが「自分の」削除ボタン付きで見え、自分のコメントは isMine を失う
+            writeCache(makeMockReport({ commentItems: [{ id: 1, userName: "自分", content: "私の", createdAt: "2026-01-01 00:00:00", userId: "ENC8", isMine: true }] }) as never, Date.now() + 1000)
+            applyBroadcastReportUpdate(
+                makeMockReport({
+                    commentItems: [
+                        { id: 1, userName: "自分", content: "私の", createdAt: "2026-01-01 00:00:00", userId: "ENC8", isMine: false },
+                        { id: 2, userName: "他人", content: "他人の", createdAt: "2026-01-01 00:01:00", userId: "ENC9", isMine: true },
+                    ],
+                }) as never,
+            )
+            const cached = getCachedReport(1)
+            // 受信者自身のコメント (id=1) の isMine は保持、送信者が「自分の」とした id=2 は false 化
+            expect(cached?.commentItems.find((c) => c.id === 1)?.isMine).toBe(true)
+            expect(cached?.commentItems.find((c) => c.id === 2)?.isMine).toBe(false)
+        })
+
+        it("未キャッシュの ID も中立化して種まきする (行が stale 安全弁で消えるのを防ぐ)", () => {
+            // 未キャッシュを書かないと、鮮度窓内のリストキャッシュに新 id が無く、行が
+            // report=null に解決してトゥームストーン化され、作成/公開された日報が消える
+            applyBroadcastReportUpdate(makeMockReport({ reportHubId: 42, subject: "New", isRead: true, isStarred: true, commentItems: [{ id: 9, userName: "他人", content: "x", createdAt: "2026-01-01 00:00:00", userId: "ENC9", isMine: true }] }) as never)
+            const cached = getCachedReport(42)
+            expect(cached?.subject).toBe("New")
+            // per-viewer は中立値で入る (送信者の true を持ち込まない)
+            expect(cached?.isRead).toBe(false)
+            expect(cached?.isStarred).toBe(false)
+            expect(cached?.commentItems[0]?.isMine).toBe(false)
+        })
+    })
 })
 
 describe("getGlobal behavior (window グローバル変数の読み取り)", () => {
@@ -153,3 +201,60 @@ describe("getGlobal behavior (window グローバル変数の読み取り)", ()
         expect(mod.getCachedReport(1)).toBeNull()
     })
 })
+
+describe("useDailyReportDetail の初回フェッチ (デバウンス適用範囲)", () => {
+    let mod: typeof import("./use-daily-report")
+
+    beforeEach(async () => {
+        vi.resetModules()
+        mod = await import("./use-daily-report")
+        vi.useFakeTimers()
+    })
+
+    afterEach(() => {
+        vi.useRealTimers()
+        vi.unstubAllGlobals()
+    })
+
+    /** business-date 応答を 1 件返す fetch スタブ。呼び出し回数を記録する。 */
+    const stubFetch = () => {
+        const calls: string[] = []
+        vi.stubGlobal(
+            "fetch",
+            vi.fn(async (input: RequestInfo | URL) => {
+                calls.push(String(input))
+                return new Response(JSON.stringify({ reports: [makeMockReport({ reportHubId: 7, date: "2026-01-01" })] }), { status: 200, headers: { "Content-Type": "application/json" } })
+            }),
+        )
+        return calls
+    }
+
+    it("未キャッシュの初回は即フェッチする (120ms のデバウンスを掛けない)", async () => {
+        const { renderHook, act } = await import("@testing-library/react")
+        const calls = stubFetch()
+        renderHook(() => mod.useDailyReportDetail(7, "2026-01-01"))
+        // タイマーを進めずマイクロタスクだけ流す → 即時 (0ms) 発火の検証
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(0)
+        })
+        expect(calls.length).toBe(1)
+        expect(calls[0]).toContain("business-date?businessDate=2026-01-01")
+    })
+
+    it("キャッシュ済み (stale) の再取得はデバウンスされる", async () => {
+        const { renderHook, act } = await import("@testing-library/react")
+        const calls = stubFetch()
+        // 期限切れのキャッシュを用意 → 表示は即、再取得はデバウンス対象
+        mod.writeCache(makeMockReport({ reportHubId: 7, date: "2026-01-01" }), Date.now() - 1)
+        renderHook(() => mod.useDailyReportDetail(7, "2026-01-01"))
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(0)
+        })
+        // 0ms 時点では発火しない (スクロール churn 吸収のためのデバウンス)
+        expect(calls.length).toBe(0)
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(120)
+        })
+        expect(calls.length).toBe(1)
+    })
+})

package/src/client/hooks/use-daily-report.ts

@@ -7,6 +7,7 @@ import { normalizeBusinessDateKey } from "../../shared/business-date"
 import { createLogger, LogLevel } from "../../shared/logger"
 import type { DailyReportDetail } from "../../shared/types"
 import { useDailyReportConfig } from "../config-context"
+import { DAILY_REPORT_FETCH_DEBOUNCE_MS } from "../utils/constants"
 
 const logger = createLogger(LogLevel.INFO, "use-daily-report")
 
@@ -22,7 +23,6 @@ const getGlobal = (k: string, d: number): number => {
 }
 const TTL = getGlobal("__DAILY_REPORT_CACHE_TTL__", 300_000)
 const REVIVE_MS = getGlobal("__DAILY_REPORT_CACHE_REVIVE_MS__", 60_000)
-const FETCH_DEBOUNCE_MS = 120
 
 // --- Cache Store (Centralized State) ---
 type CacheEntry<T> = { data: T; expiresAt: number }
@@ -270,11 +270,40 @@ export const subscribeCacheReady = (reportHubId: number, callback: () => void):
     }
 }
 
-export const applyDailyReportServerUpdates = (_reportHubIdd: number, report: DailyReportDetail) => {
+export const applyDailyReportServerUpdates = (_reportHubId: number, report: DailyReportDetail) => {
     DailyReportCache.prune()
     DailyReportCache.set(report, Date.now() + TTL)
 }
 
+/**
+ * Applies a broadcast (cross-user SSE) report while preserving the viewer's own per-viewer state.
+ * 全ユーザー放送 (SSE) の report を、受信者自身の per-viewer 状態を保持したまま反映する処理。
+ *
+ * SSE の report-create/update/publish が運ぶ isRead/isStarred は**操作した本人の状態**。
+ * そのまま書くと受信者の既読/スター表示が他人の状態で上書きされる。共有フィールドだけを
+ * 取り込み、per-viewer フィールドは受信者のキャッシュ値を保持する。ローカルに無い日報は
+ * 種まきしない (送信者の per-viewer 値で汚すより、次のフェッチが受信者視点の正しい値を
+ * 取るのに任せるほうが安全)。
+ *
+ * ❗ 信頼できる経路 (自分の HTTP 応答・recipient フィルタ済みの自分宛 status-update) は
+ * {@link applyDailyReportServerUpdates} を使うこと — そちらは値をそのまま書く。
+ */
+export const applyBroadcastReportUpdate = (report: DailyReportDetail) => {
+    DailyReportCache.prune()
+    const cached = DailyReportCache.getReport(report.reportHubId, true)
+    // per-viewer フィールド (isRead / isStarred / commentItems[].isMine) は送信者視点なので
+    // 受信者のキャッシュ値を保持し、未キャッシュなら中立値 (false) で置く。共有フィールドは配信値。
+    // ❗ 未キャッシュでも必ず書く: 書かないと鮮度窓内のリストキャッシュに新 id が載らず、
+    //   作成/公開された他ユーザーの日報が stale 安全弁でトゥームストーン化され、閲覧中の
+    //   受信者の一覧から恒久的に消える (set は既定で syncList=true = リストにも反映する)
+    const cachedMine = new Map<number | string, boolean>()
+    for (const c of cached?.commentItems ?? []) {
+        cachedMine.set(c.id, c.isMine ?? false)
+    }
+    const commentItems = (report.commentItems ?? []).map((c) => ({ ...c, isMine: cachedMine.get(c.id) ?? false }))
+    DailyReportCache.set({ ...report, isRead: cached?.isRead ?? false, isStarred: cached?.isStarred ?? false, commentItems }, Date.now() + TTL)
+}
+
 // --- Data Loading ---
 /**
  * Fetch a single report by ID.
@@ -401,6 +430,11 @@ export const useDailyReportDetail = (reportHubId: number, businessDate: string |
         setIsLoading(!cached)
         setIsRefetching(true)
 
+        // 未キャッシュ (骨組み表示中) の初回取得は即時に走らせる。デバウンスはスクロール連打の
+        // 無駄取りを抑える目的なので、スクロール churn の無い初回に効かせると純粋な遅延になる。
+        // キャッシュ済み (内容表示中) の stale 再取得だけデバウンスして churn を吸収する
+        const debounceMs = cached ? DAILY_REPORT_FETCH_DEBOUNCE_MS : 0
+
         const timer = setTimeout(async () => {
             if (reqRef.current.token !== token) return
             try {
@@ -424,7 +458,7 @@ export const useDailyReportDetail = (reportHubId: number, businessDate: string |
                     setIsRefetching(false)
                 }
             }
-        }, FETCH_DEBOUNCE_MS)
+        }, debounceMs)
 
         return () => clearTimeout(timer)
     }, [reportHubId, businessDate, apiBasePath])