@posx/core 5.5.395 → 5.5.396

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

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

@@ -1,46 +0,0 @@
-# 文档检查点
-
-## 当前基准
-
-| 项目 | 值 |
-|------|---|
-| 分支 | 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

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

@@ -1,77 +0,0 @@
-# 技术文档计划
-
-## 文档结构
-
-```
-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 是核心文档