@aiquants/daily-report 0.6.2 → 0.7.0

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/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[]
 }
 
 /**