@aiquants/daily-report 0.6.2 → 0.8.0

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

@@ -0,0 +1,181 @@
+/**
+ * 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
+    /** ids ストリームが返すアイテム一覧 (ストリーム順で渡す)。 */
+    idsStreamItems?: Array<{ reportHubId: number; businessDate: string | null; sourceType?: string }>
+    /** ids 取得 (全量・先頭ページの両方) を失敗させるエラー。 */
+    idsStreamError?: Error
+    /** 全量クエリの解決を保留にする Promise (高速先頭ページ経路の検証用)。 */
+    idsStreamFullGate?: Promise<void>
+    /** 先頭ページの結果を上書きする (既定は idsStreamItems の先頭スライス)。 */
+    idsStreamFirstPageItems?: Array<{ reportHubId: number; businessDate: string | null; sourceType?: string }>
+}
+
+/** 呼び出し記録。テストが副作用を検証するために使う。 */
+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[]
+    /** `service.getDailyReportIdsByExternalId` が受け取った `(externalId, forceRefresh)`。 */
+    getDailyReportIds: Array<[string, boolean]>
+    /** `service.getDailyReportIdsFirstPageByExternalId` が受け取った `(externalId, limit)`。 */
+    getDailyReportIdsFirstPage: Array<[string, 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: [], getDailyReportIds: [], getDailyReportIdsFirstPage: [] }
+
+    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,
+        getDailyReportIdsByExternalId: async (externalId: string, opts?: { forceRefresh?: boolean }) => {
+            calls.getDailyReportIds.push([externalId, opts?.forceRefresh ?? false])
+            if (options.idsStreamError) throw options.idsStreamError
+            if (options.idsStreamFullGate) await options.idsStreamFullGate
+            return options.idsStreamItems ?? []
+        },
+        getDailyReportIdsFirstPageByExternalId: async (externalId: string, limit: number) => {
+            calls.getDailyReportIdsFirstPage.push([externalId, limit])
+            if (options.idsStreamError) throw options.idsStreamError
+            return options.idsStreamFirstPageItems ?? (options.idsStreamItems ?? []).slice(0, limit)
+        },
+        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 引数。
+ */
+/**
+ * Builds loader args for the `:endpoint` API router.
+ * `:endpoint` API ルーター用の loader 引数を組み立てる処理。
+ *
+ * @param endpoint Endpoint segment (e.g. "ids-stream"). エンドポイントセグメント。
+ * @param init Optional method / query / signal. メソッド・クエリ・中断シグナルの任意指定。
+ * @returns Loader args. loader 引数。
+ */
+export const makeApiArgs = (endpoint: string, init: { method?: string; query?: string; signal?: AbortSignal } = {}) => ({
+    request: new Request(`http://localhost/daily_report/api/${endpoint}${init.query ?? ""}`, {
+        method: init.method ?? "GET",
+        signal: init.signal ?? undefined,
+    }),
+    params: { endpoint } as Record<string, string | undefined>,
+})
+
+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>,
+})

package/src/server.ts

@@ -5,7 +5,7 @@
 import { createEpochStore, SqlResultCache } from "./server/cache"
 import type { DailyReportExternalSource } from "./server/external-source"
 import { createDailyReportHandlers } from "./server/handlers"
-import type { DailyReportAuthenticate } from "./server/ports"
+import type { DailyReportAuthenticate, DailyReportReadAttachment } from "./server/ports"
 import { createDailyReportService, type DailyReportServiceConfig } from "./server/service"
 import { DailyReportSseReader } from "./server/sse-reader"
 
@@ -24,6 +24,14 @@ export * from "./server/sse-reader"
 export type DailyReportServerConfig = Omit<DailyReportServiceConfig, "cache" | "epochs"> & {
     /** リクエスト認証ポート。 */
     authenticate: DailyReportAuthenticate
+    /** 添付ファイル読み取りポート。未注入なら添付エンドポイントは常に 404。 */
+    readAttachment?: DailyReportReadAttachment
+    /** 添付ファイルの最大バイト数 (既定 32 MiB)。サービス側のワイヤ上限より低く保つこと。 */
+    attachmentMaxBytes?: number
+    /** 添付エンドポイントの 1 分あたり呼び出し上限 (ユーザー単位・既定 60)。 */
+    attachmentRateLimitPerMinute?: number
+    /** 添付読み取りの同時実行上限 (プロセス単位・既定 4)。 */
+    attachmentConcurrency?: number
     /** 未ログイン時のリダイレクト先 (index.loader 用、既定 "/auth/login")。 */
     loginRedirectPath?: string
     /** SQL 結果キャッシュの既定 TTL (既定 60,000ms)。 */
@@ -57,10 +65,17 @@ export function createDailyReportServer(config: DailyReportServerConfig) {
         logger: config.logger,
     })
 
+    // ❗ この呼び出しはスプレッドではなく明示列挙である。新しいポートをここへ足し忘れると
+    //    アプリが注入しても黙って捨てられ、添付エンドポイントは永久に 404 を返す。
     const handlers = createDailyReportHandlers({
         authenticate: config.authenticate,
         service,
         encodeUserId: config.encodeUserId,
+        attachmentIdCodec: config.attachmentIdCodec,
+        readAttachment: config.readAttachment,
+        attachmentMaxBytes: config.attachmentMaxBytes,
+        attachmentRateLimitPerMinute: config.attachmentRateLimitPerMinute,
+        attachmentConcurrency: config.attachmentConcurrency,
         redis: config.redis,
         sseReader,
         streamKey: service.streamKey,

package/src/shared/ids-stream.ts

@@ -0,0 +1,92 @@
+/**
+ * Wire contract and ordering helpers for the daily-report ids NDJSON stream.
+ * 日報 ID 一覧 NDJSON ストリームのワイヤ契約と並び順ヘルパー。
+ *
+ * サーバーは `GET {apiBasePath}/ids-stream` で 1 行 1 JSON の NDJSON を返す。
+ * 行は原則 {@link DailyReportIdsStreamChunkLine} で、送出中に予期しない失敗が
+ * 起きた場合のみ {@link DailyReportIdsStreamErrorLine} を 1 行流して正常クローズする
+ * (クライアントは「isLast 無しで終端」を再開シグナルとして扱う)。
+ *
+ * 並び順は SQL の `ORDER BY business_date DESC, id DESC` (MSSQL の DESC は NULL を
+ * 末尾に置く) と完全一致させる。カーソル再開はこの全順序に対する「厳密に後」の
+ * 位置からのスライスとして定義する。
+ */
+import type { DailyReportItem } from "./types"
+
+/** ストリーム再開カーソル。直前チャンク末尾アイテムの並び順キー。 */
+export type DailyReportIdsStreamCursor = {
+    /** 営業日 (YYYY-MM-DD)。null は「営業日なし領域」(並び順の末尾) を表す。 */
+    businessDate: string | null
+    /** 日報 Hub ID。 */
+    reportHubId: number
+}
+
+/** データを運ぶ NDJSON 行。 */
+export type DailyReportIdsStreamChunkLine = {
+    /** このチャンクのアイテム群 (並び順どおり)。 */
+    items: DailyReportItem[]
+    /** 次チャンクの再開カーソル。最終チャンクでは null。 */
+    nextCursor: DailyReportIdsStreamCursor | null
+    /** これが最終チャンクかどうか。 */
+    isLast: boolean
+    /** 全体件数。接続ごとの先頭行にのみ載る。 */
+    total?: number
+}
+
+/** サーバー側の予期しない失敗を伝える NDJSON 行 (内部情報は含めない)。 */
+export type DailyReportIdsStreamErrorLine = {
+    error: string
+}
+
+/** NDJSON 1 行のユニオン。 */
+export type DailyReportIdsStreamLine = DailyReportIdsStreamChunkLine | DailyReportIdsStreamErrorLine
+
+/**
+ * Type guard for chunk lines (anything else is treated as an error line).
+ * チャンク行の型ガード (それ以外はエラー行として扱う)。
+ *
+ * @param line Parsed NDJSON line. パース済みの NDJSON 行。
+ * @returns True when the line carries items. アイテムを運ぶ行なら true。
+ */
+export const isIdsStreamChunkLine = (line: unknown): line is DailyReportIdsStreamChunkLine => {
+    return typeof line === "object" && line !== null && Array.isArray((line as { items?: unknown }).items)
+}
+
+/**
+ * Total order of the ids stream: businessDate DESC (NULL last), then id DESC.
+ * ids ストリームの全順序。営業日降順 (NULL は末尾)、同日内は ID 降順。
+ *
+ * MSSQL の `ORDER BY business_date DESC, id DESC` と一致させることが唯一の存在理由。
+ * 営業日は正規化済みの `YYYY-MM-DD` 文字列なので辞書順比較 = 時系列比較になる。
+ *
+ * @param a Left key. 左辺キー。
+ * @param b Right key. 右辺キー。
+ * @returns Negative when `a` streams before `b`. `a` が先に流れるなら負値。
+ */
+export const compareIdsStreamOrder = (a: DailyReportIdsStreamCursor, b: DailyReportIdsStreamCursor): number => {
+    if (a.businessDate !== b.businessDate) {
+        // null 営業日は並び順の末尾 (MSSQL DESC の NULL 末尾挙動へ揃える)
+        if (a.businessDate === null) return 1
+        if (b.businessDate === null) return -1
+        return a.businessDate > b.businessDate ? -1 : 1
+    }
+    return b.reportHubId - a.reportHubId
+}
+
+/**
+ * Finds the first index that streams strictly after the cursor.
+ * カーソルより厳密に後ろへ並ぶ最初のインデックスを求める処理。
+ *
+ * 配列は必ずストリーム順 (SQL の ORDER BY) で渡されるが、比較器とのズレが
+ * あっても壊れない線形走査で決定する (件数は高々数万・再開時のみの実行)。
+ * 該当なし (カーソルが末尾以降) は `items.length` を返し、空チャンク +
+ * `isLast: true` の正常終端に落ちる。
+ *
+ * @param items Stream-ordered items. ストリーム順のアイテム配列。
+ * @param cursor Resume cursor. 再開カーソル。
+ * @returns Index to resume emission from. 送出を再開するインデックス。
+ */
+export const findIdsStreamResumeIndex = (items: readonly DailyReportItem[], cursor: DailyReportIdsStreamCursor): number => {
+    const index = items.findIndex((item) => compareIdsStreamOrder({ businessDate: item.businessDate, reportHubId: item.reportHubId }, cursor) > 0)
+    return index === -1 ? items.length : index
+}

package/src/shared/sse-schema.spec.ts

@@ -0,0 +1,50 @@
+/**
+ * Wire-compatibility tests for the SSE detail schema.
+ * SSE 詳細スキーマのワイヤ互換テスト。
+ *
+ * SSE の実体は永続 Redis Stream であり、配備をまたいで**旧形式のエントリが残る**。
+ * 共有リーダーはプロセス起動時にストリーム先頭から再生し、再接続クライアントの
+ * catch-up も同じエントリを読み直す。したがって受信側スキーマに既定値なしの
+ * 必須キーを足すと、そのキーを持たない配備前のエントリが fail-closed で全て捨てられ、
+ * 再接続タブへ更新が永久に届かなくなる。ここではその回帰を防ぐ。
+ */
+import { describe, expect, it } from "vitest"
+import { dailyReportDetailSchema, dailyReportSseMessageSchema } from "./sse-schema"
+
+/** 添付機能を入れる前に publish された `report-update` エントリ (attachments キーを持たない)。 */
+const legacyDetail = {
+    reportHubId: 12,
+    interviewers: [],
+    comments: [],
+    isRead: false,
+    isStarred: false,
+    labels: [],
+    commentItems: [],
+}
+
+describe("dailyReportDetailSchema / 旧形式エントリの受理", () => {
+    it("attachments キーが無い旧ペイロードを空配列として受理する", () => {
+        const parsed = dailyReportDetailSchema.parse(legacyDetail)
+        expect(parsed.attachments).toEqual([])
+    })
+
+    it("Stream に残る旧 report-update メッセージを捨てない", () => {
+        const result = dailyReportSseMessageSchema.safeParse({ type: "report-update", reportHubId: 12, report: legacyDetail, clientTempId: "c1" })
+        expect(result.success).toBe(true)
+    })
+
+    it("新形式の attachments はそのまま通す", () => {
+        const parsed = dailyReportDetailSchema.parse({
+            ...legacyDetail,
+            attachments: [{ id: "TOK", fileName: "a.png", fileType: "image/png", fileSize: 3, createdAt: null, state: "present" }],
+        })
+        expect(parsed.attachments).toHaveLength(1)
+        expect(parsed.attachments[0].state).toBe("present")
+    })
+
+    it("attachments の要素が壊れている場合は拒否する (既定値で握り潰さない)", () => {
+        // 欠損キーの救済と「不正な値の受理」は別物。後者は fail-closed のままにする
+        const result = dailyReportDetailSchema.safeParse({ ...legacyDetail, attachments: [{ id: "TOK", state: "bogus" }] })
+        expect(result.success).toBe(false)
+    })
+})

package/src/shared/sse-schema.ts

@@ -33,6 +33,25 @@ export const dailyReportCommentItemSchema = z.object({
     isMine: z.boolean(),
 })
 
+/**
+ * 添付ファイル 1 件のスキーマ。
+ *
+ * 周囲のフィールドは `.nullish()` だが、ここは意図して `.nullable()` を使う。
+ * `.nullish()` は推論キーを任意 (`?`) にするため、`types.ts` 側の必須 `fileType: string | null`
+ * へ代入できず、ファイル末尾の `_AssertDetailCompat` が `never` に落ちてコンパイルエラーになる。
+ * 既存の `.nullish()` フィールドはいずれも `types.ts` 側が `?` 付きの任意キーとペアになっており、
+ * 「`.nullish()` ↔ 任意キー」「`.nullable()` ↔ 必須 `| null`」の対応で揃っている。
+ * `| undefined` を混ぜないことは、詳細型を消費する DuckDB ステージ行の要請でもある。
+ */
+export const dailyReportAttachmentItemSchema = z.object({
+    id: z.string(),
+    fileName: z.string(),
+    fileType: z.string().nullable(),
+    fileSize: z.number().nullable(),
+    createdAt: z.string().nullable(),
+    state: z.enum(["present", "absent", "unknown"]),
+})
+
 export const dailyReportDetailSchema = z.object({
     reportHubId: z.number(),
     date: z.string().nullish(),
@@ -56,6 +75,14 @@ export const dailyReportDetailSchema = z.object({
     isStarred: z.boolean(),
     labels: z.array(dailyReportLabelDefSchema),
     commentItems: z.array(dailyReportCommentItemSchema),
+    // ❗ `.default([])` は必須。SSE の実体は永続 Redis Stream (MAXLEN 保持) であり、
+    // 配備をまたいで**旧形式のエントリが残る**。共有リーダーはプロセス起動時に先頭から
+    // 再生し、再接続クライアントの catch-up も同じエントリを読み直すため、
+    // このキーを必須にすると添付機能を入れる前に publish された全エントリが
+    // fail-closed で捨てられ、再接続タブへ更新が永久に届かなくなる。
+    // 送信側の詰め忘れ検知は types.ts の必須フィールドと `_AssertDetailCompat`
+    // (出力型は既定値適用後なので必須のまま) が担っており、ここを緩めても失われない。
+    attachments: z.array(dailyReportAttachmentItemSchema).default([]),
 })
 
 // --- SSE メッセージスキーマ（8種） ---

package/src/shared/types.ts

@@ -30,6 +30,32 @@ export type DailyReportLabelDef = {
     color?: string | null
 }
 
+/**
+ * Verification state of an attachment's backing object.
+ * 添付ファイルの実体の検証状態。
+ *
+ * 三値にする理由: 存在確認そのものが失敗した場合 (権限・通信障害) を偽の真偽で埋めないため。
+ * `unknown` は「まだ検証していない / 検証できなかった」であり、`absent` (消失を確認した) とは異なる。
+ */
+export type DailyReportAttachmentState = "present" | "absent" | "unknown"
+
+/**
+ * One attachment as exposed to the client.
+ * クライアントへ公開する添付ファイル 1 件。
+ *
+ * `id` は難読化トークンであり内部数値 ID ではない。ストレージパス (`filePath`) は
+ * サーバー内部にとどまり、この型には現れない。
+ * `fileSize` / `createdAt` が null になり得るのは、サイズや作成日時を報告しない取込元があるため。
+ */
+export type DailyReportAttachmentSummary = {
+    id: string
+    fileName: string
+    fileType: string | null
+    fileSize: number | null
+    createdAt: string | null
+    state: DailyReportAttachmentState
+}
+
 /** リレーショナルコメント 1 件。`userId` は難読化済み文字列。 */
 export type DailyReportCommentItem = {
     id: number
@@ -64,6 +90,11 @@ export type DailyReportDetail = {
     isStarred: boolean
     labels: DailyReportLabelDef[]
     commentItems: DailyReportCommentItem[]
+    /**
+     * 添付ファイル一覧。必須にしているのは詰め忘れをコンパイル時に落とすため。
+     * 任意にすると `?? []` で黙って空配列になり、SSE 経由でクライアントの既存一覧を空で上書きする。
+     */
+    attachments: DailyReportAttachmentSummary[]
 }
 
 /**