@aiquants/daily-report 0.6.2 → 0.8.0

package/src/server/ports.ts

@@ -66,3 +66,77 @@ export type DailyReportResolveUserId = (externalUserId: string) => Promise<numbe
  * 内部数値ユーザー ID をクライアント公開用に難読化するポート。
  */
 export type DailyReportEncodeUserId = (id: number) => string
+
+/**
+ * Reversible obfuscation codec for an internal numeric id exposed to clients.
+ * クライアントへ公開する内部数値 ID の可逆難読化コーデック。
+ *
+ * これは難読化であって認可ではない。トークンを能力 (capability) として扱ってはならず、
+ * 認可は必ずサーバー側の述語で行うこと。ID 空間を混ぜないため、リソース種別ごとに
+ * 別インスタンス (別 alphabet 等) を注入することを推奨する。
+ */
+export type DailyReportIdCodec = {
+    /** 内部数値 ID をトークンへ変換する。 */
+    encode: (id: number) => string
+    /** トークンを内部数値 ID へ戻す。復号できない場合は null。 */
+    decode: (token: string) => number | null
+}
+
+/**
+ * Failure kinds a caller maps onto HTTP statuses.
+ * 呼び出し側が HTTP ステータスへ写像する失敗種別。
+ *
+ * - `not_found`: 実体が存在しない (消失・未正規化 URI)
+ * - `denied`: ストレージ側で拒否された (サンドボックス外・ACL)
+ * - `too_large`: 上限超過 (事前サイズ判定またはワイヤ上限)
+ * - `invalid_path`: 受け入れないスキーム・不正なパス (データ不備)
+ * - `unavailable`: ストレージサービスへ到達できない・締め切り超過
+ */
+export type DailyReportAttachmentFailure = "not_found" | "denied" | "too_large" | "invalid_path" | "unavailable"
+
+/** 添付ファイル読み取りの成功結果。 */
+export type DailyReportAttachmentBytes = {
+    ok: true
+    /**
+     * Byte view backed by an `ArrayBuffer`.
+     * `ArrayBuffer` を裏に持つバイトビュー。
+     *
+     * 素の `Uint8Array` と書くと `Uint8Array<ArrayBufferLike>` へ広がり `BodyInit` へ代入できない
+     * (TypeScript 5.7 以降の既定型引数)。`Response` のボディへそのまま渡すため narrow 型で受ける。
+     * `head` が true の呼び出しでは長さ 0 のビューを返してよい (実サイズは `size` で申告する)。
+     */
+    bytes: Uint8Array<ArrayBuffer>
+    /** バックエンドが申告した MIME 型。判定できない場合は null。 */
+    contentType?: string | null
+    /**
+     * Entity size in bytes, independent of how many bytes `bytes` actually holds.
+     * 実体のバイト数。`bytes` が実際に保持している長さとは独立に申告する値。
+     *
+     * HEAD 応答の `Content-Length` は同じ URI への GET が返す値と一致しなければならない
+     * (RFC 9110 §9.3.2)。`head` が true の呼び出しは本体を読まないため `bytes` は空になるので、
+     * ここで実サイズを申告しないと HEAD が常に `Content-Length: 0` を返してしまう。
+     * 申告できない場合は省略してよく、そのとき呼び出し側は `bytes.byteLength` を使う。
+     */
+    size?: number
+}
+
+/** 添付ファイル読み取りの失敗結果。 */
+export type DailyReportAttachmentError = {
+    ok: false
+    reason: DailyReportAttachmentFailure
+    /** 診断ログ用の生のストレージエラーコード。HTTP ステータスの決定には使わない。 */
+    code?: string
+}
+
+/**
+ * Reads attachment bytes from the host application's storage backend.
+ * ホストアプリのストレージバックエンドから添付ファイルのバイト列を読み取るポート。
+ *
+ * `filePath` はサーバー内部にとどまり、クライアントへは決して渡らない。
+ * 失敗は種別付きで返すこと (例外を投げない・単一の null へ潰さない)。
+ * 種別を潰すと「実体が消えた」「上限超過」「サービス停止」が運用上区別できなくなる。
+ *
+ * `head` が true のときは実体を読まずメタデータのみ取得する。HEAD 要求で本体を読んで
+ * 捨てると、認証済み呼び出し元が任意に転送量とレイテンシを増幅できる経路になる。
+ */
+export type DailyReportReadAttachment = (filePath: string, options: { maxBytes: number; head: boolean; principal?: string }) => Promise<DailyReportAttachmentBytes | DailyReportAttachmentError>

package/src/server/schema.ts

@@ -6,7 +6,7 @@
  * 新規プロジェクトは `defineDailyReportSchema()` で同一構造のテーブル定義を生成できる。
  */
 import { desc, sql } from "drizzle-orm"
-import { type AnyMsSqlColumn, bigint, bit, date, datetime2, foreignKey, index, int, mssqlSchema, nvarchar, primaryKey } from "drizzle-orm/mssql-core"
+import { type AnyMsSqlColumn, bigint, bit, date, datetime2, foreignKey, index, int, mssqlSchema, nvarchar, primaryKey, uniqueIndex } from "drizzle-orm/mssql-core"
 
 /** 注入する外部ユーザーテーブルの最小形 (id / display_name)。 */
 export type DailyReportUserTable = { id: AnyMsSqlColumn; displayName: AnyMsSqlColumn }
@@ -85,19 +85,50 @@ export type DailyReportUserStatusTable = {
     updatedBy: AnyMsSqlColumn
 }
 
-/** サービスへ注入するテーブル一式 (アプリ既存モデルまたは本ファクトリ生成物)。 */
+/**
+ * DailyReportAttachment テーブルの構造形。
+ *
+ * `uploadedBy` は外部取込ソース由来の行に投稿者が存在しないため NULL 許容。
+ * `sourceKey` は取込の冪等 upsert の自然キー。
+ * `objectCheckedAt` / `objectMissingAt` から実体存在の三値 (unknown / present / absent) を導出する。
+ */
+export type DailyReportAttachmentTable = {
+    id: AnyMsSqlColumn
+    hubId: AnyMsSqlColumn
+    uploadedBy: AnyMsSqlColumn
+    sourceKey: AnyMsSqlColumn
+    fileName: AnyMsSqlColumn
+    filePath: AnyMsSqlColumn
+    fileType: AnyMsSqlColumn
+    fileSize: AnyMsSqlColumn
+    objectCheckedAt: AnyMsSqlColumn
+    objectMissingAt: AnyMsSqlColumn
+    createdAt: AnyMsSqlColumn
+    createdBy: AnyMsSqlColumn
+    updatedAt: AnyMsSqlColumn
+    updatedBy: AnyMsSqlColumn
+}
+
+/**
+ * サービスへ注入するテーブル一式 (アプリ既存モデルまたは本ファクトリ生成物)。
+ *
+ * `attachment` のみ任意。添付テーブルを持たない消費アプリでも本パッケージを使えるようにするため。
+ * 未注入時は詳細の `attachments` が常に空配列になり、添付エンドポイントは全トークンで 404 を返す
+ * (意図した縮退動作)。
+ */
 export type DailyReportTables = {
     hub: DailyReportHubTable
     internal: DailyReportInternalTable
     comment: DailyReportCommentTable
+    attachment?: DailyReportAttachmentTable
     label: DailyReportLabelTable
     hubLabel: DailyReportHubLabelTable
     userStatus: DailyReportUserStatusTable
 }
 
 /**
- * Generic factory: build the six daily-report tables under an arbitrary schema name.
- * 任意のスキーマ名の下に日報 6 テーブルを生成する汎用ファクトリ。
+ * Generic factory: build the seven daily-report tables under an arbitrary schema name.
+ * 任意のスキーマ名の下に日報 7 テーブルを生成する汎用ファクトリ。
  *
  * 制約・索引名は `${schemaName}_<Table>_...` 規約で生成する。
  * ユーザーテーブルへの FK は注入された `userTable` を参照する。
@@ -262,5 +293,49 @@ export function defineDailyReportSchema<S extends string>(schemaName: S, opts: {
         ],
     )
 
-    return { hub, internal, comment, label, hubLabel, userStatus } satisfies DailyReportTables
+    const attachment = s.table(
+        "DailyReportAttachment",
+        {
+            id: bigint("id", { mode: "number" }).identity().notNull(),
+            hubId: bigint("hub_id", { mode: "number" }).notNull(),
+            // 外部取込ソース由来の行には投稿者が存在しないため NULL 許容
+            uploadedBy: bigint("uploaded_by", { mode: "number" }),
+            // 取込の冪等 upsert の自然キー。`<source>:<external-id>` 形式を推奨 (値の規約は消費アプリが決める)
+            sourceKey: nvarchar("source_key", { length: 200 }).notNull(),
+            fileName: nvarchar("file_name", { length: 255 }).notNull(),
+            // ストレージ URI。受け入れるのは `gcs://` のみ (取込側で表明・読み取り側で再検証)
+            filePath: nvarchar("file_path", { length: "max" }).notNull(),
+            fileType: nvarchar("file_type", { length: 100 }),
+            fileSize: bigint("file_size", { mode: "number" }),
+            // 実体存在の三値をこの 2 列から導出する:
+            //   objectCheckedAt が null      -> unknown (未検証)
+            //   objectMissingAt が非 null    -> absent  (消失を確認)
+            //   上記以外                      -> present (実在を確認)
+            objectCheckedAt: datetime2("object_checked_at"),
+            objectMissingAt: datetime2("object_missing_at"),
+            createdAt: datetime2("created_at").notNull(),
+            createdBy: nvarchar("created_by", { length: 50 }).notNull(),
+            updatedAt: datetime2("updated_at").notNull(),
+            updatedBy: nvarchar("updated_by", { length: 50 }).notNull(),
+        },
+        (table) => [
+            primaryKey({ name: `${schemaName}_DailyReportAttachment_pk`, columns: [table.id] }),
+            foreignKey({
+                name: `${schemaName}_DailyReportAttachment_hub_id_fk`,
+                columns: [table.hubId],
+                foreignColumns: [hub.id],
+            }),
+            foreignKey({
+                name: `${schemaName}_DailyReportAttachment_uploaded_by_fk`,
+                columns: [table.uploadedBy],
+                foreignColumns: [users.id],
+            }),
+            // 取込の冪等性を DB 側で担保する
+            uniqueIndex(`${schemaName}_DailyReportAttachment_source_unique`).on(table.hubId, table.sourceKey),
+            // 一括取得 (hub_id IN (...) ORDER BY created_at) を被覆する
+            index(`${schemaName}_DailyReportAttachment_hub_id_index`).on(table.hubId, table.createdAt),
+        ],
+    )
+
+    return { hub, internal, comment, attachment, label, hubLabel, userStatus } satisfies DailyReportTables
 }

package/src/server/service.spec.ts

@@ -1,4 +1,5 @@
-import { bigint, mssqlSchema, nvarchar, primaryKey } from "drizzle-orm/mssql-core"
+import type { SQL } from "drizzle-orm"
+import { bigint, MsSqlDialect, mssqlSchema, nvarchar, primaryKey } from "drizzle-orm/mssql-core"
 import { describe, expect, it } from "vitest"
 import { createEpochStore, SqlResultCache } from "./cache"
 import { defineDailyReportSchema } from "./schema"
@@ -13,17 +14,92 @@ import { createDailyReportService, type DailyReportDb, type DailyReportHubRow }
 const testUsers = mssqlSchema("test").table("Users", { id: bigint("id", { mode: "number" }).notNull(), displayName: nvarchar("display_name", { length: 100 }) }, (t) => [primaryKey({ columns: [t.id] })])
 const tables = defineDailyReportSchema("test", { userTable: testUsers })
 
-/** getDailyReportsByBusinessDate 経路 (select→from→leftJoin→leftJoin→where→orderBy) だけを満たす最小モック。 */
-const makeDb = (rows: unknown[]): DailyReportDb => {
-    const chain = {
-        from: () => chain,
-        innerJoin: () => chain,
-        leftJoin: () => chain,
-        where: () => chain,
-        top: () => chain,
-        orderBy: () => Promise.resolve(rows),
+/** 本物の方言。`where` に渡された式を実際の SQL 文字列へ落として表明するために使う。 */
+const dialect = new MsSqlDialect()
+
+/** 1 本のクエリについてモックが記録した内容。 */
+type RecordedQuery = {
+    /** `where` に渡された式を実 SQL へ落としたもの。未指定なら null。 */
+    whereSql: string | null
+    /**
+     * `where` の束縛値。
+     *
+     * SQL 文字列だけでは**認可の中身を検証できない**。drizzle は値をすべて `@parN` へ落とすため、
+     * 文字列は「どのカラムをどう結んだか」しか含まない。閲覧者 ID と添付 ID の取り違えは
+     * ここを見なければ 1 件も検出できない。
+     */
+    whereParams: unknown[]
+    /** `leftJoin` された回数。 */
+    leftJoins: number
+    /** `leftJoin` の ON 条件に載った束縛値 (下書きラベル ID はここに来る)。 */
+    joinParams: unknown[]
+}
+
+/** `update(...).set(...).where(...)` について記録した内容。 */
+type RecordedUpdate = {
+    /** `set` に渡された更新内容。 */
+    set: Record<string, unknown>
+    /** `where` の束縛値。 */
+    whereParams: unknown[]
+}
+
+/**
+ * Minimal db mock that also records the SQL each query would emit.
+ * 各クエリが実際に生成する SQL を記録もする最小の db モック。
+ *
+ * チェーンは thenable にしてある。`.where()` で終わるクエリ (認可判定の
+ * `getAttachmentForUser` や `getDraftLabelId`) を `orderBy` 前提のモックで受けると
+ * チェーンオブジェクト自身が await の結果になり、分割代入が TypeError で落ちる。
+ * それを避けるためにモックを「どの段でも解決できる」形にしている。
+ *
+ * @param rows Rows every query resolves to. すべてのクエリが返す行。
+ * @returns The db mock and the per-query recordings. db モックとクエリごとの記録。
+ */
+const makeDb = (rows: unknown[]): { db: DailyReportDb; queries: RecordedQuery[]; updates: RecordedUpdate[] } => {
+    const queries: RecordedQuery[] = []
+    const updates: RecordedUpdate[] = []
+    const select = () => {
+        const recorded: RecordedQuery = { whereSql: null, whereParams: [], leftJoins: 0, joinParams: [] }
+        queries.push(recorded)
+        const chain: Record<string, unknown> = {
+            from: () => chain,
+            innerJoin: () => chain,
+            leftJoin: (_table: unknown, onExpr?: SQL) => {
+                recorded.leftJoins += 1
+                if (onExpr) recorded.joinParams.push(...dialect.sqlToQuery(onExpr).params)
+                return chain
+            },
+            where: (expr: SQL | undefined) => {
+                const query = expr ? dialect.sqlToQuery(expr) : null
+                recorded.whereSql = query?.sql ?? null
+                recorded.whereParams = query?.params ?? []
+                return chain
+            },
+            top: () => chain,
+            orderBy: () => Promise.resolve(rows),
+            // `.where()` / `.orderBy()` のどちらで終わっても await できるようにする。
+            // thenable であること自体が目的なので、この規則はここでは意図的に外す
+            // biome-ignore lint/suspicious/noThenProperty: 意図的な thenable (クエリビルダの終端を模擬する)
+            then: (resolve: (value: unknown) => unknown) => resolve(rows),
+        }
+        return chain
+    }
+    const update = () => {
+        const recorded: RecordedUpdate = { set: {}, whereParams: [] }
+        const chain: Record<string, unknown> = {
+            set: (values: Record<string, unknown>) => {
+                recorded.set = values
+                return chain
+            },
+            where: (expr: SQL | undefined) => {
+                recorded.whereParams = expr ? dialect.sqlToQuery(expr).params : []
+                updates.push(recorded)
+                return Promise.resolve({ rowsAffected: [1] })
+            },
+        }
+        return chain
     }
-    return { select: () => chain } as unknown as DailyReportDb
+    return { db: { select, update } as unknown as DailyReportDb, queries, updates }
 }
 
 const baseHub = (over: Partial<DailyReportHubRow>): DailyReportHubRow => ({
@@ -44,11 +120,12 @@ const baseHub = (over: Partial<DailyReportHubRow>): DailyReportHubRow => ({
     ...over,
 })
 
-const makeService = (rows: unknown[]) => {
+const makeService = (rows: unknown[], withAttachmentCodec = false) => {
     const epochs = createEpochStore(undefined)
     const cache = new SqlResultCache({ defaultTtlMs: 60_000 }, epochs)
-    return createDailyReportService({
-        db: makeDb(rows),
+    const { db, queries, updates } = makeDb(rows)
+    const service = createDailyReportService({
+        db,
         tables,
         userTable: testUsers,
         resolveUserId: async () => 8,
@@ -56,7 +133,11 @@ const makeService = (rows: unknown[]) => {
         cache,
         epochs,
         draftLabelName: "draft", // 必須注入 (ドラフト可視性フィルタ用のラベル名。テストは中立値で十分)
+        // 既定では未注入のまま。既存テストが縮退動作 (添付は常に空) で通ることも同時に確認する。
+        // ユーザー ID 用 (`ENC`) とは別の接頭辞にして ID 空間の分離を表現する。
+        ...(withAttachmentCodec ? { attachmentIdCodec: { encode: (id: number) => `ATT${id}`, decode: (t: string) => (t.startsWith("ATT") ? Number(t.slice(3)) : null) } } : {}),
     })
+    return Object.assign(service, { __queries: queries, __updates: updates })
 }
 
 describe("mapHubRecord audit-actor masking (security)", () => {
@@ -95,3 +176,188 @@ describe("mapHubRecord audit-actor masking (security)", () => {
         expect(r.author).toBe("") // author は非 null 契約のため空文字
     })
 })
+
+describe("添付ファイルの一括取得", () => {
+    it("コーデック未注入なら空マップを返す (既定の縮退動作)", async () => {
+        const svc = makeService([])
+        const map = await svc.getAttachmentsByHubIds([1, 2])
+        expect(map.size).toBe(0)
+    })
+
+    it("hubIds が空なら DB を叩かずに空マップを返す", async () => {
+        const svc = makeService([], true)
+        const map = await svc.getAttachmentsByHubIds([])
+        expect(map.size).toBe(0)
+    })
+
+    it("hub ID ごとにグルーピングし、内部数値 ID を難読化トークンへ変換する", async () => {
+        const rows = [
+            { id: 11, hubId: 1, fileName: "a.png", fileType: "image/png", fileSize: 10, createdAt: "2099-01-05 00:00:00", objectCheckedAt: null, objectMissingAt: null },
+            { id: 12, hubId: 1, fileName: "b.pdf", fileType: null, fileSize: null, createdAt: "2099-01-05 00:00:01", objectCheckedAt: "2099-01-06 00:00:00", objectMissingAt: null },
+            { id: 13, hubId: 2, fileName: "c.txt", fileType: "text/plain", fileSize: 0, createdAt: "2099-01-05 00:00:02", objectCheckedAt: "2099-01-06 00:00:00", objectMissingAt: "2099-01-06 00:00:00" },
+        ]
+        const svc = makeService(rows, true)
+        const map = await svc.getAttachmentsByHubIds([1, 2])
+
+        expect(map.get(1)).toHaveLength(2)
+        expect(map.get(2)).toHaveLength(1)
+        // 生の内部 ID が出ないこと。ユーザー ID 用の接頭辞とも異なること
+        expect(map.get(1)?.[0].id).toBe("ATT11")
+        expect(map.get(1)?.[0].id).not.toBe("11")
+        expect(map.get(1)?.[0].id.startsWith("ENC")).toBe(false)
+    })
+
+    it("実体状態を三値へ導出する (未検証 / 実在 / 消失)", async () => {
+        const rows = [
+            { id: 1, hubId: 1, fileName: "unknown.bin", fileType: null, fileSize: null, createdAt: null, objectCheckedAt: null, objectMissingAt: null },
+            { id: 2, hubId: 1, fileName: "present.bin", fileType: null, fileSize: null, createdAt: null, objectCheckedAt: "2099-01-06 00:00:00", objectMissingAt: null },
+            { id: 3, hubId: 1, fileName: "absent.bin", fileType: null, fileSize: null, createdAt: null, objectCheckedAt: "2099-01-06 00:00:00", objectMissingAt: "2099-01-06 00:00:00" },
+        ]
+        const svc = makeService(rows, true)
+        const list = (await svc.getAttachmentsByHubIds([1])).get(1) ?? []
+        expect(list.map((a) => a.state)).toEqual(["unknown", "present", "absent"])
+    })
+
+    it("サイズ 0 と サイズ不明 (null) を区別する", async () => {
+        const rows = [
+            { id: 1, hubId: 1, fileName: "empty.bin", fileType: null, fileSize: 0, createdAt: null, objectCheckedAt: null, objectMissingAt: null },
+            { id: 2, hubId: 1, fileName: "unsized.bin", fileType: null, fileSize: null, createdAt: null, objectCheckedAt: null, objectMissingAt: null },
+        ]
+        const svc = makeService(rows, true)
+        const list = (await svc.getAttachmentsByHubIds([1])).get(1) ?? []
+        expect(list[0].fileSize).toBe(0)
+        expect(list[1].fileSize).toBeNull()
+    })
+
+    it("空文字の fileType を null へ正規化する (取込元が欠損を空文字で表現する場合)", async () => {
+        const rows = [{ id: 1, hubId: 1, fileName: "x.bin", fileType: "", fileSize: null, createdAt: null, objectCheckedAt: null, objectMissingAt: null }]
+        const svc = makeService(rows, true)
+        expect((await svc.getAttachmentsByHubIds([1])).get(1)?.[0].fileType).toBeNull()
+    })
+})
+
+describe("添付ファイルの認可付き取得", () => {
+    it("添付テーブル未注入なら null を返す", async () => {
+        const epochs = createEpochStore(undefined)
+        const cache = new SqlResultCache({ defaultTtlMs: 60_000 }, epochs)
+        const { attachment: _omitted, ...tablesWithoutAttachment } = tables
+        const svc = createDailyReportService({
+            db: makeDb([]).db,
+            tables: tablesWithoutAttachment,
+            userTable: testUsers,
+            resolveUserId: async () => 8,
+            encodeUserId: (id) => `ENC${id}`,
+            cache,
+            epochs,
+            draftLabelName: "draft",
+        })
+        expect(await svc.getAttachmentForUser(1, 8)).toBeNull()
+    })
+
+    it("認可述語が閲覧者の所有と下書き非該当を OR で結び、論理削除も除外する", async () => {
+        // これがこの機能の唯一の認可境界。述語そのものを SQL 文字列として固定する
+        // (モックは行を絞れないので、生成される WHERE 句を直接表明するしかない)
+        const svc = makeService([{ fileName: "a.png", filePath: "gcs://b/a.png", fileType: "image/png", fileSize: 1 }])
+        await svc.getAttachmentForUser(11, 8)
+
+        // 最後のクエリが添付の認可判定 (直前は下書きラベルの解決)
+        const recorded = svc.__queries.at(-1)
+        const where = recorded?.whereSql ?? ""
+        expect(where).toContain("[DailyReportAttachment].[id]")
+        expect(where).toContain("[deleted_at] is null")
+        expect(where).toContain("[user_id] = ")
+        expect(where).toContain(" or ")
+        expect(where).toContain("[draft_label].[hub_id] is null")
+        // ❗ SQL 文字列だけでは足りない。値はすべて @parN へ落ちるため、
+        // 「添付 ID の位置に閲覧者 ID を渡す」ような取り違えは束縛値を見ないと検出できない
+        expect(recorded?.whereParams).toEqual([11, 8])
+    })
+
+    it("認可判定の束縛値が入れ替わっていないこと (添付 ID と閲覧者 ID)", async () => {
+        const svc = makeService([])
+        await svc.getAttachmentForUser(777, 42)
+        expect(svc.__queries.at(-1)?.whereParams).toEqual([777, 42])
+    })
+
+    it("営業日一覧・詳細取得・添付取得の 3 経路が同一の可視性述語を持つ", async () => {
+        // 1 経路だけ緩いと、緩い経路がメタデータ (件名・添付名・トークン) を渡してしまう。
+        // 「所有者本人」または「下書きラベルが付いていない」の OR を 3 経路すべてで固定する
+        const draftPredicate = (sql: string): boolean => /\[user_id\] = @par\d+\) or \(\(\[draft_label\]\.\[hub_id\] is null\)/.test(sql)
+
+        const byDate = makeService([])
+        await byDate.getDailyReportsByBusinessDateByExternalId("2099-01-05", "ext", { forceRefresh: true })
+        expect(byDate.__queries.some((q) => q.whereSql !== null && draftPredicate(q.whereSql))).toBe(true)
+
+        const byId = makeService([])
+        await byId.getDailyReportDetailById(1, 8, { forceRefresh: true })
+        expect(byId.__queries.some((q) => q.whereSql !== null && draftPredicate(q.whereSql))).toBe(true)
+
+        const byAttachment = makeService([])
+        await byAttachment.getAttachmentForUser(1, 8)
+        expect(byAttachment.__queries.some((q) => q.whereSql !== null && draftPredicate(q.whereSql))).toBe(true)
+    })
+
+    it("ID 一覧経路だけは `user_id IS NULL` を追加で許す (意図的な差分)", async () => {
+        // 4 番目の経路。取込元が投稿者を持たない日報 (user_id IS NULL) を一覧から消さないための
+        // 意図的な緩和であり、返すのは ID・営業日・ソース種別だけで本文も添付も含まない。
+        // 「3 経路と同一」ではないことを明示的に固定し、無自覚な差分と区別する
+        const byIds = makeService([])
+        await byIds.getDailyReportIdsByExternalId("ext", { forceRefresh: true })
+        const idsWhere = byIds.__queries.map((q) => q.whereSql ?? "").find((sql) => sql.includes("[draft_label].[hub_id] is null"))
+        expect(idsWhere).toBeDefined()
+        expect(idsWhere).toContain("[user_id] is null")
+    })
+
+    it("下書きラベルは複数解決し、可視性の結合が 2 つ目以降も対象にする", async () => {
+        // `draftLabelNames` には取込元ごとの下書き名を複数注入できる。1 個の ID でしか結合しないと
+        // 2 つ目の下書きラベルが付いた日報が誰にでも可視になる
+        const svc = makeService([{ id: 11 }, { id: 22 }])
+        await svc.getAttachmentForUser(1, 8)
+        // 結合条件は where ではなく leftJoin の ON 側に載る
+        const joinParams = svc.__queries.flatMap((q) => q.joinParams)
+        expect(joinParams).toContain(11)
+        expect(joinParams).toContain(22)
+    })
+})
+
+describe("実体存在の記録 (三値の書き込み側)", () => {
+    it("markAttachmentMissing は消失時刻と検証時刻の両方を立てる", async () => {
+        const svc = makeService([])
+        await svc.markAttachmentMissing(77)
+        const [update] = svc.__updates
+        expect(update?.whereParams).toEqual([77])
+        // objectMissingAt を落とすと三値が absent にならず、消失が永久に検知されない
+        expect(update?.set.objectMissingAt).toBeInstanceOf(Date)
+        expect(update?.set.objectCheckedAt).toBeInstanceOf(Date)
+        expect(update?.set.updatedAt).toBeInstanceOf(Date)
+    })
+
+    it("markAttachmentPresent は消失時刻を NULL へ戻す (自己回復)", async () => {
+        const svc = makeService([])
+        await svc.markAttachmentPresent(77)
+        const [update] = svc.__updates
+        expect(update?.whereParams).toEqual([77])
+        // ここが null でないと absent が解除されず、UI からリンクが戻らない
+        expect(update?.set.objectMissingAt).toBeNull()
+        expect(update?.set.objectCheckedAt).toBeInstanceOf(Date)
+    })
+
+    it("添付テーブル未注入なら書き込みを試みない", async () => {
+        const epochs = createEpochStore(undefined)
+        const { attachment: _omitted, ...tablesWithoutAttachment } = tables
+        const { db, updates } = makeDb([])
+        const svc = createDailyReportService({
+            db,
+            tables: tablesWithoutAttachment,
+            userTable: testUsers,
+            resolveUserId: async () => 8,
+            encodeUserId: (id) => `ENC${id}`,
+            cache: new SqlResultCache({ defaultTtlMs: 60_000 }, epochs),
+            epochs,
+            draftLabelName: "draft",
+        })
+        await svc.markAttachmentMissing(1)
+        await svc.markAttachmentPresent(1)
+        expect(updates).toHaveLength(0)
+    })
+})