@posx/core 5.5.392 → 5.5.395

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) - 数据层

package/memo/technical-docs/07_SIMILARITY_INDEX.md

@@ -0,0 +1,195 @@
+# 07 - 相似性索引
+
+> AI 上下文索引：功能对照、服务模式、代码复用、架构模式
+
+## 服务层模式对照
+
+### 基础服务模式
+
+所有领域服务继承相同的基础架构：
+
+| 模式 | 基类 | 特点 |
+|------|------|------|
+| 本地服务 | AppLocalService | 仅本地 CRUD，无远程调用 |
+| 远程服务 | AppRemoteService | CRUD + API 同步 |
+| 计算服务 | InvoiceBaseService | 复杂业务计算 |
+
+### 服务对照表
+
+| 服务 | 基类 | CRUD | API 同步 | 特殊功能 |
+|------|------|------|---------|---------|
+| ItemService | AppRemoteService | ✓ | ✓ | 条码搜索 |
+| CategoryService | AppRemoteService | ✓ | ✓ | 序列排序 |
+| SectionService | AppRemoteService | ✓ | ✓ | 序列排序 |
+| SectionItemService | AppRemoteService | ✓ | ✓ | 桌位管理 |
+| InvoiceService | 多层继承 | ✓ | ✓ | 计算引擎 |
+| EmployeeService | AppRemoteService | ✓ | ✓ | 密码哈希 |
+| ConfigService | AppRemoteService | ✓ | ✓ | 配置验证 |
+| PrinterService | AppRemoteService | ✓ | ✓ | 网络发现 |
+| PrintJobService | AppRemoteService | ✓ | ✓ | 队列管理 |
+| ReportService | AppRemoteService | ✓ | ✓ | 聚合计算 |
+
+## 数据模型模式
+
+### 基础模型继承
+
+```
+IAppCoreModel
+    │
+    └── IAppBaseModel (+ name)
+            │
+            └── IAppExtraModel (+ description)
+```
+
+### 模型对照
+
+| 模型 | 基类 | 额外字段 | 软删除 |
+|------|------|---------|--------|
+| Item | IAppExtraModel | barcode, codename, price | ✓ |
+| Category | IAppBaseModel | sequence | ✓ |
+| Section | IAppBaseModel | sequence | ✓ |
+| Invoice | IAppCoreModel | status, type, lines | ✓ |
+| Employee | IAppCoreModel | password, role_uid | ✓ |
+| Printer | IAppBaseModel | ip_address, type | ✓ |
+| PrintJob | IAppCoreModel | status, template | ✓ |
+
+## 功能模式对照
+
+### CRUD 操作模式
+
+所有服务共享统一的 CRUD 模式：
+
+```typescript
+// 创建
+await service.saveOne(entity);
+
+// 读取
+await service.getOne(uid);
+await service.getAll();
+await service.getMany(params, options);
+
+// 更新
+await service.updateOne(id, changes);
+
+// 删除
+await service.deleteOne(entity);      // 软删除
+await service.hardDeleteOne(entity);  // 硬删除
+```
+
+### 序列排序模式
+
+以下实体共享序列排序功能：
+
+| 实体 | 索引字段 | 用途 |
+|------|---------|------|
+| Item | sequence | 商品排序 |
+| Category | sequence | 分类排序 |
+| Section | sequence | 区域排序 |
+| SectionItem | sequence | 桌位排序 |
+| PaymentMethod | sequence | 支付方式排序 |
+
+### 状态管理模式
+
+**发票状态:**
+```
+Open → OnHold → Paying → Paid/Void
+```
+
+**班次状态:**
+```
+Open → Closed
+```
+
+**打印任务状态:**
+```
+queued → printing → printed/failed/expired
+```
+
+## 打印相关对照
+
+### 打印机类型对照
+
+| 类型 | 用途 | 模板 | 协议 |
+|------|------|------|------|
+| ReceiptPrinter | 收据 | 收据模板 | ESC/POS |
+| KitchenPrinter | 厨房 | 厨房模板 | ESC/POS |
+| LabelPrinter | 标签 | 标签模板 | TSPL |
+| KioskPrinter | 自助 | 收据模板 | ESC/POS |
+| OrderPrinter | 订单 | 订单模板 | ESC/POS |
+
+### 连接类型对照
+
+| 类型 | 平台 | 用途 |
+|------|------|------|
+| ETHERNET | 全平台 | 网络打印机 |
+| USB | Electron | USB 打印机 |
+| BLUETOOTH | Mobile | 蓝牙打印机 |
+| WINDOWS_DRIVER | Windows | 系统驱动 |
+
+## 计算模式对照
+
+### 金额计算流程
+
+| 阶段 | 方法 | 输入 | 输出 |
+|------|------|------|------|
+| 行计算 | calculateLines() | 行项 | 行小计 |
+| 折扣 | calculateDiscount() | 小计 | 折扣后金额 |
+| 服务费 | calculateServiceCharge() | 小计 | +服务费 |
+| 税费 | calculateTax() | 金额 | +税费 |
+| 舍入 | calculateRounding() | 总计 | 舍入后总计 |
+
+### 折扣计算流程对照
+
+| CalcFlow | 应用时机 | 用例 |
+|----------|---------|------|
+| AfterSubtotal | 小计后 | 一般折扣 |
+| AfterServiceCharge | 服务费后 | 会员折扣 |
+| AfterGrandTotal | 总计后 | 现金折扣 |
+
+## 复用指南
+
+### 添加新服务
+
+1. 创建类型定义 `src/types/xxx.type.ts`
+2. 继承 `AppRemoteService<T>`
+3. 在 `serviceProvider` Map 注册
+4. 在 `dbSchemas` 添加表结构
+
+### 添加新模型
+
+1. 继承 `IAppBaseModel` 或 `IAppCoreModel`
+2. 定义 UID 前缀
+3. 实现类继承 `AppBaseModel`
+
+### 添加新打印模板
+
+1. 在 `configs/` 添加 JSON 模板
+2. 定义 Handlebars 模板内容
+3. 注册到 PrintTemplateService
+
+## 文件对照
+
+### 服务文件
+
+| 文件 | 服务数量 | 复杂度 |
+|------|---------|--------|
+| app.service.ts | 16 | 高 |
+| invoice.service.ts | 3 (继承链) | 非常高 |
+| printer.service.ts | 1 | 中 |
+| ods.service.ts | 1 | 低 |
+| abstract.service.ts | 3 (基类) | 中 |
+
+### 类型文件
+
+| 文件 | 接口数量 | 行数 |
+|------|---------|------|
+| invoice.type.ts | 15+ | ~540 |
+| config.type.ts | 20+ | ~760 |
+| product.type.ts | 10+ | ~600 |
+| printer.type.ts | 8+ | ~350 |
+
+## 相关文档
+
+- [01_ARCHITECTURE.md](./01_ARCHITECTURE.md) - 整体架构
+- [02_CORE_BUSINESS.md](./02_CORE_BUSINESS.md) - 核心业务
+- [05_DATA_LAYER.md](./05_DATA_LAYER.md) - 数据层

package/memo/technical-docs/CHECKPOINT.md

@@ -0,0 +1,46 @@
+# 文档检查点
+
+## 当前基准
+
+| 项目 | 值 |
+|------|---|
+| 分支 | develop |
+| Commit | `59212b4da4c2850861bf04bf35f2cf34246b3a2b` |
+| 短 Hash | `59212b4` |
+| 时间 | 2026-01-20 16:18:57 +0800 |
+| 消息 | 5.5.388 |
+
+## 文档完成状态
+
+| 文档 | 状态 | 日期 |
+|------|------|------|
+| PROJECT_OVERVIEW.md | ✅ 完成 | 2026-01-22 |
+| 01_ARCHITECTURE.md | ✅ 完成 | 2026-01-22 |
+| 02_CORE_BUSINESS.md | ✅ 完成 | 2026-01-22 |
+| 03_UI_COMPONENTS.md | ✅ 完成 | 2026-01-22 |
+| 04_VIEWS.md | ✅ 完成 | 2026-01-22 |
+| 05_DATA_LAYER.md | ✅ 完成 | 2026-01-22 |
+| 06_CROSS_PLATFORM.md | ✅ 完成 | 2026-01-22 |
+| 07_SIMILARITY_INDEX.md | ✅ 完成 | 2026-01-22 |
+| TECHNICAL_DOCS_PLAN.md | ✅ 完成 | 2026-01-22 |
+
+## 后续更新
+
+当代码有重大变更时，可以从此 commit 对比差异，更新相关文档：
+
+```bash
+git diff 59212b4..HEAD --stat
+git diff 59212b4..HEAD --name-only
+```
+
+### 变更分类指南
+
+| 变更路径 | 影响文档 |
+|---------|---------|
+| `src/service.factory.ts` | 01_ARCHITECTURE.md, 05_DATA_LAYER.md |
+| `src/services/*.ts` | 02_CORE_BUSINESS.md |
+| `src/types/*.ts` | 05_DATA_LAYER.md, 07_SIMILARITY_INDEX.md |
+| `src/libs/electron*.ts` | 06_CROSS_PLATFORM.md |
+| `src/libs/escpos*.ts` | 06_CROSS_PLATFORM.md |
+| `src/utils/*.ts` | 05_DATA_LAYER.md |
+| `package.json` (依赖) | PROJECT_OVERVIEW.md |

package/memo/technical-docs/PROJECT_OVERVIEW.md

@@ -0,0 +1,122 @@
+# XPOS Core - 项目总览
+
+> AI 上下文索引：POS系统、核心库、TypeScript、Dexie、服务工厂、发票计算、打印服务
+
+## 项目定位
+
+**名称:** `@posx/core`
+**版本:** 5.5.388
+**定位:** POSX 核心业务库 - 为 POS 系统提供核心功能的 TypeScript 库
+
+## 技术栈
+
+| 类型 | 技术 | 版本 |
+|------|------|------|
+| 语言 | TypeScript | 5.6.3 |
+| 构建工具 | tsdown | 0.16.1 |
+| 二次构建 | Vite | 5.4.11 |
+| 代码混淆 | vite-plugin-bundle-obfuscator | 1.8.0 |
+| 测试框架 | Jest + Vitest | 30.2.0 / 2.1.0 |
+| 数据库 | Dexie (IndexedDB) | 3.2.4 |
+| HTTP | Axios | 1.5.1 |
+| 实时通信 | SignalR | 7.0.11 |
+| 跨平台 | Capacitor + Cordova | 5.4.2 / 6.6.0 |
+
+## 核心依赖
+
+- **数据处理:** lodash, dayjs, uuid, nanoid
+- **加密:** bcryptjs, crypto-js
+- **验证:** zod, ajv
+- **导出:** xlsx
+- **打印:** esc-pos-encoder-ionic
+- **模板:** handlebars
+
+## 项目结构
+
+```
+xpos-core/
+├── src/                          # 源代码
+│   ├── index.ts                 # 主入口 (barrel exports)
+│   ├── service.factory.ts       # 服务工厂 (依赖注入)
+│   ├── services/                # 核心服务
+│   │   ├── abstract.service.ts  # 基础服务接口
+│   │   ├── app.service.ts       # 应用服务 (1800+ 行)
+│   │   ├── invoice.service.ts   # 发票服务 (2800+ 行)
+│   │   ├── printer.service.ts   # 打印服务
+│   │   ├── ods.service.ts       # 订单显示服务
+│   │   └── misc.service.ts      # 杂项工具
+│   ├── types/                   # 类型定义 (23 文件)
+│   ├── utils/                   # 工具函数 (6 文件)
+│   ├── libs/                    # 库抽象 (5 文件)
+│   ├── helpers/                 # 辅助函数 (3 文件)
+│   └── test/                    # 测试文件
+├── configs/                     # 打印模板 (31 JSON)
+├── scripts/                     # 构建脚本 (8 文件)
+├── build/                       # 编译输出
+└── docs/                        # TypeDoc 文档
+```
+
+## 服务架构
+
+### 服务工厂
+
+`ServiceFactory` 提供依赖注入，管理 18 个核心服务：
+
+| 服务 | 职责 |
+|------|------|
+| ItemService | 商品管理 |
+| CategoryService | 分类管理 |
+| SectionService | 区域管理 |
+| SectionItemService | 桌位管理 |
+| InvoiceService | 发票计算与生命周期 |
+| EmployeeService | 员工认证与管理 |
+| PaymentMethodService | 支付方式 |
+| ConfigService | 配置管理 |
+| PrinterService | 打印机管理 |
+| PrintJobService | 打印任务队列 |
+| PrintTemplateService | 打印模板 |
+| ShiftService | 班次管理 |
+| TillService | 收银机管理 |
+| ReportService | 报表服务 |
+| EmployeeRoleService | 角色权限 |
+| OrderDisplayService | 厨显系统 |
+| StorageService | 通用存储 |
+| MenuService | 菜单管理 |
+
+## 数据管理
+
+- **本地存储:** Dexie (IndexedDB) - 28 张表
+- **远程同步:** REST API + SignalR
+- **查询过滤:** 自定义 FindOptions (Include, In, Between, Not, Raw)
+
+## 业务实体
+
+核心管理 15+ 业务实体：
+- 商品/产品/分类
+- 客户/优惠券
+- 员工/角色
+- 发票/支付
+- 打印机/打印任务
+- 班次/收银机
+- 报表/存储/菜单
+
+## 构建流程
+
+```bash
+npm run build      # tsdown 主构建
+npm run build:dts  # 类型声明
+npm run build:demo # Vite 演示构建
+npm run test       # Jest 单元测试
+npm run docs       # TypeDoc 文档
+```
+
+**输出:**
+- ESM Bundle: `build/index.js` (混淆)
+- 类型声明: `build/index.d.ts`
+
+## 相关文档
+
+- [01_ARCHITECTURE.md](./01_ARCHITECTURE.md) - 整体架构
+- [02_CORE_BUSINESS.md](./02_CORE_BUSINESS.md) - 核心业务
+- [05_DATA_LAYER.md](./05_DATA_LAYER.md) - 数据层
+- [06_CROSS_PLATFORM.md](./06_CROSS_PLATFORM.md) - 跨平台

package/memo/technical-docs/TECHNICAL_DOCS_PLAN.md

@@ -0,0 +1,77 @@
+# 技术文档计划
+
+## 文档结构
+
+```
+memo/technical-docs/
+├── PROJECT_OVERVIEW.md      # 项目总览
+├── 01_ARCHITECTURE.md       # 整体架构
+├── 02_CORE_BUSINESS.md      # 核心业务逻辑
+├── 03_UI_COMPONENTS.md      # UI 组件 (本项目为库，无 UI)
+├── 04_VIEWS.md              # 页面实现 (本项目为库，无页面)
+├── 05_DATA_LAYER.md         # 数据层
+├── 06_CROSS_PLATFORM.md     # 跨平台能力
+├── 07_SIMILARITY_INDEX.md   # 相似性索引
+├── CHECKPOINT.md            # 检查点
+└── TECHNICAL_DOCS_PLAN.md   # 本文档
+```
+
+## 文档用途
+
+| 文档 | 目标读者 | 主要内容 |
+|------|---------|---------|
+| PROJECT_OVERVIEW | 新成员 | 项目定位、技术栈、结构概览 |
+| 01_ARCHITECTURE | 架构师 | 服务工厂、数据库架构、事件驱动 |
+| 02_CORE_BUSINESS | 开发者 | 发票计算、支付、打印、同步 |
+| 03_UI_COMPONENTS | - | 说明本项目无 UI 组件 |
+| 04_VIEWS | - | 说明本项目无页面 |
+| 05_DATA_LAYER | 后端开发 | Dexie、API、类型系统 |
+| 06_CROSS_PLATFORM | 移动开发 | Capacitor、Electron、打印机 |
+| 07_SIMILARITY_INDEX | 全体 | 模式对照、复用指南 |
+
+## 更新策略
+
+### 触发条件
+
+1. **版本发布时** - 检查 CHECKPOINT，对比差异
+2. **重大变更后** - 影响架构的变更需更新文档
+3. **定期审查** - 每月检查文档准确性
+
+### 更新流程
+
+```bash
+# 1. 检查变更范围
+git diff <checkpoint_commit>..HEAD --name-only
+
+# 2. 根据变更分类确定需更新的文档
+# 参考 CHECKPOINT.md 中的变更分类指南
+
+# 3. 更新相关文档
+
+# 4. 更新 CHECKPOINT.md 中的 commit 信息
+```
+
+## 编写规范
+
+### 格式要求
+
+1. **标题** - 使用 `#` 层次结构
+2. **AI 索引** - 每篇开头添加关键词
+3. **表格** - 优先使用表格展示结构化信息
+4. **代码** - 仅在关键处展示代码片段
+5. **路径** - 包含文件路径便于定位
+6. **交叉引用** - 文档间使用相对链接
+
+### 语言规范
+
+- 技术术语使用英文
+- 描述性文字使用中文
+- 优化 AI 阅读理解
+
+## 项目特点说明
+
+本项目 `@posx/core` 是 TypeScript 核心库，不是前端应用：
+
+- **无 UI 组件** - 03_UI_COMPONENTS.md 仅说明类型定义
+- **无页面视图** - 04_VIEWS.md 仅说明服务架构
+- **重点文档** - 01, 02, 05, 06 是核心文档

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@posx/core",
-  "version": "5.5.392",
+  "version": "5.5.395",
   "description": "POSX core libraries",
   "main": "./build/index.js",
   "author": "Steven Lee",