@posx/core 5.5.393 → 5.5.395

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

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