@posx/core 5.5.392 → 5.5.395

package/memo/technical-docs/03_UI_COMPONENTS.md

@@ -0,0 +1,59 @@
+# 03 - UI 组件
+
+> AI 上下文索引：核心库、非UI应用、类型定义、业务实体
+
+## 重要说明
+
+**本项目是核心服务库，不包含 UI 组件。**
+
+`@posx/core` 是后端/核心库项目，提供业务逻辑服务，不是 UI 应用。因此没有 Vue/React 组件。
+
+## 项目性质
+
+- **类型:** TypeScript 核心库
+- **用途:** 被其他 POS 前端应用消费
+- **输出:** ESM bundle + 类型声明
+
+## 提供的类型定义
+
+虽然没有 UI 组件，但提供了完整的类型定义供 UI 层使用：
+
+### 业务实体类型
+
+| 文件 | 主要类型 | 用途 |
+|------|---------|------|
+| `invoice.type.ts` | IInvoice, IInvoiceLine | 发票数据结构 |
+| `product.type.ts` | IItem, ICategory | 商品/分类 |
+| `payment.type.ts` | IPayment, IPaymentMethod | 支付数据 |
+| `employee.type.ts` | IEmployee | 员工信息 |
+| `config.type.ts` | IAppConfig | 应用配置 |
+| `printer.type.ts` | IPrinter, IPrintJob | 打印相关 |
+| `shift.type.ts` | IShift, ITill | 班次/收银机 |
+| `report.type.ts` | IAppReport | 报表数据 |
+| `section.type.ts` | ISection, ISectionItem | 区域/桌位 |
+
+### 枚举类型
+
+```typescript
+// 发票状态
+enum InvoiceStatus { Open, OnHold, Paying, Paid, Void, PayAtCounter, Calibration }
+
+// 打印机类型
+enum PrinterType { Receipt, Kitchen, Kiosk, Label, Order, Check }
+
+// 支付状态
+enum PaymentStatus { payment_started, payment_completed, payment_failed, payment_cancelled }
+```
+
+## UI 应用位置
+
+使用本库的 UI 应用可能位于：
+- 单独的 `packages/app/` 目录 (monorepo 结构)
+- 独立的前端仓库
+- 消费 `@posx/core` 作为 npm 依赖
+
+## 相关文档
+
+- [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/04_VIEWS.md

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

@@ -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) - 跨平台