@posx/core 5.5.576 → 5.5.577

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 | 🔧 需修复 |