@posx/core 5.5.393 → 5.5.395

package/memo/technical-docs/05_DATA_LAYER.md

@@ -0,0 +1,375 @@
+# 05 - 数据层
+
+> AI 上下文索引：Dexie、IndexedDB、服务工厂、HTTP客户端、类型系统、查询过滤
+
+## 架构概述
+
+采用 **混合数据架构**：本地 IndexedDB (Dexie) + 远程 API 同步
+
+## 1. 数据库实现
+
+### Dexie (IndexedDB 包装器)
+
+**位置:** `src/service.factory.ts`
+**版本:** Dexie v3.2.4
+**Schema 版本:** v28
+
+```typescript
+// 初始化
+public dataSource: Dexie;
+public async initializeDatabase() {
+  this.dataSource = await new Dexie(this.options.database.name);
+  this.dataSource.version(28).stores(dbSchemas);
+  this.status = DbStatus.CONNECTED;
+}
+```
+
+### 数据库表结构
+
+**基础索引模式:**
+```typescript
+const baseSchema = 'uid, updated_at, created_at, deleted_at, _timestamp, id_in_server, created_at_timestamp';
+```
+
+**完整表清单 (28 张):**
+
+| 表名 | 额外索引 | 用途 |
+|------|---------|------|
+| items | name, barcode, codename, sequence | 商品 |
+| sections | sequence | 区域 |
+| section_items | sequence | 桌位 |
+| categories | sequence | 分类 |
+| invoices | type, status, table_uid | 发票 |
+| employees | role_uid | 员工 |
+| payment_methods | is_cash | 支付方式 |
+| configs | - | 配置 |
+| shifts | status | 班次 |
+| tills | employee_uid | 收银机 |
+| printers | - | 打印机 |
+| print_jobs | status, printer_type, device_uid_to_print | 打印任务 |
+| print_templates | type | 打印模板 |
+| employee_roles | name, is_default | 角色 |
+| order_displays | invoice_uid, status | 厨显 |
+| storages | model | 通用存储 |
+| menus | - | 菜单 |
+| reports | - | 报表 |
+
+### 数据库操作
+
+**位置:** `src/services/abstract.service.ts`
+
+```typescript
+// 创建/更新
+async saveOne(item: T): Promise<T>
+async saveMany(items: T[]): Promise<T[]>
+
+// 读取
+async getOne(uid: string): Promise<T>
+async getOneByParams(params: Partial<T>): Promise<T | null>
+async getAll(): Promise<T[]>
+async getMany(params, options): Promise<GetManyResult<T>>
+
+// 实时查询
+public liveQuery<T>(expr: () => T): Observable<T>
+
+// 清理
+async clearTableData(tableName: string)
+async dropDatabase()
+```
+
+## 2. 存储工具
+
+### 通用存储模型
+
+**位置:** `src/types/storage.type.ts`
+
+```typescript
+interface IStorage<T = Record<string, unknown> | unknown[]> extends IAppBaseModel {
+    uid: string;
+    model: 'discounts' | string;
+    data: T;
+}
+```
+
+**用途:** 存储折扣等复杂对象，通过 `storages` 表持久化。
+
+## 3. API 服务
+
+### HTTP 客户端工厂
+
+**位置:** `src/utils/http.utils.ts`
+
+```typescript
+export function createInstance(baseURL: string, uid: string, token: string) {
+  const instance = axios.create({
+    baseURL: baseURL,
+    timeout: 20000,
+    headers: {
+      'x-device-uid': uid,
+      'Authorization': `Bearer ${token}`
+    }
+  });
+
+  instance.interceptors.response.use(
+    (response) => response.data,
+    (error) => Promise.reject(error)
+  );
+
+  return instance;
+}
+```
+
+### 服务层架构
+
+```
+AppCoreService (基础 CRUD)
+    │
+    ├── AppLocalService (本地，无远程)
+    │
+    └── AppRemoteService (CRUD + API 同步)
+```
+
+### API 端点模式
+
+```
+PUT    /api/v5/merchants/{merchant_uid}/{module}/{method}  # 创建
+PATCH  /api/v5/merchants/{merchant_uid}/{module}/{id}      # 更新单个
+PATCH  /api/v5/merchants/{merchant_uid}/{module}           # 批量更新
+DELETE /api/v5/merchants/{merchant_uid}/{module}/{id}      # 删除
+```
+
+## 4. 服务工厂
+
+**位置:** `src/service.factory.ts`
+
+### 服务注册表 (18 个服务)
+
+```typescript
+const serviceProvider = new Map([
+  ['Item', ItemService],
+  ['Section', SectionService],
+  ['SectionItem', SectionItemService],
+  ['Category', CategoryService],
+  ['Config', ConfigService],
+  ['Shift', ShiftService],
+  ['Till', TillService],
+  ['Employee', EmployeeService],
+  ['PaymentMethod', PaymentMethodService],
+  ['Invoice', InvoiceService],
+  ['Report', AppReportService],
+  ['Printer', PrinterService],
+  ['PrintJob', PrintJobService],
+  ['PrintTemplate', PrintTemplateService],
+  ['EmployeeRole', EmployeeRoleService],
+  ['OrderDisplay', OrderDisplayService],
+  ['Storage', StorageService],
+  ['Menu', MenuService]
+]);
+```
+
+### 服务获取方式
+
+```typescript
+// 按类引用
+const invoiceService = await factory.getService<InvoiceService>(InvoiceService);
+
+// 按名称
+const itemService = await factory.getServiceByName('Item');
+```
+
+### 运行模式
+
+```typescript
+enum ServiceMode {
+  LOCAL = 'local',    // 仅本地
+  CLOUD = 'cloud'     // 远程同步
+}
+
+interface IServiceOptions {
+  mode: ServiceMode;
+  base_url: string;
+  device_uid: string;
+  merchant_uid: string;
+  token: string;
+  database: { version: number; name: string };
+}
+```
+
+## 5. 数据模型
+
+### 模型层次
+
+```
+IAppCoreModel (核心接口)
+    │
+    └── AppCoreModel (抽象基类)
+        │
+        ├── IAppBaseModel (+ name)
+        │   └── AppBaseModel
+        │       │
+        │       └── IAppExtraModel (+ description)
+        │           └── AppExtraModel
+```
+
+### 核心字段
+
+```typescript
+interface IAppCoreModel {
+  uid: string;                   // nanoid 主键
+  updated_at: Date;
+  created_at: Date;
+  created_at_timestamp: number;
+  deleted_at: Date | null;       // 软删除标记
+  _timestamp: number;            // 同步跟踪
+  id_in_server: number;          // 远程 ID
+}
+```
+
+### UID 前缀
+
+| 前缀 | 实体 |
+|------|------|
+| inv_ | Invoice |
+| itm_ | Item |
+| emp_ | Employee |
+| cat_ | Category |
+| sec_ | Section |
+| sit_ | SectionItem |
+
+### 类型定义文件
+
+| 文件 | 主要类型 | 行数 |
+|------|---------|------|
+| invoice.type.ts | IInvoice, IInvoiceLine | ~540 |
+| product.type.ts | IItem, ICategory | ~600 |
+| config.type.ts | IAppConfig | ~760 |
+| printer.type.ts | IPrinter, IPrintJob | ~350 |
+| payment.type.ts | IPayment, IPaymentMethod | ~270 |
+
+## 6. 查询过滤
+
+**位置:** `src/libs/FindOptions.ts`
+
+### 过滤函数
+
+```typescript
+export const Include = (query?: string) =>
+  (val) => isEmpty(query) || val.includes(query);
+
+export const In = (query?: never[]) =>
+  (val) => isEmpty(query) || query.includes(val);
+
+export const Between = (begin: number, end: number) =>
+  (val) => val > begin && val < end;
+
+export const Not = (query?: any) =>
+  (val) => val != query;
+
+export const filterByParams = (params) =>
+  (values) => !values['deleted_at'] && Object.keys(params).every(...);
+```
+
+### 使用示例
+
+```typescript
+// 按分类查询
+await itemService.getMany(
+  { category_uid: 'cat_123' },
+  { page: 1, pageSize: 20 }
+);
+
+// 自定义过滤
+await itemService.getMany(
+  { price: Between(10, 50) },
+  { pageSize: -1 }
+);
+```
+
+## 7. 同步与持久化
+
+### 软删除
+
+```typescript
+// 标记删除
+await itemService.deleteOne(item);  // 设置 deleted_at
+
+// 硬删除
+await itemService.hardDeleteOne(item);  // 从数据库移除
+```
+
+### 时间戳跟踪
+
+- `created_at` - ISO 日期
+- `created_at_timestamp` - Unix 毫秒
+- `updated_at` - 每次保存更新
+- `_timestamp` - 冲突解决
+
+### 实时更新
+
+```typescript
+const itemsObservable = itemService.liveQuery(() =>
+  itemService.getAll()
+);
+
+itemsObservable.subscribe(items => {
+  // 数据库变更时自动更新
+});
+```
+
+## 8. 架构图
+
+```
+┌─────────────────────────────────────────┐
+│            Application Layer             │
+└──────────────────┬──────────────────────┘
+                   │
+┌──────────────────▼──────────────────────┐
+│         ServiceFactory (DI)              │
+│  • 初始化 Dexie 数据库                   │
+│  • 管理 HTTP 客户端                      │
+│  • 按需实例化服务                        │
+└──────────────────┬──────────────────────┘
+                   │
+        ┌──────────┴──────────┐
+        │                     │
+        ▼                     ▼
+┌──────────────────┐   ┌──────────────────┐
+│   HTTP Client    │   │   IndexedDB      │
+│   (Axios)        │   │   (Dexie)        │
+└────────┬─────────┘   └────────┬─────────┘
+         │                      │
+         ▼                      ▼
+  ┌──────────────────────────────────────┐
+  │      AppRemoteService (Abstract)      │
+  │  CRUD + API 同步 + liveQuery          │
+  └────────────┬─────────────────────────┘
+               │
+  ┌────────────┴──────────────────────────┐
+  │         Domain Services (18)          │
+  │  Invoice, Item, Printer, Config...    │
+  └───────────────────────────────────────┘
+```
+
+## 文件结构
+
+```
+src/
+├── service.factory.ts     # DI 容器 & Schema
+├── services/
+│   ├── abstract.service.ts  # 基础 CRUD
+│   ├── app.service.ts       # 16 个领域服务
+│   ├── invoice.service.ts   # 发票计算
+│   ├── printer.service.ts   # 打印管理
+│   └── ods.service.ts       # 厨显系统
+├── types/                   # 12+ 类型文件
+├── libs/
+│   └── FindOptions.ts       # 查询过滤
+└── utils/
+    └── http.utils.ts        # Axios 工厂
+```
+
+## 相关文档
+
+- [01_ARCHITECTURE.md](./01_ARCHITECTURE.md) - 整体架构
+- [02_CORE_BUSINESS.md](./02_CORE_BUSINESS.md) - 核心业务
+- [06_CROSS_PLATFORM.md](./06_CROSS_PLATFORM.md) - 跨平台

package/memo/technical-docs/06_CROSS_PLATFORM.md

@@ -0,0 +1,246 @@
+# 06 - 跨平台能力
+
+> AI 上下文索引：Capacitor、Electron、ESC/POS、打印机、Socket、字符编码
+
+## 跨平台概述
+
+本库支持多平台运行：Web、Electron、Capacitor (iOS/Android)
+
+## 1. Capacitor 插件
+
+**依赖:** `@capacitor/core@5.4.2`, `@awesome-cordova-plugins/network-interface@6.6.0`
+
+### 网络接口
+
+**位置:** `src/services/printer.service.ts`
+
+```typescript
+import { NetworkInterface } from '@awesome-cordova-plugins/network-interface';
+
+// 获取 WiFi IP 地址
+const ipAddress: NetworkInfo = await NetworkInterface.getWiFiIPAddress();
+```
+
+**用途:**
+- 检测设备 WiFi IP
+- 计算子网掩码
+- 扫描子网发现打印机
+
+## 2. Electron 集成
+
+### 类型定义
+
+**位置:** `src/libs/electron.d.ts`
+
+```typescript
+interface Window {
+  electronSocket: {
+    open: (host: string, port: number) => Promise<boolean>;
+    write: (data: number[]) => Promise<boolean>;
+    close: () => Promise<boolean>;
+    shutdownWrite: () => Promise<boolean>;
+    onData: (callback) => void;
+    onClose: (callback) => void;
+    onError: (callback) => void;
+    onEvent: (callback) => () => void;
+  };
+}
+```
+
+### Socket 桥接
+
+**位置:** `src/libs/electron.socket.ts`
+
+**状态机:**
+```
+CLOSED (0) → OPENING (1) → OPENED (2) → CLOSING (3)
+```
+
+**回调系统:**
+```typescript
+public onData: ((data: Uint8Array) => void) | null = null;
+public onClose: ((hadError: boolean) => void) | null = null;
+public onError: ((error: string) => void) | null = null;
+```
+
+**方法:**
+- `open(host, port, success?, error?)` - 建立连接
+- `write(data, success?, error?)` - 发送数据
+- `close(success?, error?)` - 关闭连接
+
+**初始化:**
+```typescript
+// service.factory.ts
+ElectronSocket.setWindow(win);
+```
+
+## 3. 打印机硬件
+
+### ESC/POS 实现
+
+**位置:** `src/libs/escpos.printer.ts`
+
+**Socket 抽象:**
+```typescript
+function getSocket(): any {
+  return typeof Socket === 'undefined' ? new ElectronSocket() : new Socket();
+}
+```
+
+### 连接类型
+
+```typescript
+enum PrinterConnections {
+  USB,
+  WINDOWS_DRIVER,
+  ETHERNET,        // 主要用于网络打印机
+  BLUETOOTH,
+  BUILTIN
+}
+```
+
+### 打印协议
+
+```typescript
+enum PrinterProtocols {
+  ESCPOS,  // 收据打印机、厨显
+  TSPL     // 标签打印机
+}
+```
+
+### 打印操作
+
+| 方法 | 功能 |
+|------|------|
+| `testPrint(template)` | 测试打印 |
+| `connect(ip, port, timeout)` | TCP 连接 |
+| `write(resultByte, timeout)` | 发送命令 |
+| `interpret(template)` | 编码打印命令 |
+
+### 高级打印功能
+
+- 自定义字体大小
+- 表格 (列宽计算)
+- QR 码 & 条形码
+- 图片 (多种抖动算法)
+- 钱箱控制
+- 文本换行
+
+### 字符编码支持
+
+**位置:** `src/libs/viscii.encoding.ts`
+
+```typescript
+enum Codepages {
+  SimplifiedChinese = 'cp936',
+  TraditionalChinese = 'cp950',
+  Japanese = 'shiftjis',
+  Vietnamese = 'windows1258',
+  // ... 20+ 国际编码
+}
+```
+
+**越南语 VISCII:**
+- UTF-8 到 VISCII 转换
+- 100+ 越南语字符映射
+- 不支持字符回退到 ASCII
+
+## 4. 打印机服务
+
+**位置:** `src/services/printer.service.ts`
+
+### 网络发现
+
+```typescript
+searchPrinters(refresh: boolean, port: number): Promise<string[]>
+```
+
+**流程:**
+1. 获取设备 WiFi IP
+2. 计算子网掩码
+3. TCP 扫描端口 1-254
+4. 缓存结果到本地数据库
+
+### 设备管理
+
+- `getPhysicalPrintersFromNode()` - 查询连接的打印机
+- `getUnpairedNode()` - 发现未配对节点
+- `pairNode(nodeUid)` - 配对设备
+
+### 打印机配置
+
+```typescript
+interface IPrinter {
+  device_uid: string;
+  type: PrinterType;           // Receipt, Kitchen, Kiosk, Label
+  protocol: PrinterProtocols;   // ESCPOS, TSPL
+  connection_type: PrinterConnections;
+  driver_printer_name: string;
+  ip_address?: string;
+  print_sequence?: number;
+  retries: number;
+  print_times: number;
+}
+```
+
+### 打印任务队列
+
+```typescript
+interface IPrintJob {
+  printer_uid: string;
+  connection_type: PrinterConnections;
+  protocol: PrinterProtocols;
+  device_uid_to_print: string;
+  save_only: boolean;
+  status: PrintJobStatus;  // queued, printed, failed, expired
+}
+```
+
+## 5. 离线支持
+
+### Dexie 集成
+
+- **离线优先架构** 使用 IndexedDB
+- 28 个数据库版本，自动迁移
+- 打印机、打印任务、配置等表
+- 离线时支持打印队列
+
+## 6. 未实现功能
+
+| 功能 | 状态 |
+|------|------|
+| CodePush | 未实现 |
+| 热更新 | 未实现 |
+| 动态 Bundle 加载 | 未实现 |
+
+更新通过标准应用商店渠道处理。
+
+## 能力汇总
+
+| 能力 | 实现 | 状态 |
+|------|------|------|
+| Capacitor | v5.4.2 - 网络插件 | ✅ 活跃 |
+| Electron | IPC Socket 桥接 | ✅ 活跃 |
+| 原生桥接 | ElectronSocket 抽象 | ✅ 活跃 |
+| 打印协议 | ESC/POS, TSPL | ✅ 活跃 |
+| 设备检测 | Cordova NetworkInterface | ✅ 活跃 |
+| 字符编码 | VISCII, UTF-8, 20+ 编码 | ✅ 活跃 |
+| 离线支持 | Dexie IndexedDB | ✅ 活跃 |
+| CodePush | - | ❌ 未实现 |
+
+## 关键文件
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `src/libs/electron.socket.ts` | 93 | 跨平台核心 |
+| `src/libs/escpos.printer.ts` | 563 | 打印机硬件 |
+| `src/services/printer.service.ts` | 200+ | 网络检测 |
+| `src/types/printer.type.ts` | 325+ | 配置类型 |
+| `src/libs/viscii.encoding.ts` | 55 | 编码支持 |
+| `src/service.factory.ts` | 175 | 服务设置 |
+
+## 相关文档
+
+- [01_ARCHITECTURE.md](./01_ARCHITECTURE.md) - 整体架构
+- [02_CORE_BUSINESS.md](./02_CORE_BUSINESS.md) - 核心业务 (打印部分)
+- [05_DATA_LAYER.md](./05_DATA_LAYER.md) - 数据层