接到一颗芯片上，接上来的机器就成了终端 — POS、自助点单、后厨屏一次搞定

你数过一间咖啡馆里有多少台终端吗？点单机、柜台 POS、刷卡机、送去后厨的纸单，还有库存台账。终端不少，彼此却不说话。于是中间靠人来接。店员看着点单机进来的单子朝后厨喊一声，收款在另一台机器上做，库存晚上再手工对。

再往里塞一台终端，不可能是答案。只是店里本来就有的那台收款终端，不会把画面分出来而已。

这篇文章记录的，是在那台收款终端旁边立一个服务端，把平板、PC 和后厨屏接上去 —— 直到接上来的机器各自变成自助点单机、POS 和后厨显示为止。三台机器一个 App 都没做。 而且 刷卡授权那条路一行都没碰。 下面每一张画面，都是真实运行后渲染出来的像素原样截取的。

先看结果 —— 三块画面

客人在平板上点单。

同一时刻，后厨屏上已经挂着这两单。

在柜台发起收款，终端返回授权。

三块画面是 同一个服务端给出的三份不同定义。并不存在平板专用 App、POS 专用 App、后厨专用 App。

全景

terminal_sim (C)                store_server (Dart · mcp_server)         客户端 ×3
  收款终端端点     ──serial/usb──▶   持有订单与销售状态             ──MCP──▶  平板    ui://kiosk
  只回答授权                          提供 3 份画面定义              ──MCP──▶  PC      ui://pos
                                      通过适配器把请求转给终端        ──MCP──▶  后厨    ui://kds

这里，收款终端的里面不是我们的代码。 卡数据、授权判定、VAN 通信，都原样待在终端已认证的安全区里。我们做的只是问一句「这笔金额请授权」再接住答案。这个不对称，就是这篇文章的全部。

---

① 一个服务端给出三块画面的地方

这是本文的中心。设备接上来说要自己的画面，就把那块画面给它。

const screens = <String, (String, String, Map<String, dynamic>)>{
  'ui://kiosk': ('Self Order Kiosk', 'Customer-facing order screen', kioskDefinition),
  'ui://pos':   ('Counter POS', 'Owner-facing sales and payment screen', posDefinition),
  'ui://kds':   ('Kitchen Display', 'Kitchen order queue', kdsDefinition),
};

screens.forEach((uri, spec) {
  final (name, description, definition) = spec;
  server.addResource(
    uri: uri,
    name: name,
    description: description,
    mimeType: 'application/json',
    handler: (requestedUri, params) async => ReadResourceResult(
      contents: [
        ResourceContentInfo(
          uri: requestedUri,
          mimeType: 'application/json',
          text: jsonEncode(definition),
        ),
      ],
    ),
  );
});

「机器成为终端」这句话的实体，就是这张三行的表。 想加一块画面 —— 想在窗边挂一台等号显示屏 —— 就在这里加一行。不是去做一个装到那台机器上的 App，而是往这张表里加一条。

客户端这侧就这么短。角色就是画面的名字。

const _role = String.fromEnvironment('ROLE', defaultValue: 'kiosk');

const _screenForRole = <String, String>{
  'kiosk': 'ui://kiosk',
  'pos': 'ui://pos',
  'kds': 'ui://kds',
};

// 连上服务端，取回属于自己的画面，交给运行时。
final uri = _screenForRole[_role] ?? 'ui://kiosk';
final resource = await client.readResource(uri);
final definition = jsonDecode(resource.contents.first.text!) as Map<String, dynamic>;

final runtime = MCPUIRuntime();
await runtime.initialize(definition);

后厨屏用 --dart-define=ROLE=kds 启动，柜台 PC 用 ROLE=pos 启动。是同一个二进制。 这个文件里没有任何一行描述后厨画面长什么样 —— 那是服务端知道的事。

② 收款终端适配器 —— 本文最可能被抄走的代码

发一个授权请求，等一个答案。真的就只做这些，而这份「薄」本身就是主张。

/// Send one request and wait for the answer bearing the same id.
///
/// Matched by id rather than by arrival order, because a link is a stream,
/// not a call stack. A status query slipping in while an authorisation is
/// still in flight must not steal the authorisation's answer.
Future<Map<String, dynamic>> call(
  String tool, [
  Map<String, dynamic> args = const {},
]) async {
  final id = _nextId++;
  final completer = Completer<Map<String, dynamic>>();
  _pending[id] = completer;

  final request = jsonEncode({'id': id, 'tool': tool, 'args': args});
  transcript.add('=> $request');
  _proc.stdin.writeln(request);

  final reply = await completer.future.timeout(
    requestTimeout,
    onTimeout: () {
      _pending.remove(id);
      throw TimeoutException('terminal did not answer $tool', requestTimeout);
    },
  );
  if (reply['ok'] != true) {
    throw StateError('terminal refused $tool: ${reply['error']}');
  }
  return (reply['result'] as Map).cast<String, dynamic>();
}

把超时设成 3 秒的理由写下来。这是算出来的，不是口味。

/// How long to wait for the terminal.
///
/// The simulator answers in 70–160 ms. A real authorisation is dominated by
/// the VAN round trip, so the order of magnitude is the same. Three seconds
/// is set deliberately far above that distribution. A timeout here must mean
/// "the terminal is gone," not "it was slower than usual." Tighten it to a
/// few hundred milliseconds and a perfectly good authorisation turns into a
/// failure — and a payment reported as failed that actually went through is
/// the worst outcome this adapter can produce.
final Duration requestTimeout;

然后是收款处理器。看 这段代码不做什么 更要紧。

handler: (args) async {
  final unpaid = _orders.where((o) => o['paid'] == false).toList();
  if (unpaid.isEmpty) { _notice = 'Nothing to charge'; return _state(); }
  final amount = unpaid.fold<int>(0, (sum, o) => sum + (o['price'] as int));

  final started = DateTime.now();
  try {
    final result = await terminal.call('terminal.authorize', {'amount': amount});
    final elapsed = DateTime.now().difference(started);
    for (final o in unpaid) { o['paid'] = true; }
    _salesTotal += amount;
    _lastApproval = '${result['approvalCode']} (${result['last4']})';
    _lastRoundTripMs = elapsed.inMilliseconds;
  } on TimeoutException {
    // A timeout is not a decline. We do not know what the terminal did,
    // so we say we do not know. We do not decide it failed on our own.
    _notice = 'Terminal did not answer — check the receipt before retrying';
  }
  return _state();
}

不读卡。不判断这位客人能不能付。不连 VAN。数清是多少钱，去问，把答案记下来。 「问」和「答案」之间发生的一切，都发生在这个样例从没打开过的已认证硬件里面。

请留意超时的处理。收款里最危险的状态不是被拒，而是 不知道。授权其实已经通过，我们却按失败处理，客人就会钱出去了、单子却没有。所以不知道的时候，就在画面上写不知道。