《互联网产品的客户端架构·端形态与体验基础》1.1 客户端架构的四个独有约束

// file: src/core/constraints.ts
// tier: L1
// verify: node --test test/core/constraints.test.ts

export type NetworkProfile = "fast" | "slow" | "offline";
export type LifecycleState = "foreground" | "background" | "cold-start";
export type InputMode = "touch" | "mouse" | "keyboard";

export interface ClientFacts {
  /** 产品事实：用户主要使用的网络环境 */
  network: NetworkProfile;
  /** 产品事实：应用被系统中断的频率（次/小时） */
  interruptionsPerHour: number;
  /** 产品事实：主输入方式 */
  inputs: InputMode[];
  /** 产品事实：是否必须在无网时完成核心任务 */
  offlineRequired: boolean;
}

export type Risk = "startup" | "offline" | "interruption" | "input" | "distribution";

export interface ConstraintClass {
  risks: Risk[];
  required: string[];
  forbiddenDefaults: string[];
}

const FACTS_LIMIT = {
  interruptionsPerHour: 6,
} as const;

/**
 * 把产品事实翻译成端上风险与必备能力。
 * 判断顺序固定：离线 > 中断 > 网络 > 输入 > 分发，越靠前越会推翻后面的假设。
 */
export function classifyConstraints(facts: ClientFacts): ConstraintClass {
  const risks: Risk[] = [];
  const required = new Set<string>();
  const forbidden = new Set<string>();

  if (facts.offlineRequired) {
    risks.push("offline");
    required.add("local-store");
    required.add("sync-queue");
    forbidden.add("optimistic-only-write");
  }

  if (facts.interruptionsPerHour > FACTS_LIMIT.interruptionsPerHour) {
    risks.push("interruption");
    required.add("state-restore");
    required.add("draft-persistence");
    forbidden.add("in-memory-only-draft");
  }

  if (facts.network === "slow" || facts.network === "offline") {
    risks.push("startup");
    required.add("cache-first-render");
    required.add("request-budget");
    forbidden.add("blocking-first-paint");
  }

  if (facts.inputs.includes("touch")) {
    risks.push("input");
    required.add("hit-target");
    forbidden.add("hover-only-affordance");
  }

  risks.push("distribution");
  required.add("version-compat");
  forbidden.add("no-force-upgrade-window");

  return {
    risks,
    required: [...required].sort(),
    forbiddenDefaults: [...forbidden].sort(),
  };
}

/**
 * 判断某个决策是否与已识别约束冲突。
 * 返回空数组表示没有发现冲突；每条冲突都带原因，便于写进评审记录。
 */
export function conflictsWithConstraints(
  decision: string,
  cls: ConstraintClass,
): string[] {
  const reasons: string[] = [];
  if (cls.forbiddenDefaults.includes(decision)) {
    reasons.push(`决策 ${decision} 与已识别风险 ${cls.risks.join(",")} 冲突`);
  }
  return reasons;
}

// file: test/core/constraints.test.ts
// tier: L1
// verify: node --test test/core/constraints.test.ts

import { test } from "node:test";
import assert from "node:assert/strict";
import { classifyConstraints, conflictsWithConstraints } from "../../src/core/constraints.ts";
import type { ClientFacts } from "../../src/core/constraints.ts";

const base: ClientFacts = {
  network: "fast",
  interruptionsPerHour: 2,
  inputs: ["touch", "keyboard"],
  offlineRequired: false,
};

test("纯在线、低中断的产品只需要分发与输入约束", () => {
  const cls = classifyConstraints(base);
  assert.deepEqual(cls.risks, ["input", "distribution"]);
  assert.ok(cls.required.includes("version-compat"));
  assert.ok(!cls.required.includes("sync-queue"));
});

test("离线优先会推翻“只做乐观写入”的默认做法", () => {
  const cls = classifyConstraints({ ...base, offlineRequired: true, network: "offline" });
  assert.ok(cls.risks.includes("offline"));
  assert.ok(cls.risks.includes("startup"));
  const [reason] = conflictsWithConstraints("optimistic-only-write", cls);
  assert.match(reason, /offline/);
  assert.match(reason, /startup/);
});

test("高中断频率要求状态恢复与草稿持久化", () => {
  const cls = classifyConstraints({ ...base, interruptionsPerHour: 12 });
  assert.ok(cls.risks.includes("interruption"));
  assert.ok(cls.required.includes("state-restore"));
  assert.ok(cls.required.includes("draft-persistence"));
});

test("判断顺序稳定，风险列表可直接比对", () => {
  const cls = classifyConstraints({
    network: "slow",
    interruptionsPerHour: 9,
    inputs: ["touch"],
    offlineRequired: true,
  });
  assert.deepEqual(cls.risks, ["offline", "interruption", "startup", "input", "distribution"]);
});

test("没有命中禁用默认值时返回空冲突列表", () => {
  const cls = classifyConstraints(base);
  assert.deepEqual(conflictsWithConstraints("cache-first-render", cls), []);
});

node --test test/core/constraints.test.ts

✔ 纯在线、低中断的产品只需要分发与输入约束 (1.238375ms)
✔ 离线优先会推翻“只做乐观写入”的默认做法 (0.181875ms)
✔ 高中断频率要求状态恢复与草稿持久化 (0.087625ms)
✔ 判断顺序稳定，风险列表可直接比对 (0.073625ms)
✔ 没有命中禁用默认值时返回空冲突列表 (0.070292ms)
ℹ tests 5
ℹ suites 0
ℹ pass 5
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 201.846666