《互联网产品的客户端架构·端形态与体验基础》13.1 回声客户端基线

// file: src/summary/baseline.ts
// tier: L2
// verify: node --test test/summary/baseline.test.ts

import { TabbedPageStack } from "../router/page-stack.ts";
import { createStore } from "../state/store.ts";
import type { Store } from "../state/store.ts";
import { EndpointCache, MemoryStore, buildCacheKey, policyFor } from "../data/cache-store.ts";
import type { CacheSource, CacheStore } from "../data/cache-store.ts";
import { SyncQueue } from "../data/sync-queue.ts";
import type {
  ConflictPolicy,
  Mutation,
  MutationInput,
  QueueStore,
  ReplayReport,
  SendResult,
} from "../data/sync-queue.ts";

export interface FeedCard {
  id: string;
  title: string;
}

export type BaselinePhase = "idle" | "loading" | "ready" | "offline" | "error";

export interface BaselineState {
  route: string;
  phase: BaselinePhase;
  items: FeedCard[];
  source: CacheSource | "none";
  pendingWrites: number;
  lastError: string | null;
}

export interface BaselineOptions {
  now: () => number;
  loadFeed: () => Promise<FeedCard[]>;
  send: (mutation: Mutation) => Promise<SendResult>;
  cacheStore?: CacheStore;
  queueStore?: QueueStore;
  clientId?: string;
  maxCacheEntries?: number;
}

const FEED_RESOURCE = "feed:home";
const FEED_ID = "default";

class MemoryQueueStore implements QueueStore {
  private raw: string | undefined;

  load(): string | undefined {
    return this.raw;
  }

  save(raw: string): void {
    this.raw = raw;
  }
}

/**
 * 卷一收口基线：页面栈负责“在哪”，store 负责“看到什么”，
 * EndpointCache 负责“数据从哪来”，SyncQueue 负责“写有没有丢”。
 * 所有 I/O 由构造参数注入，测试在进程内推演完整流程。
 */
export class EchoBaseline {
  private readonly stack: TabbedPageStack;
  private readonly store: Store<BaselineState>;
  private readonly cache: EndpointCache;
  private readonly queue: SyncQueue;
  private readonly loadFeed: () => Promise<FeedCard[]>;
  private readonly send: (mutation: Mutation) => Promise<SendResult>;
  private readonly key: string;

  constructor(options: BaselineOptions) {
    this.loadFeed = options.loadFeed;
    this.send = options.send;
    this.stack = new TabbedPageStack({ home: { name: "feed" } });
    this.cache = new EndpointCache({
      now: options.now,
      store: options.cacheStore ?? new MemoryStore(),
      maxEntries: options.maxCacheEntries ?? 40,
    });
    this.queue = new SyncQueue({
      clientId: options.clientId ?? "client-1",
      now: options.now,
      store: options.queueStore ?? new MemoryQueueStore(),
    });
    this.key = buildCacheKey({ resource: FEED_RESOURCE, id: FEED_ID });
    this.store = createStore<BaselineState>({
      route: "feed",
      phase: "idle",
      items: [],
      source: "none",
      pendingWrites: this.queue.size,
      lastError: null,
    });
  }

  get state(): BaselineState {
    return this.store.getState();
  }

  get route(): string {
    return this.stack.current?.route.name ?? "feed";
  }

  get pages(): string[] {
    return this.stack.entries().map((entry) => entry.route.name);
  }

  /** 冷启动先同步读本地缓存；只有 fresh/stale 才能直接上屏。 */
  hydrate(): boolean {
    const found = this.cache.lookup<FeedCard[]>(this.key, policyFor(FEED_RESOURCE));
    if (!found.entry || found.status === "expired") return false;
    this.set({
      phase: "ready",
      items: found.entry.value,
      source: found.status === "fresh" ? "cache-fresh" : "cache-stale",
    });
    return true;
  }

  /** 打开发现页：缓存优先；网络失败时用过期缓存兜底，没有缓存才报错。 */
  async openFeed(forceRefresh = false): Promise<void> {
    this.set({ phase: "loading", lastError: null });
    try {
      const result = await this.cache.get<FeedCard[]>(
        this.key,
        policyFor(FEED_RESOURCE),
        this.loadFeed,
        { forceRefresh, allowExpiredOnError: true },
      );
      this.set({
        phase: result.source === "cache-stale-offline" ? "offline" : "ready",
        items: result.value,
        source: result.source,
      });
    } catch (error) {
      this.set({ phase: "error", source: "none", lastError: message(error) });
    }
  }

  navigate(name: string, params: Record<string, string> = {}): void {
    this.stack.push({ name, params });
    this.set({ route: this.stack.current?.route.name ?? name });
  }

  back(): void {
    this.stack.back();
    this.set({ route: this.stack.current?.route.name ?? "feed" });
  }

  /** 离线写：先入队落盘，再按顺序重放；网络失败会保留剩余条目。 */
  async submit(input: MutationInput, policy: ConflictPolicy = "merge-disjoint"): Promise<ReplayReport> {
    this.queue.enqueue(input);
    this.set({ pendingWrites: this.queue.size });
    return this.flush(policy);
  }

  /** 单独重放队列，用于进程重启后继续上一次没有发完的写入。 */
  async flush(policy: ConflictPolicy = "merge-disjoint"): Promise<ReplayReport> {
    const report = await this.queue.replay({ send: this.send }, policy);
    this.set({
      pendingWrites: report.remaining,
      lastError: report.stoppedBy === "network" ? "network" : null,
    });
    return report;
  }

  private set(patch: Partial<BaselineState>): void {
    this.store.setState((state) => ({ ...state, ...patch }));
  }
}

function message(error: unknown): string {
  return error instanceof Error ? error.message : String(error);
}

node --test test/summary/baseline.test.ts

✔ 冷启动缓存为空时走网络，成功后写入统一缓存键 (1.820458ms)
✔ 新鲜缓存直接上屏，第二次打开不再请求网络 (0.435583ms)
✔ 缓存超过 stale 窗口且网络失败时，退回过期缓存并标记离线 (0.581583ms)
✔ 页面栈与 store 同步：进入详情再返回，路由回到发现页 (0.244167ms)
✔ 写入在进程重启后仍能从持久队列继续发送 (0.368667ms)
ℹ tests 5
ℹ suites 0
ℹ pass 5
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 189.891166