@aiquants/daily-report 0.6.2 → 0.7.0

package/src/server/service.ts

@@ -8,10 +8,10 @@ import { aliasedTable, and, asc, desc, eq, getColumns, inArray, isNull, or, sql
 import { normalizeBusinessDateKey } from "../shared/business-date"
 import { createLogger, type DailyReportLogger, LogLevel } from "../shared/logger"
 import { commentAddMessageSchema, commentDeleteMessageSchema, reportCreateMessageSchema, reportDeleteMessageSchema, reportPublishMessageSchema, reportUpdateMessageSchema, statusUpdateMessageSchema } from "../shared/sse-schema"
-import type { DailyReportComment, DailyReportCommentItem, DailyReportDetail, DailyReportInterviewer, DailyReportItem, DailyReportLabelDef } from "../shared/types"
+import type { DailyReportAttachmentSummary, DailyReportComment, DailyReportCommentItem, DailyReportDetail, DailyReportInterviewer, DailyReportItem, DailyReportLabelDef } from "../shared/types"
 import type { EpochStore, SqlResultCache, SqlResultCacheQueryOptions } from "./cache"
 import type { DailyReportExternalSource } from "./external-source"
-import type { DailyReportEncodeUserId, DailyReportRedisProvider, DailyReportResolveUserId } from "./ports"
+import type { DailyReportEncodeUserId, DailyReportIdCodec, DailyReportRedisProvider, DailyReportResolveUserId } from "./ports"
 import type { DailyReportTables, DailyReportUserTable } from "./schema"
 
 export type { SqlResultCacheQueryOptions }
@@ -113,7 +113,7 @@ const cols = (t: unknown) => getColumns(t as Parameters<typeof getColumns>[0])
 export type DailyReportServiceConfig = {
     /** drizzle mssql データベースハンドル。 */
     db: DailyReportDb
-    /** 日報 6 テーブル (アプリ既存モデルまたは defineDailyReportSchema 生成物)。 */
+    /** 日報 7 テーブル (アプリ既存モデルまたは defineDailyReportSchema 生成物)。`attachment` のみ任意。 */
     tables: DailyReportTables
     /** 表示名解決に使う外部ユーザーテーブル ({ id, displayName })。 */
     userTable: DailyReportUserTable
@@ -145,6 +145,15 @@ export type DailyReportServiceConfig = {
     businessDateTtlMs?: number
     /** 外部 ID → 内部 ID のプロセス内キャッシュを無効化 (テスト用)。 */
     disableUserIdCache?: boolean
+    /**
+     * 添付 ID の難読化コーデック。
+     *
+     * 任意にしているのは、添付テーブルを注入しない消費アプリと既存テストのフィクスチャを
+     * 壊さないため。未注入なら添付一覧は常に空になる (縮退動作)。
+     * ユーザー ID 用のコーデックとは **別インスタンス**を渡すこと。同一だと
+     * レスポンス中の `userId` トークンがそのまま添付トークンとして解釈できてしまう。
+     */
+    attachmentIdCodec?: DailyReportIdCodec
     /** ロガー (既定は console ベース)。 */
     logger?: DailyReportLogger
 }
@@ -264,6 +273,12 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
     type HubRecord = HubQueryRow & {
         labels?: RawJsonLabel[]
         comments?: RawJsonComment[]
+        /**
+         * 添付ファイル一覧。**任意にしない。**
+         * `?` を付けると `mapHubRecord` 側で `?? []` が必要になり、注入を忘れた読み取り経路が
+         * 黙って空配列を返す。必須にしておけば注入漏れは全呼び出し箇所でコンパイルエラーになる。
+         */
+        attachments: DailyReportAttachmentSummary[]
     }
 
     /** 外部ソースアダプタの select 追加フィールドを構築する。 */
@@ -329,9 +344,11 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
 
         // 作成区分がアプリ設定の下書き候補に合致する場合、ラベル一覧に下書きラベルが含まれるよう補完
         const isCreationCategoryDraft = creationCategory ? draftLabelNames.includes(creationCategory) : false
-        if (isCreationCategoryDraft && cachedDraftLabelId && !labelsRaw.some((l) => l.id === cachedDraftLabelId)) {
+        // 同期関数なので DB へは問い合わせず、既に解決済みのキャッシュがある場合だけ補完する
+        const cachedPrimaryDraftLabelId = cachedDraftLabelIds?.[0] ?? null
+        if (isCreationCategoryDraft && cachedPrimaryDraftLabelId && !labelsRaw.some((l) => l.id === cachedPrimaryDraftLabelId)) {
             labelsRaw.push({
-                id: cachedDraftLabelId,
+                id: cachedPrimaryDraftLabelId,
                 name: draftLabelName,
                 color: null,
             })
@@ -364,16 +381,26 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
                 userId: encodeUserId(c.userId),
                 isMine: currentUserId ? c.userId === currentUserId : false,
             })),
+            // `?? []` を書かない。HubRecord 側で必須にしてあるため、注入漏れはここではなく
+            // 呼び出し箇所でコンパイルエラーになる (それが検知したい事象)。
+            attachments: row.attachments,
         }
     }
 
     /**
      * Fetches daily report IDs alongside normalized business dates.
      * 日報 ID と正規化済み営業日を取得する内部処理。
+     *
+     * ❗ 可視性述語は他の 3 経路 (営業日一覧 / 詳細取得 / 添付取得) と**意図的に 1 つ緩い**。
+     * ここだけ `isNull(DailyReportHub.userId)` を追加で許しており、投稿者を持たない
+     * 取込元の日報を一覧から消さないための緩和である。返すのは ID・営業日・ソース種別だけで
+     * 本文も添付も含まないため、緩めても内容は漏れない。
+     * この差分は無自覚なものではなく、`service.spec.ts` が明示的に表明して固定している。
+     * 他の 3 経路をこの形に合わせてはならない (合わせると内容が漏れる)。
      */
     const fetchDailyReportIdsByUserId = async (userId: number): Promise<DailyReportItem[]> => {
         const DraftLabelRelation = aliasedTable(DailyReportHub_Label as unknown as Parameters<typeof aliasedTable>[0], "draft_label") as unknown as typeof DailyReportHub_Label
-        const draftLabelId = await getDraftLabelId()
+        const draftLabelJoinIds = await getDraftLabelJoinIds()
 
         const result = await db
             .select<{ reportHubId: number; businessDate: Date | string | null; sourceType: string }>({
@@ -382,7 +409,7 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
                 sourceType: DailyReportHub.sourceType,
             })
             .from(DailyReportHub)
-            .leftJoin(DraftLabelRelation, and(eq(DraftLabelRelation.hubId, DailyReportHub.id), eq(DraftLabelRelation.labelId, draftLabelId ?? -1)))
+            .leftJoin(DraftLabelRelation, and(eq(DraftLabelRelation.hubId, DailyReportHub.id), inArray(DraftLabelRelation.labelId, draftLabelJoinIds)))
             .where(and(isNull(DailyReportHub.deletedAt), or(eq(DailyReportHub.userId, userId), isNull(DailyReportHub.userId), isNull(DraftLabelRelation.hubId))))
             .orderBy(desc(DailyReportHub.businessDate), desc(DailyReportHub.id))
 
@@ -412,7 +439,8 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
             .where(and(eq(DailyReportHub.businessDate, sql`${normalizedBusinessDate}`), isNull(DailyReportHub.deletedAt)))
             .orderBy(desc(DailyReportHub.id))
 
-        return rows.map((row) => mapHubRecord(row))
+        const attachmentsMap = await getAttachmentsByHubIds(rows.map((r) => r.hub.id))
+        return rows.map((row) => mapHubRecord({ ...row, attachments: attachmentsMap.get(row.hub.id) ?? [] }))
     }
 
     /**
@@ -491,19 +519,212 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
     }
 
     /**
-     * Retrieves the ID of the draft label.
-     * 下書きラベルの ID を取得する（キャッシュ付き）。
+     * Retrieves every label id that counts as a draft.
+     * 下書きとみなすラベル ID を**すべて**取得する処理 (キャッシュ付き)。
+     *
+     * ❗ 可視性述語は必ずこちら (複数形) を使うこと。`draftLabelNames` には複数のラベル名を
+     * 注入できる (取込元ごとに下書きの呼び名が違うため) のに、1 個の ID だけで結合すると
+     * **2 つ目以降の下書きラベルが付いた日報が誰にでも可視になる**。
+     * 名前が 1 つも解決できない場合は空配列を返し、呼び出し側は結合対象を
+     * 「存在しない ID」にして「下書きは存在しない」と解釈する。
+     *
+     * @returns Draft label ids, ascending. 昇順の下書きラベル ID 群。
+     */
+    let cachedDraftLabelIds: number[] | null = null
+    const getDraftLabelIds = async (): Promise<number[]> => {
+        if (cachedDraftLabelIds !== null) return cachedDraftLabelIds
+        const rows = await db.select<{ id: number }>({ id: DailyReportLabel.id }).from(DailyReportLabel).where(inArray(DailyReportLabel.name, draftLabelNames)).orderBy(DailyReportLabel.id)
+        cachedDraftLabelIds = rows.map((row) => row.id)
+        return cachedDraftLabelIds
+    }
+
+    /**
+     * Join targets for the draft-label relation, safe when no draft label exists.
+     * 下書きラベル関連の結合対象。下書きラベルが 1 件も無い場合でも安全に働く値。
+     *
+     * `inArray` に空配列を渡すと方言によっては構文エラーや常に真になりうるため、
+     * 実在しない ID (`-1`) を 1 個入れて「どの行にも一致しない」ことを明示する。
+     *
+     * @returns Ids to join on. 結合に使う ID 群。
+     */
+    const getDraftLabelJoinIds = async (): Promise<number[]> => {
+        const ids = await getDraftLabelIds()
+        return ids.length > 0 ? ids : [-1]
+    }
+
+    /**
+     * Retrieves the canonical draft label id used when creating a draft.
+     * 下書きを作成するときに付与する代表の下書きラベル ID を取得する処理。
+     *
+     * 付与は 1 個に決めなければならないため `draftLabelNames` の先頭に対応する ID を返す。
+     * **可視性判定には使わないこと** (`getDraftLabelIds` を使う)。
+     *
+     * @returns The canonical draft label id, or null when it does not exist. 代表の下書きラベル ID (存在しなければ null)。
      */
-    let cachedDraftLabelId: number | null = null
     const getDraftLabelId = async (): Promise<number | null> => {
-        if (cachedDraftLabelId !== null) return cachedDraftLabelId
-        const [label] = await db.select<{ id: number }>({ id: DailyReportLabel.id }).top(1).from(DailyReportLabel).where(inArray(DailyReportLabel.name, draftLabelNames))
+        const ids = await getDraftLabelIds()
+        if (ids.length === 0) return null
+        // 先頭の名前に対応する ID を選ぶ。ID 順ではなく注入順を正とする (代表名は draftLabelName)
+        const [primary] = await db.select<{ id: number }>({ id: DailyReportLabel.id }).top(1).from(DailyReportLabel).where(eq(DailyReportLabel.name, draftLabelName))
+        return primary?.id ?? ids[0]
+    }
 
-        if (label) {
-            cachedDraftLabelId = label.id
-            return cachedDraftLabelId
+    /**
+     * Derives the tri-state verification status of an attachment's backing object.
+     * 添付ファイル実体の検証状態 (三値) を導出する処理。
+     *
+     * 判定不能 (`unknown`) を `absent` へ丸めない。存在確認そのものが失敗した場合を
+     * 偽の真偽で埋めると、一時的な権限・通信障害が「消失」として表示される。
+     */
+    const deriveAttachmentState = (checkedAt: Date | string | null, missingAt: Date | string | null): DailyReportAttachmentSummary["state"] => {
+        if (missingAt != null) return "absent"
+        if (checkedAt != null) return "present"
+        return "unknown"
+    }
+
+    /**
+     * Fetches attachments for multiple hubs in one query, keyed by hub id.
+     * 複数 hub の添付ファイルを 1 クエリで取得し hub ID をキーにまとめる処理。
+     *
+     * 一覧描画は N 件の日報を同時に返すため、日報ごとに問い合わせると N+1 になる。
+     * ラベル・コメントと同じ一括取得の流儀に揃える。
+     *
+     * @param hubIds Hub ids to fetch attachments for. 添付を取得する hub ID 群。
+     * @returns Attachments grouped by hub id. hub ID ごとにまとめた添付一覧。
+     */
+    const getAttachmentsByHubIds = async (hubIds: number[]): Promise<Map<number, DailyReportAttachmentSummary[]>> => {
+        const map = new Map<number, DailyReportAttachmentSummary[]>()
+        const attachment = tables.attachment
+        // codec は config 直参照。createDailyReportService の分割代入は 8 キーのみで、
+        // 裸の識別子として書くと TS2304 になる (任意設定は config.x で読むのがこのファイルの様式)
+        const codec = config.attachmentIdCodec
+        if (hubIds.length === 0 || !attachment || !codec) {
+            return map
+        }
+
+        const rows = await db
+            .select<{ id: number; hubId: number; fileName: string; fileType: string | null; fileSize: number | null; createdAt: Date | string | null; objectCheckedAt: Date | string | null; objectMissingAt: Date | string | null }>({
+                id: attachment.id,
+                hubId: attachment.hubId,
+                fileName: attachment.fileName,
+                fileType: attachment.fileType,
+                fileSize: attachment.fileSize,
+                createdAt: attachment.createdAt,
+                objectCheckedAt: attachment.objectCheckedAt,
+                objectMissingAt: attachment.objectMissingAt,
+            })
+            .from(attachment)
+            .where(inArray(attachment.hubId, hubIds))
+            .orderBy(asc(attachment.createdAt), asc(attachment.id))
+
+        for (const row of rows) {
+            // 内部数値 ID はここで難読化トークンへ変換する。以降クライアントへ生 ID は出ない。
+            // `uploaded_by` / `created_by` / `updated_by` / `file_path` は選択もしない
+            const item: DailyReportAttachmentSummary = {
+                id: codec.encode(Number(row.id)),
+                fileName: String(row.fileName),
+                fileType: row.fileType ? String(row.fileType) : null,
+                fileSize: row.fileSize != null ? Number(row.fileSize) : null,
+                createdAt: formatDateValue(row.createdAt, "YYYY-MM-DD HH:mm:ss"),
+                state: deriveAttachmentState(row.objectCheckedAt, row.objectMissingAt),
+            }
+            const list = map.get(Number(row.hubId))
+            if (list) {
+                list.push(item)
+            } else {
+                map.set(Number(row.hubId), [item])
+            }
+        }
+
+        return map
+    }
+
+    /**
+     * Fetches one attachment together with its visibility check for a given user.
+     * 指定ユーザーの可視性判定込みで添付ファイル 1 件を取得する処理。
+     *
+     * 認可は SQL 側で完結させる。アプリ層のフィルタリングに依存しない。
+     * 認可されない / 存在しない / 親日報が論理削除済みのいずれでも `null` を返すため、
+     * 呼び出し側は 403 と 404 を区別せず 404 とすること (存在オラクル回避)。
+     *
+     * 本関数は意図的に `SqlResultCache.getOrFetch` を通さない。これは読み取りキャッシュではなく
+     * リクエストごとの**認可判定**であり、結果をキャッシュするとユーザーを跨いで再利用されうる。
+     *
+     * @param attachmentId Internal numeric attachment id. 内部数値の添付 ID。
+     * @param userId Internal numeric user id of the viewer. 閲覧者の内部数値ユーザー ID。
+     * @returns Attachment row when visible, otherwise null. 可視なら添付行、それ以外は null。
+     */
+    const getAttachmentForUser = async (attachmentId: number, userId: number): Promise<{ fileName: string; filePath: string; fileType: string | null; fileSize: number | null } | null> => {
+        const attachment = tables.attachment
+        if (!attachment) {
+            return null
+        }
+        const draftLabelJoinIds = await getDraftLabelJoinIds()
+        const DraftLabelRelation = aliasedTable(DailyReportHub_Label as unknown as Parameters<typeof aliasedTable>[0], "draft_label") as unknown as typeof DailyReportHub_Label
+
+        // `.top(1)` は `.select()` の直後でなければならない。drizzle-mssql は top() を
+        // db.select() が返す MsSqlSelectBuilder にしか定義しておらず、.from() 以降のクラスには
+        // 存在しない。誤った順序は型 (構造型 SelectChain が全段階に top を宣言) でも
+        // 単体テスト (モックが全段階で top を返す) でも検出されず、本番で TypeError になる。
+        const rows = await db
+            .select<{ fileName: string; filePath: string; fileType: string | null; fileSize: number | null }>({
+                fileName: attachment.fileName,
+                filePath: attachment.filePath,
+                fileType: attachment.fileType,
+                fileSize: attachment.fileSize,
+            })
+            .top(1)
+            .from(attachment)
+            .innerJoin(DailyReportHub, eq(DailyReportHub.id, attachment.hubId))
+            .leftJoin(DraftLabelRelation, and(eq(DraftLabelRelation.hubId, DailyReportHub.id), inArray(DraftLabelRelation.labelId, draftLabelJoinIds)))
+            .where(and(eq(attachment.id, attachmentId), isNull(DailyReportHub.deletedAt), or(eq(DailyReportHub.userId, userId), isNull(DraftLabelRelation.hubId))))
+
+        return rows[0] ?? null
+    }
+
+    /**
+     * Records that an attachment's backing object was confirmed missing.
+     * 添付ファイルの実体が消失していたことを記録する処理。
+     *
+     * 実配信で `not_found` を得たときに呼ぶ。次回描画で三値が `absent` になる。
+     * 記録の失敗は配信結果に影響させない (呼び出し側は await しない)。
+     *
+     * @param attachmentId Internal numeric attachment id. 内部数値の添付 ID。
+     */
+    const markAttachmentMissing = async (attachmentId: number): Promise<void> => {
+        const attachment = tables.attachment
+        if (!attachment) return
+        const now = new Date()
+        try {
+            await db.update(attachment).set({ objectCheckedAt: now, objectMissingAt: now, updatedAt: now }).where(eq(attachment.id, attachmentId))
+        } catch (error) {
+            logger.error("markAttachmentMissing failed", error)
+        }
+    }
+
+    /**
+     * Records that an attachment's backing object was confirmed present.
+     * 添付ファイルの実体が存在していたことを記録する処理。
+     *
+     * `markAttachmentMissing` と対にすること。消失記録が一方向だと、一時的な障害で
+     * 一度 `absent` が立った添付は UI がリンクを描画しなくなり (押しても 404 なので当然)、
+     * **利用者が再取得を発火させる手段そのものが消える**。実体が戻っても手動の
+     * 一括検証を回すまで復帰しない。配信が 200 で成功した時点で解除するのが唯一の
+     * 自動回復経路である。
+     *
+     * 記録の失敗は配信結果に影響させない (呼び出し側は await しない)。
+     *
+     * @param attachmentId Internal numeric attachment id. 内部数値の添付 ID。
+     */
+    const markAttachmentPresent = async (attachmentId: number): Promise<void> => {
+        const attachment = tables.attachment
+        if (!attachment) return
+        const now = new Date()
+        try {
+            await db.update(attachment).set({ objectCheckedAt: now, objectMissingAt: null, updatedAt: now }).where(eq(attachment.id, attachmentId))
+        } catch (error) {
+            logger.error("markAttachmentPresent failed", error)
         }
-        return null
     }
 
     /**
@@ -526,7 +747,7 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
         return sqlResultCache.getOrFetch<DailyReportDetail>({
             cacheKey,
             fetcher: async () => {
-                const draftLabelId = await getDraftLabelId()
+                const draftLabelJoinIds = await getDraftLabelJoinIds()
                 const DraftLabelRelation = aliasedTable(DailyReportHub_Label as unknown as Parameters<typeof aliasedTable>[0], "draft_label") as unknown as typeof DailyReportHub_Label
 
                 const rows = await applyExternalJoins(
@@ -543,7 +764,7 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
                 )
                     .leftJoin(DailyReportInternal, eq(DailyReportHub.id, DailyReportInternal.hubId))
                     .leftJoin(DailyReportUserStatus, and(eq(DailyReportHub.id, DailyReportUserStatus.hubId), eq(DailyReportUserStatus.userId, userId)))
-                    .leftJoin(DraftLabelRelation, and(eq(DraftLabelRelation.hubId, DailyReportHub.id), eq(DraftLabelRelation.labelId, draftLabelId ?? -1)))
+                    .leftJoin(DraftLabelRelation, and(eq(DraftLabelRelation.hubId, DailyReportHub.id), inArray(DraftLabelRelation.labelId, draftLabelJoinIds)))
                     .leftJoin(users, eq(DailyReportHub.userId, users.id))
                     .where(and(eq(DailyReportHub.businessDate, sql`${normalizedBusinessDate}`), isNull(DailyReportHub.deletedAt), or(eq(DailyReportHub.userId, userId), isNull(DraftLabelRelation.hubId))))
                     .orderBy(desc(DailyReportHub.id))
@@ -580,6 +801,9 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
                     .where(inArray(DailyReportCommentModel.hubId, hubIds))
                     .orderBy(asc(DailyReportCommentModel.createdAt))
 
+                // 添付も同じ流儀で一括取得する (日報ごとに引くと N+1 になる)
+                const attachmentsMap = await getAttachmentsByHubIds(hubIds)
+
                 const labelsMap = new Map<number, RawJsonLabel[]>()
                 const commentsMap = new Map<number, RawJsonComment[]>()
 
@@ -616,6 +840,7 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
                     return mapHubRecord(
                         {
                             ...row,
+                            attachments: attachmentsMap.get(hubId) ?? [],
                             labels: labelsMap.get(hubId) || [],
                             comments: commentsMap.get(hubId) || [],
                         },
@@ -633,6 +858,13 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
     /**
      * Retrieves a single daily report detail by ID with user-specific status and relations.
      * 指定した日報詳細を、ユーザー状態と関連データを含めて取得する。
+     *
+     * 可視性の述語は営業日一覧 (`getDailyReportsByBusinessDateByExternalId`) および
+     * `getAttachmentForUser` と同一に保つこと。3 経路のどれか 1 つだけ緩いと、
+     * 緩い経路がメタデータ (件名・本文・添付のファイル名やトークン) を渡してしまい、
+     * 「SQL 述語が唯一の認可境界」という不変条件が崩れる。
+     * 4 番目の経路である `fetchDailyReportIdsByUserId` だけは意図的に 1 つ緩い
+     * (返すのが ID・営業日・ソース種別のみのため)。詳細は同関数の docstring を参照。
      */
     const getDailyReportDetailById = async (reportHubId: number, userId: number, { forceRefresh = false, snapshot = false, ttlMsOverride }: SqlResultCacheQueryOptions = {}): Promise<DailyReportDetail | null> => {
         const cacheKey = `daily-report:detail:${reportHubId}:user:${userId}`
@@ -640,6 +872,9 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
         const results = (await sqlResultCache.getOrFetch<DailyReportDetail>({
             cacheKey,
             fetcher: async () => {
+                const draftLabelJoinIds = await getDraftLabelJoinIds()
+                const DraftLabelRelation = aliasedTable(DailyReportHub_Label as unknown as Parameters<typeof aliasedTable>[0], "draft_label") as unknown as typeof DailyReportHub_Label
+
                 const rows = await applyExternalJoins(
                     db
                         .select<HubQueryRow>({
@@ -654,8 +889,9 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
                 )
                     .leftJoin(DailyReportInternal, eq(DailyReportHub.id, DailyReportInternal.hubId))
                     .leftJoin(DailyReportUserStatus, and(eq(DailyReportHub.id, DailyReportUserStatus.hubId), eq(DailyReportUserStatus.userId, userId)))
+                    .leftJoin(DraftLabelRelation, and(eq(DraftLabelRelation.hubId, DailyReportHub.id), inArray(DraftLabelRelation.labelId, draftLabelJoinIds)))
                     .leftJoin(users, eq(DailyReportHub.userId, users.id))
-                    .where(and(eq(DailyReportHub.id, reportHubId), isNull(DailyReportHub.deletedAt)))
+                    .where(and(eq(DailyReportHub.id, reportHubId), isNull(DailyReportHub.deletedAt), or(eq(DailyReportHub.userId, userId), isNull(DraftLabelRelation.hubId))))
 
                 if (rows.length === 0) {
                     return []
@@ -687,6 +923,8 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
                     .where(eq(DailyReportCommentModel.hubId, hubId))
                     .orderBy(asc(DailyReportCommentModel.createdAt))
 
+                const attachmentsMap = await getAttachmentsByHubIds([hubId])
+
                 const labelsMapped = labels.map((l) => ({
                     id: l.id,
                     name: l.name,
@@ -705,6 +943,7 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
                     mapHubRecord(
                         {
                             ...rows[0],
+                            attachments: attachmentsMap.get(hubId) ?? [],
                             labels: labelsMapped,
                             comments: commentsMapped,
                         },
@@ -1072,6 +1311,8 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
                     isStarred: false,
                     labels: labels,
                     commentItems: [],
+                    // 新規作成直後の日報に添付は存在しない
+                    attachments: [],
                 }
             })
 
@@ -1092,8 +1333,9 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
 
             if (fullDetail) {
                 // 下書き判定
-                const draftLabelId = await getDraftLabelId()
-                const isDraft = draftLabelId ? fullDetail.labels.some((l) => l.id === draftLabelId) : false
+                // 判定は代表 ID ではなく下書きラベル**全体**で行う (2 つ目の下書き名を見落とさない)
+                const draftLabelIds = await getDraftLabelIds()
+                const isDraft = fullDetail.labels.some((l) => draftLabelIds.includes(l.id))
                 await publishToSseStream(
                     reportCreateMessageSchema.parse({
                         type: "report-create",
@@ -1230,8 +1472,9 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
         const fullDetail = await getDailyReportDetailById(reportHubId, userId, { forceRefresh: true })
         if (fullDetail) {
             // 下書き判定
-            const draftLabelId = await getDraftLabelId()
-            const isDraft = draftLabelId ? fullDetail.labels.some((l) => l.id === draftLabelId) : false
+            // 判定は代表 ID ではなく下書きラベル**全体**で行う (2 つ目の下書き名を見落とさない)
+            const draftLabelIds = await getDraftLabelIds()
+            const isDraft = fullDetail.labels.some((l) => draftLabelIds.includes(l.id))
             await publishToSseStream(
                 reportUpdateMessageSchema.parse({
                     type: "report-update",
@@ -1298,14 +1541,48 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
         return fullDetail ?? null
     }
 
+    /**
+     * Invalidates the read caches that carry hub-scoped data across every process.
+     * hub 単位のデータを載せている読み取りキャッシュを、全プロセス横断で無効化する処理。
+     *
+     * 用途: 通常の更新経路 (create / update / publish) を通らずに DB を書き換えた場合、
+     * 例えば外部システムからの一括取込。プロセス内 Map を消すだけでは稼働中の
+     * 別プロセス (別ワーカー・別コンテナ) のキャッシュが TTL まで stale のままになるため、
+     * Redis の epoch を進めて全プロセスのキャッシュ行を一斉に無効化する。
+     *
+     * `clearCache()` との違い: `clearCache()` が進める epoch は一覧 ID のものだけで、
+     * 詳細キャッシュ (`detail-epoch:<hubId>`) と営業日キャッシュ (`date-epoch:<date>`) は
+     * 進まない。日報本体に紐づくデータ (添付など) を書き換えたときはこちらを使うこと。
+     *
+     * @param hubIds Hub ids whose detail cache must be dropped. 詳細キャッシュを捨てる hub ID 群。
+     * @param businessDates Business dates (YYYY-MM-DD) whose list cache must be dropped. 一覧キャッシュを捨てる営業日群。
+     * @returns Nothing. なし。
+     */
+    const invalidateHubReadCaches = async (hubIds: readonly number[], businessDates: readonly string[]): Promise<void> => {
+        sqlResultCache.invalidatePrefix(DAILY_REPORT_BUSINESS_DATE_CACHE_PREFIX)
+        for (const hubId of new Set(hubIds)) {
+            sqlResultCache.invalidatePrefix(`daily-report:detail:${hubId}:user:`)
+            await incrementRedisEpoch(`${DAILY_REPORT_DETAIL_EPOCH_PREFIX}${hubId}`)
+        }
+        for (const businessDate of new Set(businessDates)) {
+            const normalized = normalizeBusinessDateKey(businessDate)
+            // 正規化できない値で epoch キーを作ると、誰も参照しないキーが増えるだけになる
+            if (!normalized) continue
+            await incrementRedisEpoch(`${DAILY_REPORT_DATE_EPOCH_PREFIX}${normalized}`)
+        }
+    }
+
     /**
      * Clears all server-side SQL result and user ID caches.
      * サーバー側のすべての SQL 結果キャッシュおよびユーザー ID キャッシュを全消去する。
+     *
+     * Redis で進めるのは一覧 ID の epoch のみ。詳細/営業日キャッシュも捨てたい場合は
+     * `invalidateHubReadCaches` を使うこと (このメソッドでは進まない)。
      */
     const clearCache = async (): Promise<void> => {
         sqlResultCache.clearAll()
         userIdCache.clear()
-        cachedDraftLabelId = null
+        cachedDraftLabelIds = null
         if (epochs) {
             await incrementRedisEpoch(DAILY_REPORT_IDS_EPOCH_KEY)
         }
@@ -1318,6 +1595,7 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
         streamMaxLen: DAILY_REPORT_SSE_STREAM_MAXLEN,
         // キャッシュクリア
         clearCache,
+        invalidateHubReadCaches,
         // ユーザー解決
         getUserIdByExternalId,
         // 参照系
@@ -1327,6 +1605,11 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
         getDailyReportDetailById,
         getDailyReportDetailByIdByExternalId,
         getDraftLabelId,
+        // 添付 (ハンドラーが認可判定と実体消失記録に使う)
+        getAttachmentsByHubIds,
+        getAttachmentForUser,
+        markAttachmentMissing,
+        markAttachmentPresent,
         // 更新系
         setStarStatus,
         setReadStatus,

package/src/server/test-helpers/handlers-config.ts

@@ -0,0 +1,142 @@
+/**
+ * Test fixture that assembles a minimal `DailyReportHandlersConfig`.
+ * 最小限の `DailyReportHandlersConfig` を組み立てるテスト用フィクスチャ。
+ *
+ * `handlers.ts` を対象にした spec がこれまで存在しなかったため、認証・サービス・
+ * 難読化・SSE リーダーのモック一式をここに集約する。各テストは必要な部分だけを上書きする。
+ *
+ * 本番コードからは import されない (テスト専用)。
+ */
+import type { DailyReportHandlersConfig } from "../handlers"
+import type { DailyReportAttachmentBytes, DailyReportAttachmentError, DailyReportIdCodec } from "../ports"
+import type { DailyReportService } from "../service"
+import type { DailyReportSseReader } from "../sse-reader"
+
+/** 既定の外部ユーザー ID (認証済みユーザーを表す)。 */
+export const TEST_EXTERNAL_USER_ID = "external-user"
+
+/** 既定の内部ユーザー ID。 */
+export const TEST_INTERNAL_USER_ID = 42
+
+/** テスト用の添付 ID コーデック。`A<id>` 形式で、ユーザー ID 用とは別空間であることを表す。 */
+export const testAttachmentCodec: DailyReportIdCodec = {
+    encode: (id) => `A${id}`,
+    decode: (token) => {
+        if (!token.startsWith("A")) return null
+        const value = Number(token.slice(1))
+        return Number.isInteger(value) ? value : null
+    },
+}
+
+/** `service.getAttachmentForUser` が返す行の形。 */
+export type TestAttachmentRow = { fileName: string; filePath: string; fileType: string | null; fileSize: number | null }
+
+/** フィクスチャの調整点。 */
+export type HandlersFixtureOptions = {
+    /** 認証結果。null を渡すと未認証を表す。 */
+    user?: { id: string } | null
+    /** 認証ポートが返す `Set-Cookie`。 */
+    cookie?: string
+    /** 外部 ID → 内部 ID の解決結果。 */
+    internalUserId?: number | null
+    /** 認可判定の結果。null なら不可視 (404 相当)。 */
+    attachment?: TestAttachmentRow | null
+    /** 読み取りポートの応答。 */
+    readResult?: DailyReportAttachmentBytes | DailyReportAttachmentError
+    /** ポートを未注入にする (縮退動作の検証用)。 */
+    omitPorts?: boolean
+    /** 添付の上限バイト数。 */
+    attachmentMaxBytes?: number
+    /** レート上限 (1 分あたり)。 */
+    attachmentRateLimitPerMinute?: number
+    /** 同時実行上限。 */
+    attachmentConcurrency?: number
+}
+
+/** 呼び出し記録。テストが副作用を検証するために使う。 */
+export type HandlersFixtureCalls = {
+    /** `service.getAttachmentForUser` が受け取った `(attachmentId, viewerUserId)`。 */
+    getAttachmentForUser: Array<[number, number]>
+    readAttachment: Array<{ filePath: string; maxBytes: number; head: boolean; principal?: string }>
+    markAttachmentMissing: number[]
+    markAttachmentPresent: number[]
+}
+
+/**
+ * Builds a handlers config plus the call log the assertions inspect.
+ * ハンドラー設定と、表明で参照する呼び出し記録を組み立てる処理。
+ *
+ * @param options Fixture adjustments. フィクスチャの調整点。
+ * @returns The config and its call log. 設定と呼び出し記録。
+ */
+export const makeHandlersFixture = (options: HandlersFixtureOptions = {}): { config: DailyReportHandlersConfig; calls: HandlersFixtureCalls } => {
+    const calls: HandlersFixtureCalls = { getAttachmentForUser: [], readAttachment: [], markAttachmentMissing: [], markAttachmentPresent: [] }
+
+    const user = options.user === undefined ? { id: TEST_EXTERNAL_USER_ID } : options.user
+    const internalUserId = options.internalUserId === undefined ? TEST_INTERNAL_USER_ID : options.internalUserId
+    const attachment = options.attachment === undefined ? null : options.attachment
+    const readResult: DailyReportAttachmentBytes | DailyReportAttachmentError = options.readResult ?? { ok: true, bytes: new Uint8Array(new ArrayBuffer(3)), contentType: null }
+
+    const service = {
+        getUserIdByExternalId: async () => internalUserId,
+        getAttachmentForUser: async (attachmentId: number, viewerUserId: number) => {
+            // 引数を記録する。記録しないと「閲覧者 ID を渡し忘れた」欠陥がテストに映らない
+            calls.getAttachmentForUser.push([attachmentId, viewerUserId])
+            return attachment
+        },
+        markAttachmentMissing: async (id: number) => {
+            calls.markAttachmentMissing.push(id)
+        },
+        markAttachmentPresent: async (id: number) => {
+            calls.markAttachmentPresent.push(id)
+        },
+    } as unknown as DailyReportService
+
+    const base: DailyReportHandlersConfig = {
+        authenticate: async () => ({ user: user ?? undefined, cookie: options.cookie }),
+        service,
+        encodeUserId: (id) => `ENC${id}`,
+        sseReader: { subscribe: () => () => undefined } as unknown as DailyReportSseReader,
+        streamKey: "test-stream",
+        attachmentMaxBytes: options.attachmentMaxBytes,
+        attachmentRateLimitPerMinute: options.attachmentRateLimitPerMinute,
+        attachmentConcurrency: options.attachmentConcurrency,
+    }
+
+    if (options.omitPorts) {
+        return { config: base, calls }
+    }
+
+    return {
+        config: {
+            ...base,
+            attachmentIdCodec: testAttachmentCodec,
+            readAttachment: async (filePath, opts) => {
+                calls.readAttachment.push({ filePath, ...opts })
+                // 本物の実装は head:true のとき本体を読まず長さ 0 のビューを返し、実サイズは `size` で申告する。
+                // フィクスチャが常に本体長を返すと、HEAD の Content-Length が 0 になる欠陥が観測できない
+                if (opts.head && readResult.ok) {
+                    return { ...readResult, bytes: new Uint8Array(new ArrayBuffer(0)), size: readResult.size ?? readResult.bytes.byteLength }
+                }
+                return readResult
+            },
+        },
+        calls,
+    }
+}
+
+/**
+ * Builds loader args for the attachment endpoint.
+ * 添付エンドポイント用の loader 引数を組み立てる処理。
+ *
+ * @param token Attachment token in the URL. URL 中の添付トークン。
+ * @param init Optional method / query / headers. メソッド・クエリ・ヘッダーの任意指定。
+ * @returns Loader args. loader 引数。
+ */
+export const makeAttachmentArgs = (token: string, init: { method?: string; query?: string; headers?: Record<string, string> } = {}) => ({
+    request: new Request(`http://localhost/daily_report/api/attachment/${encodeURIComponent(token)}${init.query ?? ""}`, {
+        method: init.method ?? "GET",
+        headers: init.headers,
+    }),
+    params: { token } as Record<string, string | undefined>,
+})