아키텍처
이 페이지는 개발자와 고급 사용자를 위한 WCPOS의 기술 아키텍처를 설명합니다.
두 부분 시스템
WCPOS는 두 부분으로 이루어진 시스템으로 설계되었습니다:
-
PHP 플러그인: 서버에 호스팅되는 이 비교적 작은 플러그인은 WooCommerce REST API를 POS 전용 엔드포인트로 확장합니다.
-
JavaScript 클라이언트: 브라우저, 데스크톱 앱 또는 iOS/Android 앱에서 로컬로 실행됩니다.
이를 두 개의 별도 세계로 생각할 수 있습니다:
- _PHP 세계_는 WordPress와 WooCommerce를 사용하여 데이터 관리가 이루어지는 곳입니다.
- _JavaScript 세계_는 계산대에 필요한 스토어 데이터의 로컬 사본을 오프라인에서도 사용할 수 있게 보관하며, 빠른 검색과 즉각적인 응답에 최적화되어 있습니다.
데이터 동기화
v1.10.0은 기존 복제 계층을 전용 동기화 엔진으로 대체했습니다. 아래 요약은 간단한 설명이며, 전체 설명은 동기화 엔진 작동 방식에 있습니다.
클라이언트는 로컬 우선(local-first) 방식입니다: 모든 화면이 기기의 로컬 데이터베이스를 읽고 쓰며, 백그라운드 동기화 엔진이 이 데이터베이스와 WooCommerce를 수렴시킵니다. 이 엔진은 스토어 전체를 무작정 미러링하지 않고, 화면이 실제로 필요로 하는 것을 기준으로 동작합니다:
- 변경 감지: POS는 조건부 요청으로 가벼운 변경 로그를 조회합니다. 변화가 없는 스토어는 본문 없는
304하나로 응답합니다. - 선언된 수요: 화면이 무엇을 표시하는지 선언하면, 엔진이 그것이 요청을 필요로 하는지 아니면 이미 로컬에서 해결되는지 판단합니다.
- 시드와 레인: 범위가 제한된 카탈로그 시드, 최근 주문 윈도우, 유휴 시간 유지 관리 레인이 기기별로 조정 가능한 일정에 따라 로컬 데이터를 채우고 검증합니다.
- 내구성 있는 쓰기: 판매와 편집 내용은 로컬에 대기했다가 WooCommerce로 전송되며, 서버가 거부한 항목은 눈에 보이는 복구 절차를 제공합니다.
동기화 대상: 상품 및 변형, 카테고리/태그/브랜드, 고객, 세율, 쿠폰(Pro), 주문. 결제 게이트웨이는 결제 시점에 가져옵니다.
아키텍처 장단점
| 장점 😊 | 단점 😟 |
|---|---|
| 로컬 데이터 검색이 즉시 이루어짐 | 데이터 동기화 유지가 어려움 |
| 오프라인에서 사용 가능한 캐시 데이터 | WooCommerce REST API의 제약을 받음 |
| 데스크톱, iOS 및 Android에 대한 더 나은 네이티브 앱 생성 가능 | WordPress 테마 및 훅이 POS 앱을 커스터마이즈할 수 없음 |
로컬 데이터베이스
클라이언트는 각 기기의 로컬 데이터베이스에 데이터를 저장합니다 — 웹과 데스크톱 앱은 워커에서 실행되는 OPFS(Origin Private File System) 저장소를 사용하고, 모바일 앱은 파일 시스템 엔진을 통해 동일한 디스크 형식을 사용합니다. 모든 플랫폼이 하나의 저장 형식과 복구 도구를 공유합니다. 이는 다음과 같은 이점을 제공합니다:
- 지속성: 브라우저 재시작과 기기 재부팅 후에도 데이터가 유지됨
- 성능: 네트워크 지연 없는 빠른 쿼리 — 필터링, 정렬, 페이지네이션이 저장 계층 내부에서 실행되므로 화면에 보이는 페이지의 행만 UI로 전달됨
- 오프라인 브라우징: 인터넷 없이도 캐시 데이터 접근 가능
사이트 + 스토어 + 계산원 조합마다 별도의 로컬 데이터베이스가 생성되므로, 한 기기에서 계산원과 스토어가 로컬 데이터를 공유하는 일은 없습니다. 업그레이드 시 로컬 데이터베이스를 제자리에서 마이그레이션하지 않으며, 항상 정본인 서버에서 앱이 다시 다운로드합니다.
체크아웃 아키텍처
체크아웃 프로세스는 WooCommerce 주문 결제 페이지를 로드하는 iframe/webview를 사용합니다. 이 접근 방식은:
- 기존 결제 게이트웨이를 활용: 모든 WooCommerce 결제 게이트웨이가 POS에서 작동할 수 있음
- 보안 유지: 결제 처리는 WooCommerce의 안전한 인프라를 통해 이루어짐
- 복잡성 감소: 결제 게이트웨이 통합을 재구현할 필요 없음
API 확장
PHP 플러그인은 POS 전용 기능을 위한 추가 엔드포인트로 WooCommerce REST API를 확장하며, 이 엔드포인트는 전용 네임스페이스 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())가 제거되었습니다. 클래스 별칭은 유지되지만 해당 메서드는 유지되지 않습니다.
WCPOS Pro는 동일한 V1/V2 분리를 따릅니다 — 공유 서비스는 wcpos/v2로 승격되는 반면 주문 데이터는 v1에 동결된 상태로 유지됩니다. 스토어 범위 상품 가격은 v2 레인에서 실행되며, 계산대의 스토어 범위가 주문 쓰기에 함께 전달되어 여러 스토어 주문이 올바른 스토어를 기준으로 가격과 세금을 계산합니다. Pro를 참조하세요.