@aiquants/daily-report 0.7.0 → 0.8.0

package/src/server/service.ts

@@ -419,6 +419,45 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
         }))
     }
 
+    /**
+     * Fetches only the first page of report ids for time-to-first-render (uncached).
+     * 最初の描画までの時間専用に、ID 一覧の先頭ページだけを取得する内部処理 (キャッシュ無し)。
+     *
+     * `ids-stream` の新規接続でキャッシュミスした場合、全量クエリの確定を待たずに
+     * この軽量クエリ (TOP n・インデックス順で n 行走査した時点で打ち切り) の結果を
+     * 最初のチャンクとして送出する。可視性述語と並び順は全量クエリと完全同一。
+     * `.top(n)` は `.select()` の直後でなければならない (drizzle-mssql の構造的制約)。
+     *
+     * @param externalId External user id. 外部ユーザー ID。
+     * @param limit Page size. ページサイズ。
+     * @returns First-page items in stream order. ストリーム順の先頭ページ。
+     */
+    const getDailyReportIdsFirstPageByExternalId = async (externalId: string, limit: number): Promise<DailyReportItem[]> => {
+        const userId = await getUserIdByExternalId(externalId)
+        if (!userId) {
+            return []
+        }
+        const DraftLabelRelation = aliasedTable(DailyReportHub_Label as unknown as Parameters<typeof aliasedTable>[0], "draft_label") as unknown as typeof DailyReportHub_Label
+        const draftLabelJoinIds = await getDraftLabelJoinIds()
+
+        const result = await db
+            .select<{ reportHubId: number; businessDate: Date | string | null; sourceType: string }>({
+                reportHubId: DailyReportHub.id,
+                businessDate: DailyReportHub.businessDate,
+                sourceType: DailyReportHub.sourceType,
+            })
+            .top(limit)
+            .from(DailyReportHub)
+            .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))
+
+        return result.map((item) => ({
+            ...item,
+            businessDate: formatDateValue(item.businessDate, "YYYY-MM-DD"),
+        }))
+    }
+
     /**
      * Fetches daily report details for the provided business date.
      * 指定した営業日の日報詳細を取得する内部処理。
@@ -1600,6 +1639,7 @@ export function createDailyReportService(config: DailyReportServiceConfig) {
         getUserIdByExternalId,
         // 参照系
         getDailyReportIdsByExternalId,
+        getDailyReportIdsFirstPageByExternalId,
         getDailyReportsByBusinessDate,
         getDailyReportsByBusinessDateByExternalId,
         getDailyReportDetailById,

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

@@ -51,6 +51,14 @@ export type HandlersFixtureOptions = {
     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 }>
 }
 
 /** 呼び出し記録。テストが副作用を検証するために使う。 */
@@ -60,6 +68,10 @@ export type HandlersFixtureCalls = {
     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]>
 }
 
 /**
@@ -70,7 +82,7 @@ export type HandlersFixtureCalls = {
  * @returns The config and its call log. 設定と呼び出し記録。
  */
 export const makeHandlersFixture = (options: HandlersFixtureOptions = {}): { config: DailyReportHandlersConfig; calls: HandlersFixtureCalls } => {
-    const calls: HandlersFixtureCalls = { getAttachmentForUser: [], readAttachment: [], markAttachmentMissing: [], markAttachmentPresent: [] }
+    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
@@ -79,6 +91,17 @@ export const makeHandlersFixture = (options: HandlersFixtureOptions = {}): { con
 
     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])
@@ -133,6 +156,22 @@ export const makeHandlersFixture = (options: HandlersFixtureOptions = {}): { con
  * @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",

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
+}