# warehouse-tools

**Repository Path**: c---project_1/warehouse-tools

## Basic Information

- **Project Name**: warehouse-tools
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-23
- **Last Updated**: 2026-04-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 仓库工具 (Warehouse Tools)

一个部署在仓库打包工位的 Windows 桌面辅助工具，为 Web 业务系统提供本地硬件能力调用。支持打印面单标签和摄像头录制打包视频。

## 功能特性

| 模块 | 功能 | 说明 |
|------|------|------|
| **打印服务** | WebSocket 接收打印任务，驱动本地打印机出纸 | XML + Liquid 模板引擎，GDI+ 打印管道，支持热敏/标签/A4 打印机，自动分页 |
| **录像服务** | WebSocket 接收录像指令，调用摄像头录制打包视频 | OpenCV 采集，编码器自动选择（H.264/X264/AVC1/MPEG-4/MJPEG），支持 FFmpeg/MSMF 后端，视频文字叠加（订单号、时间、备注） |
| **模板编辑** | 内置模板编辑器，实时预览 + 自动渲染 + 分页 | 三栏布局，暗色代码主题，自动切换测试数据，预览与打印分页效果一致 |
| **条码渲染** | 支持 QR Code 和 Code128 条码 | ZXing.Net + QRCoder，预览/打印双管道 |
| **队列管理** | 双优先级打印队列，支持手动清除 | 高/普通优先级队列，独立清除按钮，任务完成状态实时推送 |
| **托盘管理** | 最小化到系统托盘，右键菜单快速操作 | 支持开机自启、关闭到托盘 |
| **历史记录** | 打印和录像历史本地持久化 | SQLite 存储，支持查询和导出 |
| **日志查看** | 内置日志浏览和过滤 | 按级别过滤，支持导出和打开目录 |
| **启动画面** | 带进度条的启动加载界面 | 所有耗时初始化后台执行，UI 动画流畅 |
| **JS SDK** | 前端 WebSocket 通信封装 | ES Module，Promise API，自动重连，Vue 3 Composable |

## 技术栈

- **运行时**: .NET 8.0 (LTS)
- **UI 框架**: WPF + 原生样式（无第三方 UI 库）
- **通信**: WebSocket（作为 Web 系统与本地硬件的桥梁）
- **数据持久化**: EF Core + SQLite
- **打印引擎**: XML + Liquid 模板 → WPF Canvas（预览）/ GDI+ `PrintDocument`（打印）
- **条码生成**: ZXing.Net（Code128）、QRCoder（QR Code）
- **录像引擎**: OpenCvSharp4（DirectShow 采集 + VideoWriter 编码，FFmpeg/MSMF 后端）
- **DI 容器**: Microsoft.Extensions.DependencyInjection
- **日志**: Serilog（文件按天滚动）

## 项目结构

```
warehouse-tools/
├── src/
│   ├── WarehouseTools.Desktop/          # WPF 主程序（入口、托盘、配置 UI、启动画面）
│   │   ├── Views/                       # 视图：MainWindow、PrintView、RecordView、SettingsView、SplashScreen
│   │   ├── ViewModels/                  # ViewModel：MainViewModel、DashboardViewModel、PrintViewModel、RecordViewModel、SettingsViewModel
│   │   ├── WebSocketServer.cs           # 嵌入式 WebSocket + 静态文件服务器
│   │   └── App.xaml.cs                  # 启动流程（含 Splash 异步初始化）
│   ├── WarehouseTools.Core/             # 核心：WebSocket 路由、协议模型、事件总线、配置选项
│   │   ├── Models/WebSocket/            # 请求/响应 DTO（PrintRequests、RecordRequests、PrintResponses、RecordResponses）
│   │   ├── Events/                      # 应用内事件（AppEvent、PrintTaskCompletedEvent、RecordSessionCompletedEvent）
│   │   └── WebSocket/                   # 消息路由、服务器接口、处理器基类
│   ├── WarehouseTools.Printing/         # 打印模块：模板引擎、分页渲染、打印队列、历史记录
│   │   ├── Templates/                   # TemplateParser（WPF预览）、TemplateModelParser（GDI+模型）、GdiPrintRenderer、LiquidRenderer
│   │   ├── Queue/                       # IPrintQueue、PrintQueue（双优先级并发队列）
│   │   ├── Services/                    # PrintService（后台消费队列、保存历史）
│   │   └── Handlers/                    # PrintTaskHandler、QueryPrintersHandler
│   ├── WarehouseTools.Recording/        # 录像模块：摄像头采集、视频编码、文件打包
│   │   ├── Capture/                     # ICameraService、OpenCvCapture、VideoOverlayHelper
│   │   ├── Handlers/                    # StartRecordHandler、StopRecordHandler、QueryCamerasHandler
│   │   └── Models/                      # CameraDevice、CameraOptions、RecordingSession、RecordResult
│   └── WarehouseTools.Infrastructure/   # 基础设施：SQLite DbContext、文件存储、实体定义
│       └── Persistence/                 # WarehouseToolsDbContext、PrintHistoryEntity、RecordHistoryEntity
├── tests/
│   └── WarehouseTools.Core.Tests/       # 单元测试（xUnit）
├── templates/                           # 默认打印模板（XML）：packing-slip.xml、wave-picklist.xml
├── test/                                # WebSocket 测试页面（test/index.html）
├── appsettings.json                     # 全局配置
├── global.json                          # SDK 版本锁定
├── Directory.Build.props                # 全局 MSBuild 属性
├── Directory.Packages.props             # 中央包管理（CPM）
├── AGENTS.md                            # AI 编码代理开发指南
├── CHANGELOG.md                         # 开发日志
└── README.md                            # 项目说明
```

### 模块依赖

```
Desktop ──→ Core, Printing, Recording, Infrastructure
Printing ──→ Core, Infrastructure
Recording ──→ Core, Infrastructure
Infrastructure ──→ Core
```

### 运行时目录

```
Data/          # SQLite 数据库（自动创建）
Logs/          # Serilog 滚动日志（按天）
templates/     # 打印模板（XML，可热更新）
Recordings/    # 视频输出（MP4/AVI，按日期分目录）
```

## 快速开始

### 环境要求

- Windows 10/11 (x64)
- [.NET 8.0 SDK](https://dotnet.microsoft.com/download/dotnet/8.0)
- 本地打印机（可选，用于打印功能）
- USB/内置摄像头（可选，用于录像功能）

### 构建

```bash
# 克隆仓库
cd warehouse-tools

# 还原依赖
dotnet restore

# 编译
dotnet build

# 运行（WPF 桌面程序）
dotnet run --project src/WarehouseTools.Desktop
```

编译输出目录：
- `src/WarehouseTools.Desktop/bin/Debug/net8.0-windows/win-x64/`

### 发布（单文件 + 自包含）

```bash
dotnet publish src/WarehouseTools.Desktop \
  -c Release \
  -r win-x64 \
  --self-contained true \
  -p:PublishSingleFile=true \
  -p:EnableCompressionInSingleFile=true \
  -o ./publish
```

## 配置

编辑 `src/WarehouseTools.Desktop/appsettings.json`：

```json
{
  "WebSocket": {
    "Port": 8080,
    "Path": "/ws/",
    "AutoStart": true,
    "MaxConnections": 10
  },
  "Printing": {
    "DefaultPrinter": "",
    "AutoPrint": true,
    "Copies": 1,
    "TemplateDirectory": "templates",
    "CacheDirectory": "cache/templates",
    "CacheExpireHours": 24
  },
  "Recording": {
    "DefaultCamera": "",
    "OutputDirectory": "Recordings",
    "Resolution": "1280x720",
    "FrameRate": 25,
    "BitrateKbps": 2048,
    "VideoQuality": 95,
    "EncoderBackend": "auto",
    "SegmentDurationSeconds": 0,
    "MaxDurationSeconds": 600,
    "DiskSpaceThresholdMB": 1024
  },
  "History": {
    "Enabled": true,
    "DatabasePath": "Data/warehouse-tools.db",
    "MaxDays": 30
  },
  "UI": {
    "MinimizeToTray": true,
    "StartMinimized": false,
    "AutoStartWithWindows": false
  },
  "Logging": {
    "Level": "Information",
    "Directory": "Logs",
    "MaxLogFiles": 7
  }
}
```

## 模板系统

模板使用 **XML + Liquid** 双阶段渲染：

1. **Liquid 渲染**：DotLiquid 注入数据（`{{orderNo}}`、`{% for item in items %}`）
2. **XML 解析**：渲染后的 XML 解析为 WPF Canvas（预览）或 GDI+ 模型（打印）

### 支持元素

| 元素 | 说明 | 常用属性 |
|------|------|---------|
| `<text>` | 文本 | `font`, `fontsize`, `color`, `x`, `y`, `wrap` |
| `<label>` | 容器（可嵌套） | `width`, `height`, `padding`, `border`, `orientation`, `columns` |
| `<barcode>` | Code128 条码 | `value`, `width`, `height`, `margin` |
| `<qrcode>` | QR Code | `value`, `size`, `margin` |
| `<list>` / `<listitem>` | 列表 | `itemSpacing`, `padding`, `bg`, `orientation` |
| `<header>` / `<body>` / `<footer>` | 分页结构 | 仅在根 `<canvas>` 下生效 |

尺寸单位为 **DIP**（WPF 设备无关像素），`1 DIP = 1/96 英寸`。

### 模板示例

```xml
<canvas width="378" height="600">
  <!-- 标题 -->
  <text x="10" y="30" font="微软雅黑" fontsize="18" color="#1f2937">快递面单</text>

  <!-- 收件人信息 -->
  <label x="10" y="50" width="358" height="80" padding="8" border="#d1d5db" borderwidth="1">
    <text x="0" y="0" font="微软雅黑" fontsize="12" color="#374151">收件人：{{receiverName}}</text>
    <text x="0" y="20" font="微软雅黑" fontsize="12" color="#374151">电话：{{receiverPhone}}</text>
    <text x="0" y="40" font="微软雅黑" fontsize="11" color="#6b7280" wrap="true" width="340">地址：{{receiverAddress}}</text>
  </label>

  <!-- 条码 -->
  <barcode x="10" y="145" value="{{trackingNo}}" width="280" height="60" margin="2"/>
  <text x="300" y="175" font="Consolas" fontsize="12" color="#374151">{{trackingNo}}</text>

  <!-- 商品列表 -->
  <list x="10" y="220" width="358" itemspacing="4" padding="8" border="#d1d5db" borderwidth="1">
    {% for item in items %}
    <listitem padding="4" bg="{% cycle '#f9fafb', '#ffffff %}">
      <text x="0" y="0" font="微软雅黑" fontsize="11" color="#374151">{{item.sku}} × {{item.qty}}</text>
    </listitem>
    {% endfor %}
  </list>

  <!-- 二维码 -->
  <qrcode x="260" y="420" value="{{trackingNo}}" size="100" margin="1"/>

  <!-- 页脚 -->
  <text x="10" y="560" font="微软雅黑" fontsize="10" color="#9ca3af">打印时间：{{printTime}}</text>
</canvas>
```

### 默认模板

| 模板 | 尺寸 | 用途 |
|------|------|------|
| `templates/packing-slip.xml` | 标签/热敏 | 装箱单（快递面单） |
| `templates/wave-picklist.xml` | A4 | 波次检货单（带条码、QR Code、表格） |

模板文件存放于 `templates/` 目录，支持运行时热更新和通过 `templateUrl` 远程加载。

## WebSocket 通信

Web 业务系统通过 WebSocket 与本工具通信，端口默认为 `8080`。

```
ws://localhost:8080/ws/
```

### 通用消息格式

```json
{
  "MessageType": "print_task",
  "RequestId": "req-001",
  "Payload": { }
}
```

### 打印任务示例

**请求**
```json
{
  "MessageType": "print_task",
  "RequestId": "req-001",
  "Payload": {
    "Template": "templates/packing-slip.xml",
    "Printer": "ZDesigner GT800",
    "Priority": "normal",
    "OrderNo": "SO20240001",
    "Copies": 1,
    "Data": {
      "Warehouse": "华东仓",
      "Items": [
        { "Sku": "SKU001", "Qty": 2 }
      ]
    }
  }
}
```

**响应**
```json
{
  "MessageType": "print_task_accepted",
  "RequestId": "req-001",
  "Payload": {
    "TaskId": "task-abc123",
    "Status": "Queued",
    "EstimatedWait": "00:00:03",
    "OrderNo": "SO20240001"
  }
}
```

### 常用消息类型

| 消息类型 | 方向 | 说明 |
|----------|------|------|
| `print_task` | Web → Desktop | 发送打印任务（`OrderNo` 必填） |
| `start_record` | Web → Desktop | 开始摄像头录制（`OrderNo` 必填） |
| `stop_record` | Web → Desktop | 停止指定录制 |
| `stop_all_records` | Web → Desktop | 停止所有活跃录制 |
| `query_printers` | Web → Desktop | 查询可用打印机 |
| `query_cameras` | Web → Desktop | 查询可用摄像头 |
| `query_recording_status` | Web → Desktop | 查询当前录制状态 |

完整协议定义见 `AGENTS.md` 第 6 节。

### JS SDK

项目内置前端 SDK (`test/warehouse-tools-sdk.js`)，支持原生 JS 和 Vue 3。完整 API 文档请参阅 [`test/SDK.md`](./test/SDK.md)。

```javascript
// 原生 JS
import { WarehouseToolsClient } from './warehouse-tools-sdk.js';
const client = new WarehouseToolsClient('ws://localhost:8080/ws/');
await client.connect();

// 打印
await client.print({
  orderNo: 'SO20240001',
  template: 'templates/packing-slip.xml',
  data: { warehouse: '华东仓', items: [...] }
});

// 录像
await client.startRecord({ orderNo: 'SO20240001', cameraName: '打包台摄像头' });
await client.stopRecordByOrderNo('SO20240001');   // 按订单号停止
await client.stopAllRecords();                     // 停止所有录制
```

```javascript
// Vue 3 Composable
import { useWarehouseTools } from './warehouse-tools-sdk.js';
const { connected, print, startRecord, stopAllRecords, queryCameras } =
  useWarehouseTools('ws://localhost:8080/ws/');
```

特性：
- Promise-based API（`async/await`）
- 自动重连（指数退避，最多 10 次）
- 请求/响应按 `RequestId` 匹配
- 事件订阅：`connected`、`disconnected`、`print_completed`、`record_completed`

## 运行截图（功能概览）

- **总览面板**: 显示 WebSocket 状态、打印机/摄像头状态、磁盘剩余空间、最近事件
- **总览面板**: WebSocket 状态、打印机/摄像头状态、磁盘空间、最近事件
- **打印面板**: 打印队列管理、模板编辑器、历史记录查询、手动打印
- **模板编辑器**: 三栏布局（文件列表 / XML+JSON 编辑器 / 预览+帮助面板），支持顶部工具栏快捷插入标签/文本/条码/二维码，底部绿色状态栏
- **录像面板**: 摄像头设备列表、录制控制（开始/停止）、历史视频文件
- **设置面板**: 配置项浏览和修改
- **日志面板**: 实时日志查看、级别过滤、导出

## 常见问题

**Q: 摄像头列表为空？**
A: 检查 Windows 隐私设置是否允许桌面应用访问摄像头；检查摄像头是否被其他应用占用。

**Q: 开始录制后停止提示失败？**
A: 检查 `Logs/` 目录下的日志文件，查看具体错误信息。常见原因：编码器不可用（会自动 fallback 到 MJPG/AVI）、磁盘空间不足。

**Q: 录像文件很大？**
A: 如果 FFmpeg H.264 编码器不可用，会自动降级到 MSMF H.264 或 MJPEG/AVI。MJPEG 编码的文件体积通常是 H.264 的 5~10 倍。建议安装 FFmpeg 编解码器或使用 MSMF 后端（`EncoderBackend: "msmf"`）。

**Q: 数据库文件需要重建？**
A: 如果更新了 `DateTimeOffset` 存储格式（如从 `DateTimeOffsetToStringConverter` 变更），建议删除 `Data/warehouse-tools.db` 让程序自动重建，避免 schema 不匹配。

**Q: 打印任务无响应？**
A: 检查打印机驱动和名称拼写；确认 `PrintService` 后台消费者线程正常运行。

**Q: 打印字体和预览字体大小不一致？**
A: 这是 WPF（DIP）与 GDI+（Point）的单位差异。已在 `GdiPrintRenderer` 中统一转换（`pt = dip × 72/96`），确保打印与预览物理尺寸一致。

**Q: WebSocket 连不上？**
A: 检查端口是否被占用；检查防火墙规则；确认 WPF 程序已启动。

## 开发指南

面向开发者和 AI 编码代理的详细规范，请参阅 [`AGENTS.md`](./AGENTS.md)。

项目演进记录请参阅 [`DEVELOPMENT.md`](./DEVELOPMENT.md)。

核心原则：
- 打印逻辑只在 `Printing` 项目，录像逻辑只在 `Recording` 项目
- `Core` 层不引用 WPF / WinForms / ASP.NET
- 所有硬件操作必须加 `try-finally`，防止资源锁定
- 使用 `DateTimeOffset.UtcNow` 代替 `DateTime.Now`

## License

MIT