@solhun/feedback-kit-core 0.1.0

package/src/queue.test.ts

@@ -0,0 +1,848 @@
+// DP-252 전송 보장 검증.
+//
+// 이 파일의 통합 테스트는 "가짜 수집 서버 + 문서화된 HTTP 계약을 그대로 구현한 테스트용
+// 어댑터"를 상대로 돈다. 실 엔드포인트가 아직 배포돼 있지 않아서다(실 왕복 TC와 성능
+// TC는 `lasso` 어댑터가 생기는 DP-255 에서 시도한다 — 워크패드에 명시).
+// 여기서 검증하는 것은 코어가 지켜야 할 것들이다:
+// 큐 적재 시점 / 제거 조건(2xx **및** ok=true) / 멱등 키 재사용 / 보관 한도 / 백오프.
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  BACKOFF_MAX_MS,
+  defaultBackoff,
+  FeedbackQueue,
+  MAX_QUEUE_ITEMS,
+  RATE_LIMIT_MIN_DELAY_MS,
+} from "./queue.js";
+import { byteLengthOf, canUseKeepalive } from "./keepalive.js";
+import type {
+  FeedbackAdapter,
+  FeedbackReport,
+  FeedbackStorage,
+  SubmitResult,
+} from "./types.js";
+
+// ────────────────────────────────────────────────────────────────────────────
+// 테스트 도구
+// ────────────────────────────────────────────────────────────────────────────
+
+const QUEUE_KEY = "feedback-kit:queue";
+const START_TIME = 1_700_000_000_000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+let clockNow = START_TIME;
+const clock = (): number => clockNow;
+const advance = (ms: number): void => {
+  clockNow += ms;
+};
+
+let seq = 0;
+function makeReport(over: Partial<FeedbackReport> = {}): FeedbackReport {
+  seq += 1;
+  return {
+    clientSubmissionId: `sub-${seq}`,
+    kind: "report",
+    comment: `테스트 제보 ${seq}`,
+    priority: "unset",
+    screenshot: null,
+    pin: null,
+    element: null,
+    context: {
+      app: "test-app",
+      screen: "/home",
+      url: null,
+      sessionId: "session-1",
+      user: { id: "guest_1", email: null, isGuest: true },
+      source: { screenId: null, sourceFile: null },
+      platform: "unknown",
+      timezone: "Asia/Seoul",
+      clientTimestamp: new Date(clockNow).toISOString(),
+      native: null,
+      web: null,
+      diagnostics: null,
+      extra: {},
+    },
+    createdAt: new Date(clockNow).toISOString(),
+    ...over,
+  };
+}
+
+/** 메모리 저장소. `limitBytes` 를 주면 그 크기를 넘는 쓰기를 쿼터 초과로 거절한다. */
+function memoryStorage(limitBytes = Number.POSITIVE_INFINITY): FeedbackStorage & {
+  dump(): unknown;
+} {
+  const map = new Map<string, string>();
+  return {
+    async get(key) {
+      return map.get(key) ?? null;
+    },
+    async set(key, value) {
+      if (value.length > limitBytes) {
+        throw new Error("QuotaExceededError");
+      }
+      map.set(key, value);
+    },
+    async remove(key) {
+      map.delete(key);
+    },
+    dump() {
+      const raw = map.get(QUEUE_KEY);
+      return raw === undefined ? null : JSON.parse(raw);
+    },
+  };
+}
+
+interface StubStep {
+  status: number;
+  body?: unknown;
+  headers?: Record<string, string>;
+  /** 네트워크 자체가 끊긴 상황. */
+  networkError?: boolean;
+}
+
+interface CapturedRequest {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body: unknown;
+  keepalive: boolean;
+}
+
+/**
+ * 가짜 수집 엔드포인트.
+ * 문서화된 계약만 흉내낸다: `Idempotency-Key` 로 중복 제출을 합치고,
+ * 성공 응답은 `{ ok: true, annotationId, sourceId, projectId }`.
+ */
+function createFakeIngest(steps: StubStep[] = []) {
+  const requests: CapturedRequest[] = [];
+  const stored = new Map<string, { unverified: boolean }>();
+  const plan = [...steps];
+
+  const fetchImpl = async (
+    url: string,
+    init: {
+      method?: string;
+      headers?: Record<string, string>;
+      body?: string;
+      keepalive?: boolean;
+    }
+  ): Promise<{ status: number; headers: Map<string, string>; json(): Promise<unknown> }> => {
+    const headers = init.headers ?? {};
+    const key = headers["Idempotency-Key"] ?? "";
+    requests.push({
+      url,
+      method: init.method ?? "GET",
+      headers,
+      body: init.body === undefined ? null : JSON.parse(init.body),
+      keepalive: init.keepalive === true,
+    });
+
+    const step = plan.shift();
+    if (step?.networkError) throw new TypeError("Failed to fetch");
+
+    const status = step?.status ?? 200;
+    if (status >= 200 && status < 300) {
+      // 멱등: 같은 키는 한 번만 적재한다.
+      if (!stored.has(key)) {
+        stored.set(key, { unverified: headers["Authorization"] === undefined });
+      }
+    }
+    const body =
+      step?.body ??
+      (status >= 200 && status < 300
+        ? { ok: true, annotationId: `ann-${key}`, sourceId: "src-1", projectId: "proj-1" }
+        : { ok: false });
+
+    return {
+      status,
+      headers: new Map(Object.entries(step?.headers ?? {})),
+      async json() {
+        return body;
+      },
+    };
+  };
+
+  return { requests, stored, fetchImpl };
+}
+
+/**
+ * 문서화된 HTTP 계약을 그대로 구현한 테스트용 어댑터.
+ * 실패를 예외가 아니라 결과값으로 돌려주는 규약(DP-255)을 여기서도 지킨다.
+ * 프로덕션 `lasso` 어댑터는 DP-255 에서 만든다 — 이건 코어 검증용 최소 구현이다.
+ */
+function createTestAdapter(opts: {
+  fetchImpl: ReturnType<typeof createFakeIngest>["fetchImpl"];
+  token?: string | null;
+  warn?: (...a: unknown[]) => void;
+}): FeedbackAdapter {
+  const warn = opts.warn ?? (() => {});
+  return {
+    async submit(report): Promise<SubmitResult> {
+      const body = JSON.stringify(report);
+      const headers: Record<string, string> = {
+        "Content-Type": "application/json",
+        "Idempotency-Key": report.clientSubmissionId,
+      };
+      if (opts.token) {
+        headers["Authorization"] = `Bearer ${opts.token}`;
+      } else {
+        // 토큰이 없어도 제보를 버리지 않는다. 사용자에게는 알리지 않고 개발자 콘솔에만.
+        warn("feedback-kit: 수집 토큰이 없다 — 서버가 미검증(unverified) 제보로 적재한다");
+      }
+
+      try {
+        const res = await opts.fetchImpl("https://ingest.example/api/feedback", {
+          method: "POST",
+          headers,
+          body,
+          keepalive: canUseKeepalive(byteLengthOf(body)),
+        });
+
+        const retryAfter = res.headers.get("Retry-After");
+        const retryAfterMs = retryAfter ? Number(retryAfter) * 1000 : null;
+
+        if (res.status === 429) {
+          return { ok: false, id: null, retryable: true, retryAfterMs, rateLimited: true };
+        }
+        if (res.status >= 200 && res.status < 300) {
+          const json = (await res.json()) as { ok?: boolean; annotationId?: string };
+          // 2xx 만으로는 성공이 아니다. 본문의 ok 까지 봐야 한다.
+          if (json.ok === true) {
+            return { ok: true, id: json.annotationId ?? null, retryable: false, retryAfterMs: null };
+          }
+          return { ok: false, id: null, retryable: true, retryAfterMs };
+        }
+        if (res.status === 401 || res.status === 403) {
+          // 토큰 문제로 제보를 버리지 않는다. 큐에 남겨 둔다.
+          warn("feedback-kit: 수집 토큰이 거절됐다(제보는 큐에 보관)");
+          return { ok: false, id: null, retryable: true, retryAfterMs };
+        }
+        if (res.status >= 400 && res.status < 500) {
+          return { ok: false, id: null, retryable: false, retryAfterMs: null };
+        }
+        return { ok: false, id: null, retryable: true, retryAfterMs };
+      } catch {
+        // 네트워크 실패 = 일시적. 다음 트리거에서 다시 보낸다.
+        return { ok: false, id: null, retryable: true, retryAfterMs: null };
+      }
+    },
+  };
+}
+
+/** 호출 횟수만 세는 단순 어댑터. */
+function stubAdapter(result: SubmitResult | (() => SubmitResult)) {
+  const calls: FeedbackReport[] = [];
+  const adapter: FeedbackAdapter = {
+    async submit(report) {
+      calls.push(report);
+      return typeof result === "function" ? result() : result;
+    },
+  };
+  return { adapter, calls };
+}
+
+const RETRYABLE_FAIL: SubmitResult = {
+  ok: false,
+  id: null,
+  retryable: true,
+  retryAfterMs: null,
+};
+
+beforeEach(() => {
+  clockNow = START_TIME;
+  seq = 0;
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// TC1 / TC14 — 큐 적재와 제거 조건
+// ────────────────────────────────────────────────────────────────────────────
+
+describe("큐 적재와 제거 조건", () => {
+  it("TC1: 2xx 를 받기 전에는 제보가 큐에 남아 있다", async () => {
+    const storage = memoryStorage();
+    const { adapter, calls } = stubAdapter(RETRYABLE_FAIL);
+    const queue = new FeedbackQueue({ storage, adapter, now: clock, flushIntervalMs: 0 });
+
+    const outcome = await queue.submit(makeReport());
+
+    expect(calls).toHaveLength(1); // 전송을 시도는 했다
+    expect(outcome.delivered).toBe(false);
+    expect(outcome.queued).toBe(true);
+    expect(await queue.size()).toBe(1); // 그래도 큐에 남아 있다
+  });
+
+  it("TC14: 정상 전송되면 큐가 비고 서버에는 제보가 1건만 남는다", async () => {
+    const storage = memoryStorage();
+    const ingest = createFakeIngest();
+    const queue = new FeedbackQueue({
+      storage,
+      adapter: createTestAdapter({ fetchImpl: ingest.fetchImpl, token: "tok" }),
+      now: clock,
+      flushIntervalMs: 0,
+    });
+
+    const outcome = await queue.submit(makeReport());
+
+    expect(outcome.delivered).toBe(true);
+    expect(outcome.id).toBe("ann-sub-1");
+    expect(await queue.size()).toBe(0);
+    expect(ingest.stored.size).toBe(1);
+  });
+
+  it("TC2: 재시도는 같은 clientSubmissionId 로 나가고 서버 제보는 1건만 생긴다", async () => {
+    const storage = memoryStorage();
+    const ingest = createFakeIngest([
+      { status: 500 }, // 첫 시도 실패
+      { status: 200 }, // 재시도 성공
+    ]);
+    const queue = new FeedbackQueue({
+      storage,
+      adapter: createTestAdapter({ fetchImpl: ingest.fetchImpl, token: "tok" }),
+      now: clock,
+      flushIntervalMs: 0,
+    });
+
+    const report = makeReport();
+    const first = await queue.submit(report);
+    expect(first.delivered).toBe(false);
+    expect(await queue.size()).toBe(1);
+
+    advance(10 * 1000); // 백오프(5초) 경과
+    await queue.flush();
+
+    expect(await queue.size()).toBe(0);
+    expect(ingest.requests).toHaveLength(2);
+    expect(ingest.requests[0]?.headers["Idempotency-Key"]).toBe(report.clientSubmissionId);
+    expect(ingest.requests[1]?.headers["Idempotency-Key"]).toBe(report.clientSubmissionId);
+    expect(ingest.stored.size).toBe(1); // 두 번 보냈지만 서버에는 1건
+  });
+
+  it("TC10: 2xx 라도 본문이 ok=false 면 실패로 보고 큐에 남긴다", async () => {
+    const storage = memoryStorage();
+    const ingest = createFakeIngest([{ status: 200, body: { ok: false, error: "invalid" } }]);
+    const queue = new FeedbackQueue({
+      storage,
+      adapter: createTestAdapter({ fetchImpl: ingest.fetchImpl, token: "tok" }),
+      now: clock,
+      flushIntervalMs: 0,
+    });
+
+    const outcome = await queue.submit(makeReport());
+
+    expect(outcome.delivered).toBe(false);
+    expect(await queue.size()).toBe(1);
+  });
+
+  it("어댑터가 예외를 던져도 제보를 잃지 않는다", async () => {
+    const storage = memoryStorage();
+    const warn = vi.fn();
+    const adapter: FeedbackAdapter = {
+      async submit() {
+        throw new Error("boom");
+      },
+    };
+    const queue = new FeedbackQueue({ storage, adapter, now: clock, flushIntervalMs: 0, warn });
+
+    await queue.submit(makeReport());
+
+    expect(await queue.size()).toBe(1);
+    expect(warn).toHaveBeenCalled();
+  });
+
+  it("여러 건이 밀려 있으면 한 건씩 순서대로 보낸다", async () => {
+    const storage = memoryStorage();
+    let inFlight = 0;
+    let maxInFlight = 0;
+    const order: string[] = [];
+    const adapter: FeedbackAdapter = {
+      async submit(report) {
+        inFlight += 1;
+        maxInFlight = Math.max(maxInFlight, inFlight);
+        await Promise.resolve();
+        order.push(report.clientSubmissionId);
+        inFlight -= 1;
+        return { ok: true, id: report.clientSubmissionId, retryable: false, retryAfterMs: null };
+      },
+    };
+    const queue = new FeedbackQueue({ storage, adapter, now: clock, flushIntervalMs: 0 });
+
+    await queue.enqueue(makeReport());
+    await queue.enqueue(makeReport());
+    await queue.enqueue(makeReport());
+    await queue.flush();
+
+    expect(maxInFlight).toBe(1);
+    expect(order).toEqual(["sub-1", "sub-2", "sub-3"]);
+    expect(await queue.size()).toBe(0);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// TC3 / TC4 / TC5 — 보관 한도
+// ────────────────────────────────────────────────────────────────────────────
+
+describe("보관 한도", () => {
+  it(`TC3: ${MAX_QUEUE_ITEMS}건을 넘기면 오래된 것부터 버리고 콘솔에 경고한다`, async () => {
+    const storage = memoryStorage();
+    const warn = vi.fn();
+    const { adapter } = stubAdapter(RETRYABLE_FAIL);
+    const queue = new FeedbackQueue({ storage, adapter, now: clock, flushIntervalMs: 0, warn });
+
+    for (let i = 0; i < MAX_QUEUE_ITEMS + 3; i += 1) {
+      await queue.enqueue(makeReport());
+    }
+
+    expect(await queue.size()).toBe(MAX_QUEUE_ITEMS);
+
+    const persisted = storage.dump() as Array<{ report: { clientSubmissionId: string } }>;
+    // 가장 오래된 3건(sub-1~3)이 밀려나고 sub-4 가 맨 앞이다.
+    expect(persisted[0]?.report.clientSubmissionId).toBe("sub-4");
+    expect(
+      warn.mock.calls.filter((c) => String(c[0]).includes("가장 오래된 제보를 버렸다"))
+    ).toHaveLength(3);
+  });
+
+  it("TC4: 7일이 지난 제보는 마운트 시 정리되고 전송을 시도하지 않는다", async () => {
+    const storage = memoryStorage();
+    const warn = vi.fn();
+    const { adapter, calls } = stubAdapter(RETRYABLE_FAIL);
+
+    // 8일 전에 들어온 제보를 저장소에 직접 심어 둔다.
+    await storage.set(
+      QUEUE_KEY,
+      JSON.stringify([
+        {
+          report: makeReport(),
+          attempts: 0,
+          nextAttemptAt: null,
+          enqueuedAt: clockNow - 8 * DAY_MS,
+        },
+      ])
+    );
+
+    const queue = new FeedbackQueue({ storage, adapter, now: clock, flushIntervalMs: 0, warn });
+    queue.start(); // 마운트
+    await queue.flush();
+    queue.stop();
+
+    expect(calls).toHaveLength(0); // 전송을 시도조차 하지 않는다
+    expect(await queue.size()).toBe(0);
+    expect(warn.mock.calls.some((c) => String(c[0]).includes("보관 기간(7일)"))).toBe(true);
+  });
+
+  it("7일이 안 지난 제보는 마운트 시 그대로 전송된다", async () => {
+    const storage = memoryStorage();
+    const { adapter, calls } = stubAdapter(RETRYABLE_FAIL);
+
+    await storage.set(
+      QUEUE_KEY,
+      JSON.stringify([
+        {
+          report: makeReport(),
+          attempts: 0,
+          nextAttemptAt: null,
+          enqueuedAt: clockNow - 6 * DAY_MS,
+        },
+      ])
+    );
+
+    const queue = new FeedbackQueue({ storage, adapter, now: clock, flushIntervalMs: 0 });
+    queue.start();
+    await queue.flush();
+    queue.stop();
+
+    expect(calls).toHaveLength(1);
+    expect(await queue.size()).toBe(1);
+  });
+
+  it("TC5: 저장소 한도를 넘으면 스크린샷만 떼어내고 제보 본문은 보관한다", async () => {
+    const bigScreenshot = "A".repeat(4000);
+    const withShot = makeReport({
+      comment: "스크린샷이 붙은 제보",
+      screenshot: { base64: bigScreenshot, contentType: "image/png" },
+    });
+
+    // 스크린샷을 포함하면 넘치고, 떼어내면 들어가는 한도.
+    const limit = 2000;
+    const storage = memoryStorage(limit);
+    const warn = vi.fn();
+    const { adapter } = stubAdapter(RETRYABLE_FAIL);
+    const queue = new FeedbackQueue({ storage, adapter, now: clock, flushIntervalMs: 0, warn });
+
+    await queue.enqueue(withShot);
+
+    const persisted = storage.dump() as Array<{
+      report: { comment: string; screenshot: unknown; clientSubmissionId: string };
+    }>;
+    expect(persisted).toHaveLength(1); // 제보 자체는 살아 있다
+    expect(persisted[0]?.report.comment).toBe("스크린샷이 붙은 제보"); // 사용자가 쓴 글은 보존
+    expect(persisted[0]?.report.screenshot).toBeNull(); // 스크린샷만 떨어져 나갔다
+    expect(warn.mock.calls.some((c) => String(c[0]).includes("스크린샷을 떼어내고"))).toBe(true);
+
+    // 호출자가 넘긴 원본 객체는 건드리지 않는다.
+    expect(withShot.screenshot).not.toBeNull();
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// TC8 / TC9 — 백오프와 429
+// ────────────────────────────────────────────────────────────────────────────
+
+describe("재시도 간격", () => {
+  it("TC9: 연속 실패해도 재시도 간격이 5분을 넘지 않는다", () => {
+    for (let attempts = 1; attempts <= 10; attempts += 1) {
+      expect(defaultBackoff(attempts, null)).toBeLessThanOrEqual(BACKOFF_MAX_MS);
+    }
+    expect(defaultBackoff(1, null)).toBe(5 * 1000); // 5초에서 시작
+    expect(defaultBackoff(2, null)).toBe(10 * 1000); // 2배씩
+    expect(defaultBackoff(10, null)).toBe(BACKOFF_MAX_MS); // 상한에 붙는다
+  });
+
+  it("TC9(통합): 10회 연속 실패하는 동안 매 간격이 5분 이하다", async () => {
+    const storage = memoryStorage();
+    const { adapter, calls } = stubAdapter(RETRYABLE_FAIL);
+    const queue = new FeedbackQueue({ storage, adapter, now: clock, flushIntervalMs: 0 });
+
+    await queue.enqueue(makeReport());
+    await queue.flush(); // 최초 전송(실패) — 여기서 첫 백오프가 잡힌다
+
+    for (let i = 0; i < 10; i += 1) {
+      const persisted = storage.dump() as Array<{ nextAttemptAt: number | null }>;
+      const nextAt = persisted[0]?.nextAttemptAt ?? clockNow;
+      const gap = nextAt - clockNow;
+      expect(gap).toBeLessThanOrEqual(BACKOFF_MAX_MS);
+      advance(Math.max(gap, 0));
+      await queue.flush();
+    }
+
+    expect(calls.length).toBe(11); // 최초 1회 + 재시도 10회
+    expect(await queue.size()).toBe(1); // 그래도 제보는 살아 있다
+  });
+
+  it("서버가 준 Retry-After 는 존중하되 5분으로 자른다", () => {
+    expect(defaultBackoff(1, 90 * 1000)).toBe(90 * 1000);
+    expect(defaultBackoff(1, 60 * 60 * 1000)).toBe(BACKOFF_MAX_MS);
+  });
+
+  it("TC8: 429 면 큐에 남기고 최소 10분 뒤에 다시 시도한다", async () => {
+    const storage = memoryStorage();
+    const ingest = createFakeIngest([
+      { status: 429, headers: { "Retry-After": "60" } },
+      { status: 200 },
+    ]);
+    const queue = new FeedbackQueue({
+      storage,
+      adapter: createTestAdapter({ fetchImpl: ingest.fetchImpl, token: "tok" }),
+      now: clock,
+      flushIntervalMs: 0,
+    });
+
+    await queue.submit(makeReport());
+    expect(await queue.size()).toBe(1);
+
+    const afterFail = storage.dump() as Array<{ nextAttemptAt: number; rateLimited: boolean }>;
+    expect(afterFail[0]?.rateLimited).toBe(true);
+    // 서버가 60초를 권했어도 429 는 최소 10분이다.
+    expect((afterFail[0]?.nextAttemptAt ?? 0) - clockNow).toBe(RATE_LIMIT_MIN_DELAY_MS);
+
+    // 5분 뒤 수동 [다시 보내기] — 429 대기는 앞당기지 않는다.
+    advance(5 * 60 * 1000);
+    await queue.retryNow();
+    expect(ingest.requests).toHaveLength(1);
+    expect(await queue.size()).toBe(1);
+
+    // 10분이 지나면 다시 보낸다.
+    advance(6 * 60 * 1000);
+    await queue.flush();
+    expect(ingest.requests).toHaveLength(2);
+    expect(await queue.size()).toBe(0);
+  });
+
+  it("일반 실패는 수동 [다시 보내기] 로 즉시 재시도된다", async () => {
+    const storage = memoryStorage();
+    const { adapter, calls } = stubAdapter(RETRYABLE_FAIL);
+    const queue = new FeedbackQueue({ storage, adapter, now: clock, flushIntervalMs: 0 });
+
+    await queue.submit(makeReport());
+    expect(calls).toHaveLength(1);
+
+    await queue.retryNow(); // 백오프를 기다리지 않는다
+    expect(calls).toHaveLength(2);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// TC7 — 토큰 없음/무효
+// ────────────────────────────────────────────────────────────────────────────
+
+describe("토큰 없음/무효", () => {
+  it("TC7: 토큰이 없어도 전송하고, 사용자에게는 실패를 알리지 않으며 콘솔 경고만 남는다", async () => {
+    const storage = memoryStorage();
+    const ingest = createFakeIngest();
+    const warn = vi.fn();
+    const queue = new FeedbackQueue({
+      storage,
+      adapter: createTestAdapter({ fetchImpl: ingest.fetchImpl, token: null, warn }),
+      now: clock,
+      flushIntervalMs: 0,
+      warn,
+    });
+
+    const outcome = await queue.submit(makeReport());
+
+    expect(ingest.requests[0]?.headers["Authorization"]).toBeUndefined();
+    expect(ingest.stored.size).toBe(1);
+    expect([...ingest.stored.values()][0]?.unverified).toBe(true); // 서버가 미검증으로 적재
+    expect(outcome.delivered).toBe(true); // 사용자에게는 성공으로 보인다
+    expect(warn.mock.calls.some((c) => String(c[0]).includes("수집 토큰이 없다"))).toBe(true);
+    expect(queue.getStatus().lastError).toBeNull();
+  });
+
+  it("토큰이 거절돼도(401) 제보를 버리지 않는다", async () => {
+    const storage = memoryStorage();
+    const ingest = createFakeIngest([{ status: 401 }]);
+    const warn = vi.fn();
+    const queue = new FeedbackQueue({
+      storage,
+      adapter: createTestAdapter({ fetchImpl: ingest.fetchImpl, token: "bad", warn }),
+      now: clock,
+      flushIntervalMs: 0,
+    });
+
+    await queue.submit(makeReport());
+
+    expect(await queue.size()).toBe(1);
+    expect(warn).toHaveBeenCalled();
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// 이탈 대비(keepalive) — TC6 의 클라이언트 측 근거
+// ────────────────────────────────────────────────────────────────────────────
+
+describe("이탈 대비", () => {
+  it("작은 제보는 keepalive 로 나간다", async () => {
+    const storage = memoryStorage();
+    const ingest = createFakeIngest();
+    const queue = new FeedbackQueue({
+      storage,
+      adapter: createTestAdapter({ fetchImpl: ingest.fetchImpl, token: "tok" }),
+      now: clock,
+      flushIntervalMs: 0,
+    });
+
+    await queue.submit(makeReport());
+
+    expect(ingest.requests[0]?.keepalive).toBe(true);
+  });
+
+  it("64 KiB 를 넘는 제보(스크린샷 동반)는 keepalive 없이 보내고 큐에 남겨 재전송한다", async () => {
+    const storage = memoryStorage();
+    const ingest = createFakeIngest([{ networkError: true, status: 0 }, { status: 200 }]);
+    const queue = new FeedbackQueue({
+      storage,
+      adapter: createTestAdapter({ fetchImpl: ingest.fetchImpl, token: "tok" }),
+      now: clock,
+      flushIntervalMs: 0,
+    });
+
+    const big = makeReport({
+      screenshot: { base64: "B".repeat(100 * 1024), contentType: "image/png" },
+    });
+    await queue.submit(big); // 이탈로 끊긴 상황을 네트워크 오류로 흉내낸다
+
+    expect(ingest.requests[0]?.keepalive).toBe(false); // 한도를 넘으므로 켜지 않는다
+    expect(await queue.size()).toBe(1); // 유실이 아니라 지연
+
+    advance(10 * 1000);
+    await queue.flush(); // 다음 마운트/복귀에서 자동 재전송
+    expect(await queue.size()).toBe(0);
+    expect(ingest.stored.size).toBe(1);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// 상태 표시
+// ────────────────────────────────────────────────────────────────────────────
+
+describe("전송 상태", () => {
+  it("전송 중 / 대기 / 없음 상태를 구독으로 알린다", async () => {
+    const storage = memoryStorage();
+    const { adapter } = stubAdapter(RETRYABLE_FAIL);
+    const queue = new FeedbackQueue({ storage, adapter, now: clock, flushIntervalMs: 0 });
+
+    const seen: string[] = [];
+    const unsubscribe = queue.subscribe((s) => seen.push(s.state));
+
+    await queue.submit(makeReport());
+
+    expect(seen[0]).toBe("idle"); // 구독 즉시 현재 상태 1회
+    expect(seen).toContain("sending");
+    expect(queue.getStatus()).toEqual({ state: "pending", pending: 1, lastError: "retryable" });
+
+    unsubscribe();
+    const before = seen.length;
+    await queue.flush();
+    expect(seen.length).toBe(before); // 해지 뒤에는 통지가 오지 않는다
+  });
+
+  it("성공하면 대기 건수가 0 이 되고 마지막 오류가 지워진다", async () => {
+    const storage = memoryStorage();
+    let fail = true;
+    const adapter: FeedbackAdapter = {
+      async submit(report) {
+        if (fail) {
+          fail = false;
+          return RETRYABLE_FAIL;
+        }
+        return { ok: true, id: report.clientSubmissionId, retryable: false, retryAfterMs: null };
+      },
+    };
+    const queue = new FeedbackQueue({ storage, adapter, now: clock, flushIntervalMs: 0 });
+
+    await queue.submit(makeReport());
+    expect(queue.getStatus().lastError).toBe("retryable");
+
+    await queue.retryNow();
+    expect(queue.getStatus()).toEqual({ state: "idle", pending: 0, lastError: null });
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// 저장소 견고성
+// ────────────────────────────────────────────────────────────────────────────
+
+describe("저장소 견고성", () => {
+  it("큐가 손상돼 있으면 초기화하고 새 제보를 계속 받는다", async () => {
+    const storage = memoryStorage();
+    await storage.set(QUEUE_KEY, "{이건 JSON 이 아니다");
+    const warn = vi.fn();
+    const { adapter } = stubAdapter(RETRYABLE_FAIL);
+    const queue = new FeedbackQueue({ storage, adapter, now: clock, flushIntervalMs: 0, warn });
+
+    await queue.enqueue(makeReport());
+
+    expect(await queue.size()).toBe(1);
+    expect(warn.mock.calls.some((c) => String(c[0]).includes("손상"))).toBe(true);
+  });
+
+  it("enqueuedAt 이 없던 옛 항목도 즉시 버리지 않는다", async () => {
+    const storage = memoryStorage();
+    const { adapter, calls } = stubAdapter(RETRYABLE_FAIL);
+    await storage.set(
+      QUEUE_KEY,
+      JSON.stringify([{ report: makeReport(), attempts: 0, nextAttemptAt: null }])
+    );
+
+    const queue = new FeedbackQueue({ storage, adapter, now: clock, flushIntervalMs: 0 });
+    await queue.flush();
+
+    expect(calls).toHaveLength(1);
+    expect(await queue.size()).toBe(1);
+  });
+
+  it("동시에 들어온 제보가 서로를 덮어쓰지 않는다", async () => {
+    const storage = memoryStorage();
+    const { adapter } = stubAdapter(RETRYABLE_FAIL);
+    const queue = new FeedbackQueue({ storage, adapter, now: clock, flushIntervalMs: 0 });
+
+    await Promise.all([
+      queue.enqueue(makeReport()),
+      queue.enqueue(makeReport()),
+      queue.enqueue(makeReport()),
+    ]);
+
+    expect(await queue.size()).toBe(3);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// 저장소 교체 — w1 "저장소를 교체해도 큐 동작이 같다"
+// ────────────────────────────────────────────────────────────────────────────
+
+/**
+ * AsyncStorage 처럼 **비동기이고 내부 구조가 다른** 저장소.
+ * memoryStorage 가 Map 에 즉시 쓰는 것과 달리, 여기서는 키/값 쌍 배열에 담고
+ * 매 연산이 한 틱 뒤에 끝난다. 큐가 저장소 구현을 알고 있으면 여기서 갈라진다.
+ */
+function deferredPairStorage(): FeedbackStorage {
+  let pairs: Array<[string, string]> = [];
+  const tick = (): Promise<void> => new Promise((r) => setTimeout(r, 0));
+  return {
+    async get(key) {
+      await tick();
+      return pairs.find(([k]) => k === key)?.[1] ?? null;
+    },
+    async set(key, value) {
+      await tick();
+      pairs = pairs.filter(([k]) => k !== key);
+      pairs.push([key, value]);
+    },
+    async remove(key) {
+      await tick();
+      pairs = pairs.filter(([k]) => k !== key);
+    },
+  };
+}
+
+describe("저장소 교체", () => {
+  // 같은 시나리오(실패 → 큐 잔류 → 성공 → 큐 비움)를 두 구현에 그대로 돌리고
+  // 관측값을 비교한다. 기대값을 손으로 적지 않고 **두 실행의 결과를 서로 대조**하는
+  // 이유는, 한쪽만 보면 "둘 다 같이 틀린" 경우를 못 잡기 때문이다.
+  async function runScenario(storage: FeedbackStorage) {
+    const ingest = createFakeIngest([
+      { status: 503 }, // 1회차: 일시 실패 → 큐에 남는다
+      { status: 200 }, // 2회차: 성공 → 큐에서 빠진다
+    ]);
+    const queue = new FeedbackQueue({
+      storage,
+      adapter: createTestAdapter({ fetchImpl: ingest.fetchImpl, token: "tok" }),
+      now: clock,
+      flushIntervalMs: 0,
+      warn: () => {},
+    });
+
+    const report = makeReport();
+    const first = await queue.submit(report);
+    const sizeAfterFail = await queue.size();
+
+    advance(BACKOFF_MAX_MS);
+    await queue.retryNow();
+    const sizeAfterSuccess = await queue.size();
+
+    return {
+      firstDelivered: first.delivered,
+      firstQueued: first.queued,
+      sizeAfterFail,
+      sizeAfterSuccess,
+      storedCount: ingest.stored.size,
+      // 키의 **값**은 실행마다 달라지므로(제보마다 새로 발급) 값이 아니라 불변식을 본다:
+      // "몇 번을 재시도해도 하나의 키로만 나갔다".
+      requestCount: ingest.requests.length,
+      distinctSubmissionIds: new Set(
+        ingest.requests.map((r) => (r.body as { clientSubmissionId?: string })?.clientSubmissionId)
+      ).size,
+    };
+  }
+
+  it("Map 기반이든 비동기 배열 기반이든 큐 동작이 같다", async () => {
+    const viaMemory = await runScenario(memoryStorage());
+    const viaDeferred = await runScenario(deferredPairStorage());
+
+    expect(viaDeferred).toEqual(viaMemory);
+  });
+
+  it("교체한 저장소에서도 실패는 큐에 남기고 성공하면 비운다", async () => {
+    const result = await runScenario(deferredPairStorage());
+
+    expect(result.firstDelivered).toBe(false);
+    expect(result.firstQueued).toBe(true);
+    expect(result.sizeAfterFail).toBe(1);
+    expect(result.sizeAfterSuccess).toBe(0);
+    expect(result.storedCount).toBe(1);
+    // 두 번 나갔지만 멱등 키는 하나다.
+    expect(result.requestCount).toBe(2);
+    expect(result.distinctSubmissionIds).toBe(1);
+  });
+});