taro-bluetooth-print 2.12.0 → 2.15.0

package/CHANGELOG.md

@@ -1,147 +1,97 @@
 # Changelog
 
-## [2.11.0] - 2026-05-04
-
-### Changed
-- **错误体系统一**: 将 14 处 `throw new Error()` 迁移为 `BluetoothPrintError` + `ErrorCode`，覆盖 ReactNativeAdapter、DeviceManager、PrinterConfigManager、PrinterFactory、PreviewRenderer、PrintQueue、CloudPrintManager、PrintJobManager、PrintScheduler、image.ts
-- **DiscoveryService.ts**: 移除顶部 3 条 eslint-disable 规则，清理注释代码
-- **TemplateRenderer.ts**: `itemData: any` → `Record<string, unknown>`，移除 3 处行内 eslint-disable
-- **outputLimiter.ts**: batchProcess 错误处理规范化（instanceof Error 守卫 + message 输出）
-- **魔数提取**: ChunkWriteStrategy 提取 7 个常量（CHUNK_SIZE_STEP、DELAY_BACKOFF_FACTOR 等），PrintHistory 提取 DEFAULT_MAX_ENTRIES，TemplateRenderer/TemplateEngine 提取 DEFAULT_PAPER_WIDTH
+## [2.15.0] - 2026-07-07
 
 ### Added
-- 新增 ErrorCode: `QUEUE_FULL`、`QUEUE_JOB_NOT_FOUND`、`PREVIEW_FAILED`
-
-### Testing
-- 985 tests passed, 38 skipped, 0 regressions
-- type-check: 0 errors
-- lint: 0 errors
-
-
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
----
-
-## [2.10.2] - 2026-05-02
-
-### Fixed
-
-- **代码质量优化 — 消除所有 ESLint 错误** (#37 → 0)
-  - 移除 3 个文件顶部 `eslint-disable`（共 18 条规则绕过）
-  - 修复所有非空断言 (`!`) — `Uint8Array[i]!`、`parts[x]!`、`job.nextRunTime!` 等
-  - 修复所有 `any` 类型绕过 — `as string` 改为 `typeof` 运行时检查
-  - JSON.parse 结果改用 `as Record<string, unknown>` + 类型守卫访问
-  - 异步方法 `void` → `await`，消除 `require-await` 错误
-  - `Record<string, any>` → `Record<string, unknown>`
-  - 消除 `no-base-to-string`：`String(value)` → `JSON.stringify(value)`
-  - 消除 `no-unused-vars`：废弃变量改为 `void timeout`
-- **零 ESLint 警告/错误、零非空断言、零行内 eslint-disable 残留**
-
----
-
-## [2.10.1] - 2026-05-01
-
-### Fixed
 
-- **npm publish 版本冲突** — `v2.10.0` 因旧 tag 提前发布导致新内容无法覆盖。bump 至 `2.10.1` 重新发布。
-
----
-
-## [2.10.0] - 2026-05-01
-
-### Added
-
-- **`ChunkWriteStrategy` 自适应分块写入抽象基类** (#R4)
-  - Template Method 模式：将 MiniProgramAdapter 与 ReactNativeAdapter 共用的自适应分块写入逻辑提取到统一基类
-  - 子类仅需实现 `writeSingleChunk()` 平台特定的单块写入操作
-  - 公共框架包括：自适应分块大小调整、指数退避重试、连接状态周期性检查、单块超时、分块间 BLE 拥塞控制延迟
-  - `MiniProgramWriteStrategy` — 封装 Taro/微信/支付宝/百度/字节/QQ 小程序 BLE API
-  - `ReactNativeWriteStrategy` — 封装 react-native-ble-plx，含 withResponse/withoutResponse 降级回退
-
-- **`withTimeout()` 工具函数集成** (#R5)
-  - 提取 Promise race + setTimeout 重复模式到 `src/utils/withTimeout.ts`
-  - 已集成至 `BaseAdapter.connect()`、`ReactNativeAdapter.connect()`、`ConnectionManager.connect()`、`PrinterStatus.queryStatus()`
-  - 减少约 40 行重复的手动 timer 管理代码，消除遗漏 clearTimeout 的风险
+- **Professional Documentation Redesign** — Complete visual overhaul of docs site with custom brand identity
+  - 6 new SVG logo variants (primary, mark, dark, wordmark, OG cover, hero banner)
+  - Reimagined docs landing page with hero banner, feature cards, and compatibility matrix
+  - Full Mermaid architecture diagrams (6-layer system, connection sequence, print flow)
+- **Online Documentation Link** — `homepage` and `documentation` fields added to `package.json`
+  - Live docs: https://agions.github.io/taro-bluetooth-print/
 
 ### Changed
 
-- **适配器代码重构**
-  - `MiniProgramBLEApi.writeBLECharacteristicValue` 参数类型从 `ArrayBuffer` 扩展为 `ArrayBuffer | ArrayBufferLike`，消除 `chunk.buffer` 的类型兼容性 warning
-  - `ReactNativeAdapter.arrayBufferToBase64` 同理扩展参数类型
-  - `ChunkWriteStrategy.logger` 类型修正为 `ReturnType<typeof Logger.scope>`，修复 Logger 实例类型不匹配
+- **README.md** — Hero section with brand badges, 4 why-choose cards, architecture mermaid diagram, 8×7 platform compatibility matrix, error handling pattern guide, and plugin ecosystem section (360 → 443 lines)
+- **docs/index.md** — VitePress hero with `hero-banner.svg`, 6 feature cards, full protocol×platform matrix, 6 highlight cards with hover effects (154 → 305 lines)
+- **docs/guide/architecture.md** — Added mermaid `flowchart TD` (6-layer architecture), `sequenceDiagram` (connection flow + print flow), detailed layer responsibility table
+- **docs/.vitepress/config.ts** — Updated SEO meta tags, OG image (`og-cover.svg`), brand theme color (`#6366f1`)
+- **Brand Identity** — Unified design language: indigo → cyan gradient (`#4338ca` → `#6366f1` → `#0891b2`), rounded-receipt motif, Bluetooth waveform arcs, 7×7 QR matrix
 
-### Fixed
+### Assets
 
-- **`ChunkWriteStrategy.ts` 缺少 Logger 导入** — 导致 5 个适配器测试失败（TaroAdapter、AlipayAdapter、BaiduAdapter、ByteDanceAdapter、QQAdapter）
-- **`chunk.buffer` 类型兼容性** — `Uint8Array.buffer` 返回 `ArrayBufferLike`，原 `ArrayBuffer` 参数类型导致 TypeScript 编译错误
+| File | Size | Purpose |
+|:---|:---|:---|
+| `docs/public/logo.svg` | 240×240 | Primary logo (gradient plate + receipt + BT arcs) |
+| `docs/public/logo-mark.svg` | 64×64 | Compact icon-only variant |
+| `docs/public/logo-dark.svg` | 240×240 | Dark background variant |
+| `docs/public/wordmark.svg` | 560×96 | Horizontal logo with tagline |
+| `docs/public/og-cover.svg` | 1200×630 | Social sharing card |
+| `docs/public/hero-banner.svg` | 1600×400 | Docs landing page hero |
+| `docs/public/favicon.svg` | 32×32 | Browser tab favicon (redesigned) |
 
-### Security
+### Documentation
 
-- `withTimeout()` 统一使用 try/finally 模式的 timer 清理，消除所有手动 `Promise.race` + `setTimeout` 模式中遗漏 `clearTimeout` 的风险
+- All SVG assets are inline-path (0 external dependencies)
+- Docs build time: 19.3s, 0 errors
+- Mermaid diagrams render correctly in VitePress
 
 ---
 
-## [2.9.6] - 2026-04-30
-
-### Added
-
-- **`ZplDriver.image()` — ZPL 图像编码实现** (#1)
-  - 使用 ZPL `^GFA` (Graphic Field) 命令编码 1-bit 黑白位图
-  - 支持 x/y 定位、字节校验、十六进制数据编码
-  - 适用于 Zebra ZD420、GT800、ZM400 等标签打印机
-  - [之前为 TODO 占位方法]
-
-- **`CpclDriver.downloadLogo()` — CPCL Logo 下载实现** (#2)
-  - 使用 CPCL `CG` (Compressed Graphic) 命令编码 1-bit 位图
-  - 宏定义存储 (`! DF`)，位图大小自动推断（可选传参）
-  - 向后兼容：签名保持 `(logoName, bitmap, options?)`
-  - 适用于 HP IR3222、霍尼韦尔等移动打印机
-  - [之前为 TODO 占位方法]
-
-- **单元测试覆盖**
-  - ZPL 图像编码：链式调用验证 (`^FO` / `^GFA` / `^FS` 命令输出断言)
-  - ZPL 空 bitmap 边界处理
+## [2.14.0] - 2026-07-07
 
-### Fixed
+### Changed
 
-- **`ConnectionManager` 连接超时 Timer 泄漏** (#3)
-  - `connect()` 中 `setTimeout` 创建的连接超时 timer 在成功连接后未清理
-  - 修复：保存 timeoutId 引用，`Promise.race` 成功后显式 `clearTimeout()`
+- **核心引擎解耦**: `BluetoothPrinter` 抽出 `handleError()` 与 `resolveConnectionManager()` helper，消除 4 处 try/catch 模板
+- **命令构建器精简**: `CommandBuilder` 抽出 `pushCommands()` helper，消除 7 处 `buffer.push + invalidateCache` 重复
+- **适配器分层**: 5 个 mini-program adapter（Taro / Alipay / Baidu / ByteDance / QQ）精简为薄壳类（-69% 平均）
+- **服务层去重**: `ConnectionManager.classifyConnectError()`、`PrintJobManager.wrapError()` 抽离，消除嵌套三元
+- **错误类去重**: `ConnectionError` / `PrintJobError` 移除冗余 mapping 表（基于字符串值与 `ErrorCode` 完全一致）；`CommandBuildError` 仅保留 DRIVER_ERROR 单条映射
+- **类型黑洞修复**: `PluginManager.executeHook()` 移除 `@ts-expect-error`，改用显式类型守卫
+- **命名规范统一**: 冻结 PascalCase（类文件）/ camelCase（工具文件）/ `I`-prefix（接口）/ 0 下划线前缀 4 条规则
+- **API 表面补完**: `src/index.ts` 新增 `QQAdapter` 导出
 
-- **`PrinterStatus` 状态查询超时 Timer 泄漏** (#4)
-  - `queryStatus()` 中超时 timer 在正常返回后仍驻留至超时触发
-  - 修复：使用相同 timer 清理模式
+### Removed
 
-- **`PrintQueue` 重试定时器泄漏** (#5)
-  - 任务重试 `setTimeout` 未保存引用，`clear()` 时无法清理
-  - 修复：新增 `retryTimerId` 成员，`clear()` 时自动取消待执行的重试
+- `src/utils/validation.ts` — deprecated 空 stub，无任何引用
 
-### Changed
+### Renamed
 
-- **README 文档更新**
-  - 「高级打印」新增 ZPL 图像编码、CPCL Logo 下载条目
-  - 「打印机驱动」新增功能状态列，明确标注各驱动支持程度
-  - 「性能指标」测试用例数更新为 879（95.7% 通过率）
+- `drivers/escPosDriver.ts` → `drivers/EscPosDriver.ts`
+- `drivers/barcode-helpers.ts` → `drivers/BarcodeHelpers.ts`
+- `errors/baseError.ts` → `errors/BaseError.ts`
+- `plugins/types.ts` → `plugins/PluginTypes.ts`
+- `encoding/gbk-{table,lite,data}.ts` → `encoding/Gbk{Table,Lite,Data}.ts`
+- `encoding/korean-japanese.ts` → `encoding/KoreanJapanese.ts`
 
-### Security
+### Refactoring Metrics
 
-- 消除了所有已识别的 `setTimeout` 泄漏风险点（共 3 处）
-- 资源清理路径审计通过：`disconnect` / `destroy` / `clear` 均能正确清理关联定时器
+| 指标 | Before | After | Δ |
+|---|---:|---:|---:|
+| `BluetoothPrinter.ts` | 433 行 | 277 行 | **-36%** |
+| `CommandBuilder.ts` | 315 行 | 158 行 | **-50%** |
+| `PrintJobManager.ts` | 539 行 | 386 行 | **-28%** |
+| 5 mini-program adapters | ~200 行 | ~62 行 | **-69%** |
+| 3 error classes | 225 行 | 142 行 | **-37%** |
+| **Total** | **23,355 行** | **22,567 行** | **-788 / -3.4%** |
 
----
+### Testing
 
-## [2.9.5] - 初始发布
+- 1,102 tests passed, 38 skipped, 0 regressions
+- type-check: 0 errors (strict + noUncheckedIndexedAccess 全开)
+- eslint: 0 errors / 0 warnings
+- vite build: 22.84s · 230.91 KB gzip（基线 22.25s · 230.58 KB gzip）
+- GitHub Actions CI: ✅ success (Run #28835694715)
 
-初始发布版本，包含完整的跨平台蓝牙打印功能支持。
+### Commits
 
-### 核心能力
+7 个 conventional commits 落地 (`be2fbdc..06f5ede`)：
 
-- 7 大平台适配器：微信 / 支付宝 / 百度 / 字节跳动 / QQ 小程序 + H5 + React Native
-- 8 种打印机驱动：ESC/POS、TSPL、ZPL、CPCL、STAR、佳博、芯烨、思普瑞特
-- 完整打印生命周期：扫描 → 连接 → 打印 → 断开
-- 丰富的打印特性：图片（Floyd-Steinberg 抖动）、QR/条码（10+ 格式）、模板引擎
-- 运维体系：离线缓存、打印队列、多设备管理、历史统计、定时重试、插件系统
+- `2fc1f2d` refactor(core): simplify BluetoothPrinter & CommandBuilder
+- `27fdd6a` refactor(services): dedup ConnectionManager + PrintJobManager
+- `c6adaf6` refactor(adapters): deduplicate mini-program adapters and BaseAdapter imports
+- `2bf28f6` refactor: enforce PascalCase file naming for class-bearing modules
+- `6dfe1c5` refactor: remove @ts-expect-error and dead code
+- `8e9193d` refactor(errors): deduplicate error-code mapping tables
+- `06f5ede` chore: update import paths after PascalCase file renames