跳到主内容
版本: 1.x

架构

本页为开发人员和高级用户解释 WCPOS 的技术架构。

双部分系统​

WCPOS 被设计为一个由两部分组成的系统：

  1. PHP 插件： 托管在你的服务器上，这是一个相对较小的插件，它以 POS 专用端点扩展了 WooCommerce REST API。

  2. JavaScript 客户端： 该客户端在你的浏览器、桌面应用或 iOS/Android 应用中本地运行。

你可以将其视为两个独立的世界：

  • PHP 世界 是使用 WordPress 和 WooCommerce 进行数据管理的地方。
  • JavaScript 世界 保存着你的收银机所需商店数据的本地、离线可用副本，并针对快速搜索和即时响应进行了优化。
pos-client-woo-server

数据同步​

v1.10.0 中的变更

v1.10.0 以专用的同步引擎取代了先前的复制层。下面的概述只是简要版本 —— 完整说明请参阅同步引擎的工作原理。

客户端采用本地优先设计：每个界面都从设备的本地数据库读取和写入，而后台同步引擎负责让该数据库与 WooCommerce 保持收敛一致。该引擎不会盲目镜像你的整个商店 —— 它以你的界面实际需要的内容为依据来工作：

  • 变更检测： POS 使用条件请求轮询一份轻量的变更日志；空闲的商店只会返回一个无正文的 304。
  • 声明式需求： 界面声明它正在展示的内容，引擎则判断这是否需要发起请求，还是本地已能满足。
  • 预填充与通道： 有界的产品目录预填充、近期订单窗口，以及空闲时段的维护通道，会按你可为每台设备调整的计划填充并校验本地数据。
  • 持久化写入： 销售和编辑会在本地排队并发送到 WooCommerce，对于服务器拒绝的任何内容还提供可见的恢复方式。

同步的内容包括：产品和变体、类别/标签/品牌、客户、税率、优惠券（Pro）以及订单。支付网关在结账时获取。

架构优缺点​

优点 😊缺点 😟
搜索本地数据瞬间完成保持数据同步具有挑战性
缓存数据可在离线时使用受限于 WooCommerce REST API
能够为桌面、iOS 和 Android 创建更好的原生应用WordPress 主题和钩子无法自定义 POS 应用

本地数据库​

客户端将数据存储在每台设备的本地数据库中 —— 网页应用和桌面应用使用在 worker 中运行的 OPFS（源私有文件系统，Origin Private File System）存储，而移动应用通过文件系统引擎使用相同的磁盘格式。所有平台共用同一种存储格式和恢复工具。它提供：

  • 持久性： 数据在浏览器重启和设备重启后仍然存在
  • 性能： 快速查询而无网络延迟 —— 筛选、排序和分页都在存储层内部运行，因此只有可见的那一页记录会到达界面
  • 离线浏览： 缓存数据在没有互联网的情况下仍然可访问

每个站点 + 商店 + 收银员的组合都有自己的本地数据库，因此同一台设备上的收银员和商店绝不会共享本地数据。升级绝不会就地迁移本地数据库 —— 应用会从服务器重新下载，服务器始终是权威副本。

结账架构​

结账过程使用一个加载 WooCommerce 订单支付页面的 iframe/webview。这种方式：

  • 利用现有支付网关： 任何 WooCommerce 支付网关都可以在 POS 中工作
  • 保持安全性： 支付处理通过 WooCommerce 的安全基础设施进行
  • 降低复杂性： 无需重新实现支付网关集成

API 扩展​

PHP 插件以额外的端点扩展 WooCommerce REST API 来实现 POS 专用功能，这些端点注册在专用的 wcpos/v1 和 wcpos/v2 命名空间下 —— wcpos/v2 承载 v1.10.0 的同步接口，这也是应用与插件版本必须同步发布的原因。入门介绍请参见 WooCommerce REST API。

wcpos/v2 命名空间​

v1.10 引入了 wcpos/v2 REST 命名空间。同步功能位于此处，而之前由 wcpos/v1 提供的共享 POS 服务现在由 wcpos/v2 提供（wcpos/v1 的服务路由是对其 v2 实现的透传）。wcpos/v1 的路由为了向后兼容仍会注册，但已被冻结 —— 当前的客户端不再调用它们。

如果你要针对这些端点进行集成，以下几点很重要：

  • v2 路由始终注册。 旧的 woocommerce_pos_sync_api_enabled 选项已被移除；不再有开关来打开或关闭该 API。
  • 公开端点。 wcpos/v2/site、wcpos/v2/ping 和 wcpos/v2/echo 是公开的（用于能力和连通性探测，包括面向受限主机的传输回退）。
  • 订单以 UUID 为主键。 订单在传输中的标识是 UUID；旧有的 wooOrderId 字段已从订单拉取信封中退役。订单元数据在传输中通过单一的规范化器进行类型化。
  • 商品行定价存储已有文档说明，以便第三方同步兼容 —— 参见 POS 价格覆盖的存储方式。
  • POS 中的默认产品排序现在是按名称升序（之前为 menu_order, id）。
  • 移除了旧有方法。 若干旧的 API\Settings 控制器方法（例如 get_general_settings()、update_access_settings()、get_general_endpoint_args()、remove_license_transient()）已被移除；类别名仍然保留，但这些方法不再存在。
Pro 也遵循此拆分

WCPOS Pro 遵循相同的 V1/V2 拆分 —— 其共享服务被提升到 wcpos/v2，而其订单数据仍冻结在 v1。按商店范围划分的产品定价运行在 v2 通道上，且收银机的商店范围会被带入订单写入中，从而使多商店订单按正确的商店进行定价和计税。参见 Pro。