隔离模式服务器 (Island-Mode Server)
一个轻量级的Node服务器运行在物理站点，持有该站点Firestore数据子集的实时RxDB副本。网络正常时，它处于隐身状态；一旦网络中断，局域网内的kiosk/员工终端将自动故障转移至该服务器，站点依然可以继续接单、移动库存和切换硬件设备。重连后，离线期间产生的工作会同步回云端。贯穿一切的核心见解是：同步是双系统，而非单一系统——文档级别的RxDB复制负责状态同步，外加HTTP批量推送由云端自行处理的业务事件（如库存增量、审计摄入），两者缺一不可。
使用场景
- 站点必须在网络中断期间仍能执行真实的写入操作（预订、库存、硬件控制），而不仅仅是缓存读取。
- 终端基于浏览器（PWA/kiosk），需要透明地完成故障转移。
- Firestore是云端唯一的事实来源，并保持这一角色。
不适用场景
- 纯粹的读取缓存或仅需Firestore内置离线持久化的PWA——Firebase SDK已能实现，无需额外服务器。
- 使用其他云端数据库（如Supabase/Postgres）——复制层的概念通用，但此处所有模板均为Firestore专属。
- 站点间的多主同步——本设计严格采用中心辐射模式，云端作为事实来源，采用最后写入获胜的策略。
架构
Internet
|
+--------+---------+
| 云端 (SSoT) | Firestore + 公开API + cron状态标记
+--------+---------+
| |
RxDB 复制 HTTP批量推送 (重连)
| |
+-+-------------+-+
| 本地服务器 | Node/NestJS + RxDB，局域网 :443 通过 nginx TLS
+--------+--------+
|
LAN — kiosk PWA、员工PWA、硬件控制器
关键事实
- 每次云端写入一个被复制的集合时，必须打上检查点字段 (
serverTimestamp: FieldValue.serverTimestamp()) 和_deleted: false——RxDB Firestore插件通过serverTimestamp > checkpoint拉取数据；未打时间戳的文档永远不会被复制拉取。 - 三种复制层级，按集合选择：只拉取（站点消费的配置）、双向（站点变更的操作状态）、只推送（站点产生的日志）。选错集合的层级是主要的设计错误。
- 内存型RxDB存储意味着离线重启会丢失所有离线工作。 副本会从Firestore重新填充，但离线期间创建的文档将丢失。请明确决策存储的权衡——参见replication.md。
- 批量推送是至少一次语义，因此云端摄入必须幂等——用客户端生成的ID标识每次应用，并跳过已应用的记录。
- 推送过滤器防止回环：双向推送仅推送标记为
_offlineCreated/_locallyModified的文档，从而避免拉取的云端文档被推送回去。 - 终端优先使用云端——只有在连续N次健康检查失败后才会启用故障转移，且离线期间必须持续扫描本地服务器，而非仅在切换时扫描一次。
硬性规则
切勿在未授权的情况下暴露云端同步摄入端点。 这些端点会执行库存增量和注入订单。必须使用共享密钥头部作为最低要求。
在线时切勿宽松验证离线员工令牌。 不验证直接解码的回退方案仅可为局域网环境下的安全折衷；它必须仅在服务器真正离线时启用，否则将成为签名验证的旁路。
切勿重置尚未确认同步的事务对应的本地库存增量。 仅在收到确认后按ID重置，否则离线销售要么重复计数，要么从可用库存中消失。
切勿让本地服务器自行发明云端负责的业务规则（如营业时间、定价）。通过复制配置并基于配置计算，否则隔离模式的行为将与网站产生偏差。
快速开始
- 将集合划分为层级，并明确分界点——architecture.md。
- 搭建RxDB + 复制，使用自定义令牌认证和安全规则——replication.md。
- 添加重连时的批量推送和幂等云端摄入——sync-flush.md。
- 配置心跳/状态链和客户端故障转移——network-failover.md。
- 保护本地API（员工/kiosk/硬件HMAC/静态令牌）——auth.md。
- 镜像终端所需的云端端点——local-api.md。
- 现场部署：systemd、nginx TLS、mDNS、监控——operations.md。
参考目录
| 场景 | 触发关键词 | 参考文档 |
|---|---|---|
| 拓扑、层级、分界点、重命名表 | 只拉取、双向、只推送、双路径、locationId、冲突 | architecture.md |
| 副本搭建、模式、检查点陷阱 | RxDB、replicateFirestore、serverTimestamp、custom token、storage-memory、firestore.rules | replication.md |
| 重连批量推送、库存增量、摄入 | flushAll、幂等、FieldValue.increment、localDelta、syncedIds | sync-flush.md |
| 故障检测和API切换 | heartbeat、lastHeartbeatAt、cron、NetworkManager、apiBaseUrl、failover | network-failover.md |
| 本地API认证 | AuthGuard、HMAC、重放窗口、离线JWT回退、kiosk key | auth.md |
| 离线端点和写入 | availability、mutex、离线预订、签到、定价库存过滤器 | local-api.md |
| 现场部署和运维手册 | systemd、nginx、自签名TLS、mDNS、avahi、journalctl、回滚 | operations.md |
| 分类账：审计变更、保留、新增的内容 | provenance、audit、deviations、kept deliberately | provenance.md |
针对信任关键逻辑（HMAC验证、离线令牌解码、在真实RxDB上的增量展开、故障转移重新扫描）的vitest测试套件通过情况： assets/behavior.test.ts——请将其带入目标项目中作为回归覆盖。