@posx/core 5.5.395 → 5.5.396

package/memo/technical-docs/04_VIEWS.md

@@ -1,82 +0,0 @@
-# 04 - 页面实现
-
-> AI 上下文索引：核心库、非UI应用、服务层、类型导出
-
-## 重要说明
-
-**本项目是核心服务库，不包含页面/视图。**
-
-`@posx/core` 是 TypeScript 核心库，提供业务逻辑和数据服务，不是前端应用。因此没有 Vue/React 页面。
-
-## 项目性质
-
-- **类型:** 后端服务库
-- **输出:** ESM bundle + 类型声明
-- **用途:** 被 POS 前端应用消费
-
-## 提供的服务
-
-本库为 UI 层提供完整的业务服务：
-
-### POS 相关服务
-
-| 服务 | 功能 |
-|------|------|
-| SectionService | 区域管理 |
-| SectionItemService | 桌位管理 |
-| InvoiceService | 发票/订单处理 |
-| ItemService | 商品查询 |
-
-### 管理相关服务
-
-| 服务 | 功能 |
-|------|------|
-| EmployeeService | 员工管理 |
-| EmployeeRoleService | 角色权限 |
-| ConfigService | 系统配置 |
-| ReportService | 报表数据 |
-
-### 设置相关服务
-
-| 服务 | 功能 |
-|------|------|
-| PrinterService | 打印机配置 |
-| PaymentMethodService | 支付方式 |
-| CategoryService | 分类管理 |
-| MenuService | 菜单配置 |
-
-## UI 应用架构建议
-
-使用本库的 UI 应用典型结构：
-
-```
-app/
-├── views/
-│   ├── pos/              # POS 页面
-│   ├── management/       # 管理页面
-│   ├── settings/         # 设置页面
-│   └── reporting/        # 报表页面
-├── stores/               # 状态管理
-└── services/             # 服务调用层
-```
-
-## 服务调用示例
-
-```typescript
-import { ServiceFactory, InvoiceService } from '@posx/core';
-
-// 初始化服务工厂
-const factory = await ServiceFactory.init(options, window);
-
-// 获取服务
-const invoiceService = await factory.getServiceByName('Invoice');
-
-// 使用服务
-const invoice = await invoiceService.getOne(uid);
-```
-
-## 相关文档
-
-- [PROJECT_OVERVIEW.md](./PROJECT_OVERVIEW.md) - 项目总览
-- [02_CORE_BUSINESS.md](./02_CORE_BUSINESS.md) - 核心业务逻辑
-- [05_DATA_LAYER.md](./05_DATA_LAYER.md) - 数据层

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

@@ -1,375 +0,0 @@
-# 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

@@ -1,246 +0,0 @@
-# 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) - 数据层