@posx/core 5.5.392 → 5.5.395

package/jest.config.cjs

@@ -1,36 +1,36 @@
-// jest.config.js
-module.exports = {
-  preset: 'ts-jest',
-  testEnvironment: 'jsdom',
-  setupFilesAfterEnv: ['<rootDir>/jest.setup.cjs'],
-  transform: {
-    '^.+\\.ts$': ['ts-jest', {
-      tsconfig: {
-        module: 'commonjs',
-        esModuleInterop: true,
-      }
-    }],
-    '^.+\\.(mjs|js)$': ['ts-jest', {
-      tsconfig: {
-        allowJs: true,
-        module: 'commonjs',
-        esModuleInterop: true,
-      }
-    }]
-  },
-  transformIgnorePatterns: [
-    'node_modules/(?!(.pnpm|nanoid|@litepos|dexie|lodash-es)/)', // Transform ESM packages
-  ],
-  testMatch: [
-    '<rootDir>/src/test/**/*.test.ts'
-  ],
-  moduleNameMapper: {
-    '\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$': '<rootDir>/scripts/testMock.cjs',
-    '\\.(css|less)$': '<rootDir>/scripts/testMock.cjs',
-    '^nanoid$': '<rootDir>/src/test/__mocks__/nanoid.js',
-    '^dexie$': '<rootDir>/src/test/__mocks__/dexie.js',
-    '^@awesome-cordova-plugins/network-interface$': '<rootDir>/src/test/__mocks__/@awesome-cordova-plugins/network-interface.js',
-    '^canvas$': '<rootDir>/scripts/testMock.cjs'
-  },
-  moduleFileExtensions: ['web.js', 'js', 'web.ts', 'ts', 'web.tsx', 'tsx', 'json', 'web.jsx', 'jsx', 'node'],
-};
+// jest.config.js
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'jsdom',
+  setupFilesAfterEnv: ['<rootDir>/jest.setup.cjs'],
+  transform: {
+    '^.+\\.ts$': ['ts-jest', {
+      tsconfig: {
+        module: 'commonjs',
+        esModuleInterop: true,
+      }
+    }],
+    '^.+\\.(mjs|js)$': ['ts-jest', {
+      tsconfig: {
+        allowJs: true,
+        module: 'commonjs',
+        esModuleInterop: true,
+      }
+    }]
+  },
+  transformIgnorePatterns: [
+    'node_modules/(?!(.pnpm|nanoid|@litepos|dexie|lodash-es)/)', // Transform ESM packages
+  ],
+  testMatch: [
+    '<rootDir>/src/test/**/*.test.ts'
+  ],
+  moduleNameMapper: {
+    '\\.(jpg|jpeg|png|gif|eot|otf|webp|svg|ttf|woff|woff2|mp4|webm|wav|mp3|m4a|aac|oga)$': '<rootDir>/scripts/testMock.cjs',
+    '\\.(css|less)$': '<rootDir>/scripts/testMock.cjs',
+    '^nanoid$': '<rootDir>/src/test/__mocks__/nanoid.js',
+    '^dexie$': '<rootDir>/src/test/__mocks__/dexie.js',
+    '^@awesome-cordova-plugins/network-interface$': '<rootDir>/src/test/__mocks__/@awesome-cordova-plugins/network-interface.js',
+    '^canvas$': '<rootDir>/scripts/testMock.cjs'
+  },
+  moduleFileExtensions: ['web.js', 'js', 'web.ts', 'ts', 'web.tsx', 'tsx', 'json', 'web.jsx', 'jsx', 'node'],
+};

package/jest.setup.cjs

@@ -1,80 +1,80 @@
-// Jest setup file to polyfill File and Blob APIs
-// This ensures consistent behavior across different Node.js versions and test environments
-
-// Polyfill Blob.text() if not available
-if (typeof Blob !== 'undefined' && !Blob.prototype.text) {
-  Blob.prototype.text = async function() {
-    const reader = new FileReader();
-    return new Promise((resolve, reject) => {
-      reader.onload = () => resolve(reader.result);
-      reader.onerror = reject;
-      reader.readAsText(this);
-    });
-  };
-}
-
-// Polyfill FileReader if not available
-if (typeof FileReader === 'undefined') {
-  global.FileReader = class FileReader {
-    result = null;
-    error = null;
-    onload = null;
-    onerror = null;
-
-    readAsText(blob) {
-      try {
-        // For our polyfilled Blob
-        if (blob.parts) {
-          this.result = blob.parts.join('');
-        } else if (typeof blob === 'string') {
-          this.result = blob;
-        } else {
-          this.result = String(blob);
-        }
-
-        if (this.onload) {
-          setTimeout(() => this.onload({ target: this }), 0);
-        }
-      } catch (err) {
-        this.error = err;
-        if (this.onerror) {
-          setTimeout(() => this.onerror({ target: this }), 0);
-        }
-      }
-    }
-  };
-}
-
-// Polyfill Blob if not available (for Node.js < 18)
-if (typeof Blob === 'undefined') {
-  global.Blob = class Blob {
-    constructor(parts = [], options = {}) {
-      this.parts = parts;
-      this.type = options.type || '';
-      this.size = parts.reduce((acc, part) => {
-        return acc + (typeof part === 'string' ? part.length : part.length || 0);
-      }, 0);
-    }
-
-    async text() {
-      return this.parts.join('');
-    }
-
-    async arrayBuffer() {
-      const text = await this.text();
-      const buffer = Buffer.from(text);
-      return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
-    }
-  };
-}
-
-// Polyfill File if not available (for Node.js < 18)
-if (typeof File === 'undefined') {
-  global.File = class File extends global.Blob {
-    constructor(bits, name, options = {}) {
-      super(bits, options);
-      this.name = name;
-      this.lastModified = options.lastModified || Date.now();
-    }
-  };
-}
+// Jest setup file to polyfill File and Blob APIs
+// This ensures consistent behavior across different Node.js versions and test environments
+
+// Polyfill Blob.text() if not available
+if (typeof Blob !== 'undefined' && !Blob.prototype.text) {
+  Blob.prototype.text = async function() {
+    const reader = new FileReader();
+    return new Promise((resolve, reject) => {
+      reader.onload = () => resolve(reader.result);
+      reader.onerror = reject;
+      reader.readAsText(this);
+    });
+  };
+}
+
+// Polyfill FileReader if not available
+if (typeof FileReader === 'undefined') {
+  global.FileReader = class FileReader {
+    result = null;
+    error = null;
+    onload = null;
+    onerror = null;
+
+    readAsText(blob) {
+      try {
+        // For our polyfilled Blob
+        if (blob.parts) {
+          this.result = blob.parts.join('');
+        } else if (typeof blob === 'string') {
+          this.result = blob;
+        } else {
+          this.result = String(blob);
+        }
+
+        if (this.onload) {
+          setTimeout(() => this.onload({ target: this }), 0);
+        }
+      } catch (err) {
+        this.error = err;
+        if (this.onerror) {
+          setTimeout(() => this.onerror({ target: this }), 0);
+        }
+      }
+    }
+  };
+}
+
+// Polyfill Blob if not available (for Node.js < 18)
+if (typeof Blob === 'undefined') {
+  global.Blob = class Blob {
+    constructor(parts = [], options = {}) {
+      this.parts = parts;
+      this.type = options.type || '';
+      this.size = parts.reduce((acc, part) => {
+        return acc + (typeof part === 'string' ? part.length : part.length || 0);
+      }, 0);
+    }
+
+    async text() {
+      return this.parts.join('');
+    }
+
+    async arrayBuffer() {
+      const text = await this.text();
+      const buffer = Buffer.from(text);
+      return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+    }
+  };
+}
+
+// Polyfill File if not available (for Node.js < 18)
+if (typeof File === 'undefined') {
+  global.File = class File extends global.Blob {
+    constructor(bits, name, options = {}) {
+      super(bits, options);
+      this.name = name;
+      this.lastModified = options.lastModified || Date.now();
+    }
+  };
+}

package/memo/technical-docs/01_ARCHITECTURE.md

@@ -0,0 +1,147 @@
+# 01 - 整体架构
+
+> AI 上下文索引：服务工厂、依赖注入、Dexie数据库、Axios HTTP、服务层次、事件驱动
+
+## 架构概述
+
+本项目是 **核心服务库**，非前端应用。采用服务导向架构，通过工厂模式进行依赖注入。
+
+## 入口点
+
+**主入口:** `src/index.ts`
+- Barrel 导出所有公共 API
+- 导出服务工厂、领域模型、工具函数
+
+**服务工厂:** `src/service.factory.ts`
+- 初始化 Dexie 数据库 (28 张表)
+- 创建 Axios HTTP 客户端
+- 按需实例化领域服务
+- 管理数据库连接状态
+
+## 服务层次结构
+
+```
+IAppCoreService<T>     # 读操作接口
+    │
+    ├── IAppLocalService<T>   # 本地 CRUD (无远程)
+    │
+    └── IAppRemoteService<T>  # 远程 API CRUD
+            │
+            ├── addOne()     → PUT
+            ├── updateOne()  → PATCH
+            ├── updateMany() → PATCH
+            └── deleteOne()  → DELETE (软删除)
+```
+
+## 数据库架构
+
+**技术:** Dexie v3.2.4 (IndexedDB 包装器)
+**版本:** v28
+**表数量:** 28 张
+
+### 核心表
+
+| 表名 | 索引 | 用途 |
+|------|------|------|
+| items | uid, name, barcode, codename, sequence | 商品 |
+| sections | uid, sequence | 区域 |
+| section_items | uid, sequence | 桌位 |
+| categories | uid, sequence | 分类 |
+| invoices | uid, type, status, table_uid | 发票 |
+| employees | uid, role_uid | 员工 |
+| payment_methods | uid, is_cash | 支付方式 |
+| printers | uid | 打印机 |
+| print_jobs | uid, status, printer_type, device_uid_to_print | 打印任务 |
+| configs | uid | 配置 |
+| shifts | uid, status | 班次 |
+| tills | uid, employee_uid | 收银机 |
+
+### 基础索引模式
+
+```typescript
+const baseSchema = 'uid, updated_at, created_at, deleted_at, _timestamp, id_in_server, created_at_timestamp';
+```
+
+## 事件驱动模式
+
+### SignalR 集成
+
+**Hub 消息类型:** `src/types/hub.message.type.ts`
+
+```typescript
+enum HubMessageType {
+    PaynowEvent = 'paynow_event',
+    SmoochPaymentEvent = 'smooch_payment_event',
+    SyncInvoice = 'sync_invoice',
+}
+```
+
+### Dexie Live Query
+
+```typescript
+public liveQuery<T>(expr: () => T): Observable<T> {
+    return liveQuery(expr);
+}
+```
+- 提供响应式数据更新
+- 通过 RxJS Observable 集成
+
+## Electron Socket 桥接
+
+**位置:** `src/libs/electron.socket.ts`
+
+**状态机:**
+- CLOSED (0) → OPENING (1) → OPENED (2) → CLOSING (3)
+
+**用途:**
+- Electron IPC 通信
+- 硬件控制 (打印机、钱箱)
+
+## 插件系统
+
+### Handlebars 插件注册
+
+**位置:** `src/helpers/helpers.register.ts`
+
+用于动态模板渲染：
+- `string.helpers.ts` - 字符串处理
+- `comparison.helpers.ts` - 比较逻辑
+
+## 关键文件
+
+| 文件路径 | 大小 | 核心职责 |
+|----------|------|---------|
+| `src/service.factory.ts` | 6KB | 服务实例化、数据库初始化 |
+| `src/services/abstract.service.ts` | 8KB | 基础 CRUD 接口 |
+| `src/services/app.service.ts` | 82KB | 领域服务集合 |
+| `src/services/invoice.service.ts` | 107KB | 发票生命周期、计算引擎 |
+| `src/libs/electron.socket.ts` | 3KB | Electron IPC 桥接 |
+| `src/libs/escpos.printer.ts` | 18KB | ESC/POS 打印命令 |
+
+## 架构模式
+
+1. **服务工厂模式** - 延迟初始化服务
+2. **仓储模式** - AppRemoteService 提供数据访问抽象
+3. **适配器模式** - Dexie + Axios 双重持久化
+4. **观察者模式** - Dexie liveQuery + RxJS
+5. **模板方法模式** - 抽象服务基类
+6. **策略模式** - 多种计算流程 (CalcFlow)
+7. **事件驱动** - SignalR 实时同步
+
+## 运行模式
+
+```typescript
+enum ServiceMode {
+  LOCAL = 'local',    // 仅客户端模式
+  CLOUD = 'cloud'     // 远程 API 同步模式
+}
+```
+
+**LOCAL:** 仅使用 IndexedDB，无远程调用
+**CLOUD:** 与远程 API 同步，维护本地缓存
+
+## 相关文档
+
+- [PROJECT_OVERVIEW.md](./PROJECT_OVERVIEW.md) - 项目总览
+- [05_DATA_LAYER.md](./05_DATA_LAYER.md) - 数据层详解
+- [06_CROSS_PLATFORM.md](./06_CROSS_PLATFORM.md) - 跨平台能力

package/memo/technical-docs/02_CORE_BUSINESS.md

@@ -0,0 +1,292 @@
+# 02 - 核心业务逻辑
+
+> AI 上下文索引：发票计算、支付处理、打印系统、数据同步、员工认证、权限管理
+
+## 1. 发票/账单系统
+
+**核心文件:**
+- `src/services/invoice.service.ts` (2800+ 行)
+- `src/types/invoice.type.ts`
+
+### 服务层次
+
+```
+InvoiceBaseService      # 计算引擎
+    │
+    ├── LineOperationService    # 行项操作
+    │
+    └── InvoiceOperationService # 发票生命周期
+```
+
+### 计算流程
+
+```
+1. 行项计算
+   ├─ 数量 × 单价
+   ├─ 修改器合计
+   └─ 行小计
+
+2. 折扣阶段 (CalcFlow)
+   ├─ AfterSubtotal
+   ├─ AfterServiceCharge
+   └─ AfterGrandTotal
+
+3. 服务费
+   └─ 仅堂食适用
+
+4. 税费计算
+   ├─ 内含 (inclusive)
+   └─ 外加 (exclusive)
+
+5. 配送费
+
+6. 舍入
+   ├─ 现金规则
+   └─ 非现金规则
+
+7. 最终调整
+   ├─ 积分抵扣
+   └─ 零钱计算
+```
+
+### 发票状态流转
+
+```
+Open → OnHold/Paying → Paid/Void
+                    ↓
+         PayAtCounter, Calibration (特殊状态)
+```
+
+### 发票类型
+
+| 类型 | 服务费 | 配送费 |
+|------|--------|--------|
+| dine_in | ✓ | ✗ |
+| take_out | ✗ | ✗ |
+| delivery | ✗ | ✓ |
+
+### 核心方法
+
+| 方法 | 功能 |
+|------|------|
+| `calculate()` | 主计算协调 |
+| `calculateLines()` | 行级小计 |
+| `calculateDiscount()` | 折扣计算 |
+| `calculateTax()` | 税费计算 |
+| `calculateServiceCharge()` | 服务费 |
+| `calculateRounding()` | 舍入处理 |
+| `createInvoice()` | 创建发票 |
+| `payInvoice()` | 支付发票 |
+| `voidInvoice()` | 作废发票 |
+| `sliceInvoice()` | 拆分发票 |
+
+## 2. 支付处理
+
+**核心文件:**
+- `src/types/payment.type.ts`
+- `src/services/app.service.ts`
+
+### 支付实体
+
+```typescript
+interface IPayment {
+  tender_amount: number;       // 实付金额
+  change_amount: number;       // 找零
+  payment_method: IPaymentMethod;
+  payment_method_history: [];  // 变更历史
+}
+
+interface IPaymentMethod {
+  is_cash: boolean;
+  enable_drawer: boolean;      // 钱箱支持
+  enable_receipt: boolean;     // 小票打印
+  is_integrated: boolean;      // 集成支付
+  enable_credit_validation: boolean;
+  enable_customer_validation: boolean;
+}
+```
+
+### 支付状态
+
+```typescript
+enum PaymentStatus {
+  payment_started,
+  payment_completed,
+  payment_failed,
+  payment_cancelled
+}
+```
+
+### 支付操作
+
+- `addPayment()` - 添加支付
+- `removePayment()` - 移除支付
+- `changePayments()` - 更换支付方式
+- `syncStandardPaymentMethods()` - 同步支付方式
+
+## 3. 打印系统
+
+**核心文件:**
+- `src/services/printer.service.ts`
+- `src/types/printer.type.ts`
+- `src/libs/escpos.printer.ts`
+
+### 打印机类型
+
+| 类型 | 用途 |
+|------|------|
+| ReceiptPrinter | 收据打印 |
+| KitchenPrinter | 厨房小票 |
+| KioskPrinter | 自助终端 |
+| LabelPrinter | 标签打印 |
+| OrderPrinter | 订单打印 |
+| CheckPrinter | 账单打印 |
+
+### 打印服务能力
+
+- 物理打印机发现
+- 打印机配对
+- 网络扫描 (子网探测)
+- 钱箱控制
+- 模板渲染 (Handlebars)
+- ESC/POS 命令生成
+
+### 打印任务队列
+
+```typescript
+interface IPrintJob {
+  printer_uid: string;
+  connection_type: PrinterConnections;
+  protocol: PrinterProtocols;
+  status: PrintJobStatus;  // queued, printed, failed, expired
+  device_uid_to_print: string;
+  save_only: boolean;
+}
+```
+
+## 4. 数据同步
+
+**核心文件:**
+- `src/services/abstract.service.ts`
+- `src/services/app.service.ts`
+
+### 远程服务 API
+
+```
+PUT    /api/v5/merchants/{merchant_uid}/{module}/{method}  # 创建
+PATCH  /api/v5/merchants/{merchant_uid}/{module}/{id}      # 更新
+DELETE /api/v5/merchants/{merchant_uid}/{module}/{id}      # 删除
+```
+
+### 同步策略
+
+- **双键设计:** `uid` (本地 nanoid) + `id_in_server` (远程 ID)
+- **软删除:** `deleted_at` 字段标记
+- **冲突检测:** `outdatedInvoice`, `outdatedSectionItem`
+
+### 同步操作
+
+| 操作 | 方法 |
+|------|------|
+| 发票数据同步 | `syncInvoiceData()` |
+| 支付方式同步 | `syncStandardPaymentMethods()` |
+| 报表同步 | `syncStandardReports()` |
+
+## 5. 员工认证
+
+**核心文件:**
+- `src/types/employee.type.ts`
+- `src/services/app.service.ts`
+
+### 认证方法
+
+```typescript
+// 登录验证 (bcryptjs, 12 rounds)
+await bcryptjs.compare(password, user.password)
+
+// 密码修改
+await bcryptjs.hash(newPassword, 12)
+```
+
+### 员工实体
+
+```typescript
+interface IEmployee {
+  user_uid: string;
+  name: string;
+  email: string;
+  password: string;  // hashed
+  role_uid: string;
+  language: string;
+  can_login: boolean;
+}
+```
+
+### 认证操作
+
+- `login()` - 员工登录
+- `createEmployee()` - 创建员工
+- `changePassword()` - 修改密码
+
+## 6. 权限管理
+
+**核心文件:**
+- `src/types/role.type.ts`
+
+### 角色实体
+
+```typescript
+interface IEmployeeRole extends IAppBaseModel {
+  permissions: string[];  // 权限字符串数组
+  is_default: boolean;
+}
+```
+
+### 权限设计
+
+- 字符串形式权限
+- 数组存储多权限
+- 通过 `role_uid` 关联员工
+- 服务端验证 (非本地)
+
+## 横切关注点
+
+### 配置系统 (ConfigService)
+
+包含 20+ 子系统配置：
+- General, Till, Report, Receipt, Kitchen
+- Tax, Rounding, Charges, Currency
+- Inventory, PAX, CRM, Loyalty Program
+- Online Order, Kiosk, Order Display
+
+### 订单显示系统 (ODS)
+
+```typescript
+// 订单状态流转
+Preparing → ReadyForPickup
+
+// 操作
+toPickUp(), toPreparing(), undo()
+```
+
+### 工具函数
+
+- `preciseRound()` - 精确舍入 (2 位小数)
+- `humanizedData()` - 日期格式化
+- CSV 导入/导出
+
+## 关键文件汇总
+
+| 文件 | 大小 | 职责 |
+|------|------|------|
+| invoice.service.ts | 107KB | 发票完整生命周期 |
+| app.service.ts | 82KB | 通用 CRUD、配置、支付、报表 |
+| abstract.service.ts | 8KB | 服务基类 |
+| printer.service.ts | 9KB | 打印机发现与管理 |
+| ods.service.ts | 4KB | 订单显示操作 |
+
+## 相关文档
+
+- [01_ARCHITECTURE.md](./01_ARCHITECTURE.md) - 整体架构
+- [05_DATA_LAYER.md](./05_DATA_LAYER.md) - 数据层
+- [06_CROSS_PLATFORM.md](./06_CROSS_PLATFORM.md) - 跨平台