《互联网产品的客户端架构·交易、增长与平台化》1.2 trade-lab 的第一条约束：金额与订单状态归谁所有

// file: src/core/ownership.ts
// tier: L1
// verify: node --test test/core/ownership.test.ts
import type { Money, Order, OrderState } from "./trade-model.ts";

export type Ownership = "server" | "client";

export type Field =
  | "price"
  | "stock"
  | "orderState"
  | "paymentResult"
  | "cartSelection"
  | "draftComment";

const OWNERS: Record<Field, Ownership> = {
  price: "server",
  stock: "server",
  orderState: "server",
  paymentResult: "server",
  cartSelection: "client",
  draftComment: "client",
};

export function ownerOf(field: Field): Ownership {
  return OWNERS[field];
}

export function clientMayWrite(field: Field): boolean {
  return OWNERS[field] === "client";
}

export interface AmountView {
  cents: number;
  currency: Money["currency"];
  source: "server" | "preview" | "stale";
  provisional: boolean;
}

export interface TimedAmount {
  money: Money;
  at: number;
}

// 服务端金额永远压过端上预览；预览只在服务端金额缺席时展示，并明确标注。
export function amountView(
  server: TimedAmount | null,
  preview: Money | null,
  now: number,
  ttlMs = 30_000,
): AmountView | null {
  if (server !== null) {
    const fresh = now - server.at <= ttlMs;
    return {
      cents: server.money.cents,
      currency: server.money.currency,
      source: fresh ? "server" : "stale",
      provisional: !fresh,
    };
  }
  if (preview !== null) {
    return {
      cents: preview.cents,
      currency: preview.currency,
      source: "preview",
      provisional: true,
    };
  }
  return null;
}

const STATE_ORDER: OrderState[] = [
  "created",
  "pending_payment",
  "paid",
  "shipped",
  "completed",
  "cancelled",
  "refunding",
  "refunded",
];

// 端上订单只接收服务端状态；本地状态只能用于展示，不能反向覆盖。
export function reconcileOrder(
  local: Order,
  remote: Order,
): { order: Order; conflicts: string[] } {
  const conflicts: string[] = [];
  if (local.id !== remote.id) {
    throw new Error("订单号不一致，不能合并");
  }
  if (local.state !== remote.state) {
    conflicts.push(`state:${local.state}->${remote.state}`);
  }
  if (local.total.cents !== remote.total.cents) {
    conflicts.push(`total:${local.total.cents}->${remote.total.cents}`);
  }
  if (local.lines.length !== remote.lines.length) {
    conflicts.push(`lines:${local.lines.length}->${remote.lines.length}`);
  }
  const order: Order = {
    ...remote,
    lines: remote.lines.map((line) => ({ ...line })),
    total: { ...remote.total },
  };
  return { order, conflicts };
}

export function stateRank(state: OrderState): number {
  return STATE_ORDER.indexOf(state);
}

$ node --test test/core/ownership.test.ts
✔ 金额、库存与订单状态归服务端 (0.508458ms)
✔ 勾选与草稿归端上 (0.07025ms)
✔ 服务端金额优先于预览 (0.087417ms)
✔ 过期的服务端金额标注 stale 而不是回退预览 (0.063834ms)
✔ 没有服务端金额时才展示预览并标记 provisional (0.055209ms)
✔ 两边都没有金额时返回 null (0.046416ms)
✔ 合并订单时服务端覆盖本地并列出差异 (0.841209ms)
✔ 订单号不同时拒绝合并 (0.243042ms)
✔ 状态次序可用于比较进度 (0.119583ms)
ℹ tests 9
ℹ suites 0
ℹ pass 9
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 132.681541