@posx/core 5.5.586 → 5.5.589

package/dev/export/xpos_retail_sample.csv

@@ -0,0 +1,38 @@
+Type,Name,SKU,Price,Stock,Is Internal,Min Order,Max Order,Image URL,Thumbnail URL,Sequence,Item UID,Print On Receipt,Discountable,Open Editor Panel,Is Delisted,Name Translations,Prices,PLU,Code
+category,Electronics,,,,,false,,,,,1,,,,,false,en:Electronics|zh:电子产品|vi:Điện tử,,001
+subcategory,Smartphones,,,,,false,,,,,0,,,,,false,en:Smartphones|zh:智能手机|vi:Điện thoại,,001-01
+product,iPhone 15 Pro,IP15PRO,1599.00,50,false,1,5,,,0,itm_ip15pro,true,true,false,false,en:iPhone 15 Pro|zh:iPhone 15 Pro|vi:iPhone 15 Pro,,PLU001,
+product,Samsung Galaxy S24,SGS24,1299.00,35,false,1,5,,,1,itm_sgs24,true,true,false,false,en:Samsung Galaxy S24|zh:三星 Galaxy S24|vi:Samsung Galaxy S24,,PLU002,
+product,Xiaomi 14,XM14,899.00,60,false,1,10,,,2,itm_xm14,true,true,false,false,en:Xiaomi 14|zh:小米 14|vi:Xiaomi 14,,PLU003,
+subcategory,Tablets,,,,,false,,,,,1,,,,,false,en:Tablets|zh:平板电脑|vi:Máy tính bảng,,001-02
+product,iPad Pro 12.9,IPADPRO,1799.00,20,false,1,3,,,0,itm_ipadpro,true,true,false,false,en:iPad Pro 12.9|zh:iPad Pro 12.9|vi:iPad Pro 12.9,,PLU004,
+product,Samsung Galaxy Tab S9,TABS9,1099.00,25,false,1,5,,,1,itm_tabs9,true,true,false,false,en:Samsung Galaxy Tab S9|zh:三星 Galaxy Tab S9|vi:Samsung Galaxy Tab S9,,PLU005,
+subcategory,Accessories,,,,,false,,,,,2,,,,,false,en:Accessories|zh:配件|vi:Phụ kiện,,001-03
+product,AirPods Pro 2,APP2,349.00,100,false,1,10,,,0,itm_app2,true,true,false,false,en:AirPods Pro 2|zh:AirPods Pro 2|vi:AirPods Pro 2,,PLU006,
+product,Apple Watch Ultra 2,AWU2,1199.00,30,false,1,5,,,1,itm_awu2,true,true,false,false,en:Apple Watch Ultra 2|zh:Apple Watch Ultra 2|vi:Apple Watch Ultra 2,,PLU007,
+product,USB-C Charger 65W,USBC65,45.00,200,false,1,20,,,2,itm_usbc65,true,true,false,false,en:USB-C Charger 65W|zh:USB-C 65W充电器|vi:Sạc USB-C 65W,,PLU008,
+category,Apparel,,,,,false,,,,,2,,,,,false,en:Apparel|zh:服装|vi:Quần áo,,002
+subcategory,Men,,,,,false,,,,,0,,,,,false,en:Men|zh:男装|vi:Nam,,002-01
+product,Cotton T-Shirt White,TSHIRT-W-M,29.90,150,false,1,10,,,0,itm_tshirt_wm,true,true,false,false,en:Cotton T-Shirt White|zh:白色纯棉T恤|vi:Áo thun cotton trắng,"[{""lookup_keys"":[""S""],""amount"":29.90,""name"":""S""},{""lookup_keys"":[""M""],""amount"":29.90,""name"":""M""},{""lookup_keys"":[""L""],""amount"":29.90,""name"":""L""},{""lookup_keys"":[""XL""],""amount"":32.90,""name"":""XL""}]",PLU009,
+product,Denim Jeans Slim,JEANS-S-M,89.90,80,false,1,5,,,1,itm_jeans_sm,true,true,false,false,en:Denim Jeans Slim|zh:修身牛仔裤|vi:Quần jeans ôm,"[{""lookup_keys"":[""30""],""amount"":89.90,""name"":""30""},{""lookup_keys"":[""32""],""amount"":89.90,""name"":""32""},{""lookup_keys"":[""34""],""amount"":89.90,""name"":""34""},{""lookup_keys"":[""36""],""amount"":94.90,""name"":""36""}]",PLU010,
+product,Running Shoes Pro,RUNPRO-M,159.00,45,false,1,3,,,2,itm_runpro_m,true,true,false,false,en:Running Shoes Pro|zh:专业跑鞋|vi:Giày chạy bộ Pro,"[{""lookup_keys"":[""40""],""amount"":159.00,""name"":""40""},{""lookup_keys"":[""41""],""amount"":159.00,""name"":""41""},{""lookup_keys"":[""42""],""amount"":159.00,""name"":""42""},{""lookup_keys"":[""43""],""amount"":159.00,""name"":""43""},{""lookup_keys"":[""44""],""amount"":164.00,""name"":""44""}]",PLU011,
+subcategory,Women,,,,,false,,,,,1,,,,,false,en:Women|zh:女装|vi:Nữ,,002-02
+product,Summer Dress Floral,DRESS-F-W,79.90,60,false,1,5,,,0,itm_dress_fw,true,true,false,false,en:Summer Dress Floral|zh:碎花夏裙|vi:Váy hoa mùa hè,"[{""lookup_keys"":[""S""],""amount"":79.90,""name"":""S""},{""lookup_keys"":[""M""],""amount"":79.90,""name"":""M""},{""lookup_keys"":[""L""],""amount"":79.90,""name"":""L""}]",PLU012,
+product,Yoga Leggings,YOGA-W,59.90,90,false,1,5,,,1,itm_yoga_w,true,true,false,false,en:Yoga Leggings|zh:瑜伽裤|vi:Quần legging yoga,"[{""lookup_keys"":[""S""],""amount"":59.90,""name"":""S""},{""lookup_keys"":[""M""],""amount"":59.90,""name"":""M""},{""lookup_keys"":[""L""],""amount"":59.90,""name"":""L""}]",PLU013,
+category,Home & Living,,,,,false,,,,,3,,,,,false,en:Home & Living|zh:家居生活|vi:Nhà & Đời sống,,003
+product,LED Desk Lamp,LEDLAMP,49.90,75,false,1,10,,,0,itm_ledlamp,true,true,false,false,en:LED Desk Lamp|zh:LED台灯|vi:Đèn bàn LED,,PLU014,
+product,Ceramic Mug Set 4pcs,MUGSET4,35.00,120,false,1,10,,,1,itm_mugset4,true,true,false,false,en:Ceramic Mug Set 4pcs|zh:陶瓷杯4件套|vi:Bộ cốc gốm 4 chiếc,,PLU015,
+product,Memory Foam Pillow,MFPILLOW,69.00,50,false,1,5,,,2,itm_mfpillow,true,true,false,false,en:Memory Foam Pillow|zh:记忆棉枕头|vi:Gối memory foam,,PLU016,
+product,Stainless Steel Bottle,SSBOTTLE,25.00,200,false,1,20,,,3,itm_ssbottle,true,true,false,false,en:Stainless Steel Bottle|zh:不锈钢保温杯|vi:Bình inox,,PLU017,
+category,Groceries,,,,,false,,,,,4,,,,,false,en:Groceries|zh:杂货|vi:Tạp hóa,,004
+product,Organic Honey 500g,HONEY500,18.90,80,false,1,10,,,0,itm_honey500,true,true,false,false,en:Organic Honey 500g|zh:有机蜂蜜500g|vi:Mật ong hữu cơ 500g,,PLU018,
+product,Extra Virgin Olive Oil 1L,EVOO1L,24.90,60,false,1,5,,,1,itm_evoo1l,true,true,false,false,en:Extra Virgin Olive Oil 1L|zh:特级初榨橄榄油1L|vi:Dầu olive extra virgin 1L,,PLU019,
+product,Premium Coffee Beans 1kg,COFFEE1K,32.00,100,false,1,10,,,2,itm_coffee1k,true,true,false,false,en:Premium Coffee Beans 1kg|zh:精品咖啡豆1kg|vi:Cà phê hạt cao cấp 1kg,,PLU020,
+product,Green Tea 100 bags,GTEA100,12.90,150,false,1,20,,,3,itm_gtea100,true,true,false,false,en:Green Tea 100 bags|zh:绿茶100包|vi:Trà xanh 100 túi,,PLU021,
+product,Dark Chocolate 200g,CHOCO200,8.90,200,false,1,30,,,4,itm_choco200,true,true,false,false,en:Dark Chocolate 200g|zh:黑巧克力200g|vi:Socola đen 200g,,PLU022,
+category,Sports & Outdoors,,,,,false,,,,,5,,,,,false,en:Sports & Outdoors|zh:运动户外|vi:Thể thao & Ngoài trời,,005
+product,Yoga Mat Premium,YOGAMAT,45.00,70,false,1,5,,,0,itm_yogamat,true,true,false,false,en:Yoga Mat Premium|zh:高端瑜伽垫|vi:Thảm yoga cao cấp,,PLU023,
+product,Resistance Bands Set,RBAND,29.90,90,false,1,10,,,1,itm_rband,true,true,false,false,en:Resistance Bands Set|zh:阻力带套装|vi:Bộ dây kháng lực,,PLU024,
+product,Jump Rope Pro,JUMPROPE,19.90,100,false,1,10,,,2,itm_jumprope,true,true,false,false,en:Jump Rope Pro|zh:专业跳绳|vi:Dây nhảy chuyên nghiệp,,PLU025,
+product,Camping Tent 2P,TENT2P,199.00,25,false,1,3,,,3,itm_tent2p,true,true,false,false,en:Camping Tent 2P|zh:双人帐篷|vi:Lều cắm trại 2 người,,PLU026,
+product,Hiking Backpack 40L,HKBP40L,129.00,40,false,1,5,,,4,itm_hkbp40l,true,true,false,false,en:Hiking Backpack 40L|zh:40L登山背包|vi:Ba lô leo núi 40L,,PLU027,

package/dev/harbor-harness-deployment.md

@@ -0,0 +1,78 @@
+# Harbor + Harness 部署总结
+
+## 服务端口
+
+| 服务        | 端口 | 说明           |
+|-------------|------|----------------|
+| Harbor      | 8081 | 容器镜像仓库   |
+| Harness     | 8082 | Git 代码托管   |
+| Harness SSH | 3022 | Git SSH        |
+| PostgreSQL  | 5433 | 数据库         |
+| Redis       | 6380 | 缓存           |
+
+## 外部访问
+
+| 服务    | 外部地址                | 内部地址     |
+|---------|-------------------------|--------------|
+| Harbor  | https://harbor.wyo.sg   | LAN_IP:8081  |
+| Harness | https://harness.wyo.sg  | LAN_IP:8082  |
+
+## Harbor 登录
+
+- URL: https://harbor.wyo.sg
+- 用户名: `admin`
+- 密码: `Harbor@2024!`
+
+## Harness 登录
+
+- URL: https://harness.wyo.sg
+- 用户名: `admin@harness.local`
+- 密码: `Harness@2024!`
+
+## PostgreSQL
+
+Host: `127.0.0.1:5433`
+
+| 数据库   | 用户名   | 密码           |
+|----------|----------|----------------|
+| postgres | postgres | Postgres@2024! |
+| harbor   | harbor   | Harbor@2024!   |
+| harness  | harness  | Harness@2024!  |
+
+## Redis
+
+- Host: `127.0.0.1:6380`
+- 密码: (无)
+- Harbor DB Index: 1, 2, 5, 6, 7
+
+## 文件位置
+
+```
+/opt/infra/docker-compose.yml      # PostgreSQL + Redis
+/opt/infra/config/postgresql.conf  # PostgreSQL 配置
+/opt/infra/config/redis.conf       # Redis 配置
+/opt/harbor/harbor.yml             # Harbor 配置
+/opt/harness/docker-compose.yml    # Harness 配置
+```
+
+## 管理命令
+
+```bash
+# 基础设施
+cd /opt/infra && docker compose up -d
+cd /opt/infra && docker compose down
+
+# Harbor
+cd /opt/harbor && docker compose up -d
+cd /opt/harbor && docker compose down
+
+# Harness
+cd /opt/harness && docker compose up -d
+cd /opt/harness && docker compose down
+```
+
+## Docker 登录 Harbor
+
+```bash
+docker login harbor.wyo.sg
+```

package/dev/incidents/2026-04-01-reprint-timeout.md

@@ -0,0 +1,33 @@
+# Incident: 重打收据超时失败
+
+- **日期:** 2026-04-01
+- **Issue:** #91
+- **Commit:** `441ec0c`
+- **影响范围:** 所有超过 1 小时的订单重打收据/厨房单
+
+## 现象
+
+用户在 12:27 重打一张 07:54 创建的订单收据，打印机无响应，PrintJob 被 worker 直接标记为 Failed。
+
+## 根因
+
+`reprintReceipt()` 和 `printLastKitchenSlips()` 从 DB 取出原始 PrintJob 复用，重置了 `uid`, `status`, `retries` 等字段，但**遗漏了 `created_at_timestamp`**。
+
+新 job 携带原始订单的创建时间 (07:54)，被 App 端 worker 的超时逻辑判定为超过 1 小时，直接标记 Failed。
+
+```
+原始 PrintJob (07:54) → 复制 → 换 uid → 重置 status=Queued
+                                        ❌ created_at_timestamp 仍为 07:54
+                                        → worker: 距今 > 1h → Failed
+```
+
+## 修复
+
+在两处 clone 路径中重置时间戳：
+
+- `invoice.service.ts` `reprintReceipt()`: `printJob.created_at_timestamp = Date.now()`
+- `invoice.service.ts` `printLastKitchenSlips()`: `updatedJob.created_at_timestamp = Date.now()`
+
+## 相关知识
+
+- [对象复用的隐式状态泄漏](../KB/object-clone-pitfalls.md)

package/dev/incidents/2026-05-06-searchable-field-design-pitfall.md

@@ -0,0 +1,37 @@
+# Boolean 字段默认值设计陷阱
+
+**日期:** 2026-05-06
+**类型:** 设计审查
+**严重程度:** 高（若未发现会导致生产事故）
+
+## 问题描述
+
+在为 Category 和 Item 添加 `is_searchable` 字段时，若设计为：
+- `is_searchable: boolean` 默认 `true`
+
+会导致兼容性问题：
+- 现有数据库记录没有此字段
+- JavaScript 读取时值为 `undefined`
+- `undefined` 是 falsy，逻辑上等同于 `false`
+- **结果：所有现有 item/category 突然变得不可搜索**
+
+## 正确方案
+
+使用**反向布尔字段**：`is_not_searchable`
+- 默认值：`false`（可搜索）
+- 现有数据无此字段 = `undefined` = falsy = 可搜索
+- 显式设为 `true` 才会排除搜索
+
+## 通用规则
+
+新增布尔字段时，确保：
+- `undefined`/缺失值 = 系统原有行为
+- 新行为需要显式设置 `true`
+
+**命名模式：**
+- 原行为是 X → 新字段应为 `is_not_X` 或 `disable_X`
+- 这样 `undefined` = 保持原行为
+
+## 相关文件
+
+- `src/types/product.type.ts` - ICategory, IItem 接口

package/dev/nginx-harbor-harness.conf

@@ -0,0 +1,84 @@
+# Harbor - 容器镜像仓库
+server {
+    listen 80;
+    server_name harbor.wyo.sg;
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name harbor.wyo.sg;
+
+    ssl_certificate /etc/nginx/ssl/wyo.sg/fullchain.pem;
+    ssl_certificate_key /etc/nginx/ssl/wyo.sg/privkey.pem;
+
+    # SSL 配置
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
+    ssl_prefer_server_ciphers off;
+    ssl_session_cache shared:SSL:10m;
+    ssl_session_timeout 1d;
+
+    # 重要：Docker 镜像上传无大小限制
+    client_max_body_size 0;
+    chunked_transfer_encoding on;
+
+    # 禁用缓冲，支持大文件流式传输
+    proxy_buffering off;
+    proxy_request_buffering off;
+
+    location / {
+        proxy_pass http://LAN_IP:8081;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # 超时设置（镜像推送可能耗时较长）
+        proxy_connect_timeout 900;
+        proxy_send_timeout 900;
+        proxy_read_timeout 900;
+    }
+}
+
+# Harness - Git 代码托管
+server {
+    listen 80;
+    server_name harness.wyo.sg;
+    return 301 https://$server_name$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name harness.wyo.sg;
+
+    ssl_certificate /etc/nginx/ssl/wyo.sg/fullchain.pem;
+    ssl_certificate_key /etc/nginx/ssl/wyo.sg/privkey.pem;
+
+    ssl_protocols TLSv1.2 TLSv1.3;
+    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
+    ssl_prefer_server_ciphers off;
+    ssl_session_cache shared:SSL:10m;
+    ssl_session_timeout 1d;
+
+    # Git 仓库可能较大
+    client_max_body_size 0;
+
+    location / {
+        proxy_pass http://LAN_IP:8082;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # WebSocket 支持（实时日志、通知等）
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+
+        # 超时设置
+        proxy_connect_timeout 300;
+        proxy_send_timeout 300;
+        proxy_read_timeout 300;
+    }
+}

package/dev/px-cli.md

@@ -0,0 +1,97 @@
+# px-cli
+
+Bun CLI project to interact with server using x-api-key method
+
+## Setup
+
+```bash
+cd px
+bun install
+cp .env.example .env   # fill in PX_BASE_URL, PX_API_KEY, PX_MERCHANT_UID
+```
+
+## Structure
+
+```
+px/
+├── package.json          # bun project, depends on @posx/core
+├── tsconfig.json
+├── .env.example
+├── index.ts              # entry point & router (cac)
+├── http.ts               # HTTP client with x-api-key auth
+└── commands/
+    ├── category.ts       # Category CRUD (types: ICategory)
+    └── product.ts        # Product CRUD (types: IItem)
+```
+
+## Dependencies
+
+- `@posx/core` — import types only (no service layer — no Dexie/IndexedDB in Bun):
+  - `IServiceOptions` — config typing in `http.ts`
+  - `ICategory` — category request/response typing
+  - `IItem` — product request/response typing
+- `@litepos/autoquery` — `QueryBuilder` for `list` action (autoquery via `sapi` endpoint)
+- `cac` — lightweight CLI framework (arg parsing, help text, subcommands)
+
+## Usage
+
+### Read (immediate)
+
+```bash
+# List via autoquery (sapi)
+px category list
+px category list --nameContains Drinks --take 10
+px product list
+px product list --nameContains Latte --take 10
+
+# Get by ID
+px category get --id 123
+px product get --id 456
+```
+
+### CUD — direct execution with dry-run
+
+```bash
+# Add
+px category add --name "Drinks" --type product --color "#ff0000" --icon "🍹"
+px category add --name "Drinks" --dry-run  # preview only
+
+# Update (always fetches first: GET → show diff → PATCH)
+px category update --id 123 --name "Beverages"
+px product update --id 456 --price 6.00 --dry-run  # preview diff
+
+# Delete
+px category delete --id 123
+px product delete --id 456 --dry-run  # preview record to be removed
+```
+
+### Update flow
+
+```
+1. GET /api/v5/merchants/{uid}/product/456
+2. Show diff:
+   - price: 5.00 → 6.00
+3. PATCH (or skip if --dry-run)
+```
+
+`--dry-run` 和正常执行都会先 GET，区别只在是否发送 PATCH。
+
+## API
+
+- **Base**: `https://lite-dev.posx.ai`
+- **Auth**: `x-api-key` header
+
+| Method   | Route                                               | Action           |
+|----------|-----------------------------------------------------|------------------|
+| `GET`    | `sapi/v5/merchants/{merchant_uid}/{module}`         | list (autoquery) |
+| `GET`    | `api/v5/merchants/{merchant_uid}/{module}/{id}`     | get              |
+| `PUT`    | `api/v5/merchants/{merchant_uid}/{module}/{method}` | add              |
+| `PATCH`  | `api/v5/merchants/{merchant_uid}/{module}/{id}`     | update           |
+| `DELETE` | `api/v5/merchants/{merchant_uid}/{module}/{id}`     | delete           |
+
+## Ref
+
+```bash
+curl -H "x-api-key: p8Hwl4A7ewynszODOOc05SJcqSP6YZDo2pevtZ" \
+  "https://lite-dev.posx.ai/api/v5/merchants/by-whatsapp-jid/6590992059@s.whatsapp.net"
+```

package/dev/test-logs/2026-02.md

@@ -0,0 +1,5 @@
+# 2026-02 测试日志
+
+| # | 分支 | 时间 | 变更 | 测试 | 🌐 | 问题 | 状态 |
+|---|------|------|------|------|:--:|------|------|
+| 1 | bugfix/rounding-half-up-51 | 02-03 10:45 | roundingStep 实现 round half up | 19/20 passed | ✗ | `service-charge-and-tax-exempt.test.ts` 期望值需更新 5877→5876.9 | 🔧 需修复 |