# WarehouseWebSocketTools

**Repository Path**: ai-code_4/warehouse-web-socket-tools

## Basic Information

- **Project Name**: WarehouseWebSocketTools
- **Description**: 仓库小工具，web调用C#应用程序
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-16
- **Last Updated**: 2026-03-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Warehouse WebSocket Tools

仓库 WebSocket 工具 - 基于 WPF 的设备通信与管理平台

[![.NET](https://img.shields.io/badge/.NET-8.0-blue)](https://dotnet.microsoft.com/)
[![WPF](https://img.shields.io/badge/UI-WPF-purple)](https://docs.microsoft.com/dotnet/desktop/wpf/)

---

## 📖 功能特性

### 核心功能
- ✅ **WebSocket 服务器** - 内嵌 Fleck，支持多客户端连接
- ✅ **摄像头控制** - FFmpeg 推流、截图（框架已搭建）
- ✅ **打印机管理** - 打印机列表、测试页打印
- ✅ **标签打印** - XML 模板引擎、支持变量替换
- ✅ **模板管理** - 内置快递面单模板，支持自定义
- ✅ **MVVM 架构** - CommunityToolkit.Mvvm，数据绑定
- ✅ **现代化 UI** - 圆角卡片、Tab 分页、彩色日志

### 技术亮点
- 🎨 **美观界面** - 蓝色主色调、状态指示器、图标化 Tab
- 📝 **日志系统** - 单例模式、级别分类、自动清理
- 🔌 **插件化** - 设备服务接口化，易于扩展
- 📦 **中文支持** - 全中文界面、中文日志输出

---

## 🚀 快速开始

### 环境要求
- Windows 10/11
- .NET 8.0 SDK
- Visual Studio 2022 (可选)

### 构建项目

```bash
# 克隆仓库
git clone git@gitee.com:ai-code_4/warehouse-web-socket-tools.git

# 进入目录
cd warehouse-web-socket-tools

# 还原依赖
dotnet restore

# 编译
dotnet build

# 运行
dotnet run
```

---

## 📡 WebSocket API

### 连接
```
ws://localhost:8080/
```

### 消息协议

#### 请求格式
```json
{
  "code": "req_001",
  "type": "printer",
  "action": "ListPrinters",
  "direction": "request",
  "data": {}
}
```

#### 响应格式
```json
{
  "code": "req_001",
  "type": "printer",
  "status": "success",
  "direction": "response",
  "data": {},
  "timestamp": 1710601200000
}
```

### API 列表

#### 系统操作
| Action | 说明 |
|--------|------|
| `Heartbeat` | 心跳检测 |
| `Status` | 获取服务器状态 |

#### 摄像头操作
| Action | 说明 |
|--------|------|
| `ListDevices` | 获取摄像头列表 |
| `StartStream` | 开始推流 |
| `StopStream` | 停止推流 |
| `CaptureImage` | 捕获截图 |

#### 打印机操作
| Action | 说明 |
|--------|------|
| `ListPrinters` | 获取打印机列表 |
| `PrintTestPage` | 打印测试页 |
| `PrintDocument` | 打印文档 |
| `PrintLabel` | 打印标签 |
| `ListTemplates` | 获取模板列表 |
| `SaveTemplate` | 保存模板 |
| `DeleteTemplate` | 删除模板 |

### 打印标签示例

```json
{
  "code": "print_001",
  "type": "printer",
  "action": "PrintLabel",
  "data": {
    "templateId": "waybill_default",
    "printerName": "ZDesigner GT800",
    "copies": 1,
    "data": {
      "orderNo": "SF1234567890",
      "receiver": {
        "name": "张三",
        "phone": "13800138000",
        "address": "北京市朝阳区某某街道"
      },
      "sender": {
        "name": "李四",
        "phone": "13900139000",
        "address": "上海市浦东新区某某路"
      },
      "remark": "请轻拿轻放"
    }
  }
}
```

---

## 📝 模板语法

### 基础示例
```xml
<LabelTemplate>
  <Text x="10" y="10" fontSize="16" fontWeight="Bold">
    收件人：{{receiver.name}}
  </Text>
  <Text x="10" y="35" fontSize="14">
    电话：{{receiver.phone}}
  </Text>
  <BarCode x="10" y="100" width="200" value="{{orderNo}}"/>
  <QrCode x="250" y="100" size="80" value="{{orderNo}}"/>
</LabelTemplate>
```

### 支持的元素
| 元素 | 说明 | 属性 |
|------|------|------|
| `<Text>` | 文本标签 | x, y, fontSize, fontWeight, color, text |
| `<BarCode>` | 条形码 (Code128) | x, y, width, height, value, showText |
| `<QrCode>` | 二维码 | x, y, size, value |
| `<Line>` | 线条 | x1, y1, x2, y2, strokeWidth, stroke |
| `<Rectangle>` | 矩形 | x, y, width, height, fill, stroke |
| `<Image>` | 图片 | x, y, width, height, src |

### 模板变量
- 支持嵌套路径：`{{receiver.name}}`, `{{sender.address.city}}`
- 支持数组索引：`{{items[0].name}}`
- 自动替换：渲染时自动替换为实际数据

---

## 🏗️ 项目结构

```
warehouse-web-socket-tools/
├── Core/
│   ├── MessageProtocol.cs      # JSON 消息模型
│   ├── WebSocketServer.cs      # WebSocket 服务 (WsServer)
│   ├── MessageHandler.cs       # 消息路由处理
│   └── Logger.cs               # 日志工具类
├── Devices/
│   ├── Camera/
│   │   └── ICameraService.cs   # 摄像头服务接口
│   └── Printer/
│       └── IPrinterService.cs  # 打印机服务接口
├── Models/
│   └── LabelTemplate.cs        # 标签模板模型
├── Services/
│   ├── LabelElementParser.cs   # 元素解析基类
│   ├── TextElementParser.cs    # 文本解析
│   ├── QrCodeElementParser.cs  # 二维码/条形码解析
│   ├── LabelTemplateRenderer.cs # 模板渲染引擎
│   └── LabelPrintService.cs    # 标签打印服务
├── ViewModels/
│   ├── MainViewModel.cs        # 主视图模型
│   └── ViewModels.cs           # ConnectionInfo, LogEntry
├── Converters/
│   └── BoolConverters.cs       # 值转换器
├── Themes/
│   └── Styles.xaml             # UI 样式资源
├── Templates/
│   └── Waybill.xml             # 快递面单模板示例
├── App.xaml                    # 应用入口
├── MainWindow.xaml             # 主界面
└── README.md                   # 项目说明
```

---

## 🎨 UI 界面

### Tab 1: WebSocket 服务器
- 🌐 服务器配置（主机、端口、启动/停止）
- 📡 活动连接列表
- 📋 活动日志（按级别着色）

### Tab 2: 打印机
- 🖨️ 可用打印机列表
- 📋 标签模板列表
- 📑 打印任务列表
- 🔄 刷新 / 📄 打印测试页 / ▶️ 打印标签

### Tab 3: 摄像头
- 📷 可用摄像头列表
- 🖥️ 预览区域
- ▶️ 开始推流 / ⏹️ 停止推流 / 📸 捕获图像

---

## 🛠️ 开发指南

### 添加新设备支持

1. 在 `Devices/` 下创建服务接口
2. 在 `MessageProtocol.cs` 添加 `MessageAction`
3. 在 `MessageHandler.cs` 实现处理方法
4. 在 `MainViewModel.cs` 添加命令
5. 在 `MainWindow.xaml` 添加 UI

### 自定义模板

```csharp
var template = new LabelTemplate
{
    Id = "my_template",
    Name = "我的模板",
    Width = 100,
    Height = 150,
    Content = @"
<LabelTemplate>
  <Text x=""10"" y=""10"" fontSize=""16"">Hello {{name}}</Text>
</LabelTemplate>"
};

await printerService.SaveTemplateAsync(template);
```

### 日志使用

```csharp
// 任何地方都可以直接调用
Log.Info("信息");
Log.Success("成功");
Log.Error("错误");
Log.Warning("警告");
Log.Debug("调试");
Log.Message("WebSocket 消息");

// 记录异常
try { ... }
catch (Exception ex)
{
    Log.Error("操作失败", ex);
}
```

---

## 📊 开发进度

- [x] 创建 WPF 项目 (.NET 8.0)
- [x] NuGet 包安装（Fleck, Newtonsoft.Json, CommunityToolkit.Mvvm）
- [x] WebSocket 服务器实现
- [x] JSON 消息模型定义
- [x] 日志工具类
- [x] MVVM 架构重构
- [x] 现代化 UI 设计
- [x] 全中文化
- [x] 标签模板引擎
- [x] 打印功能集成
- [ ] FFmpeg 摄像头集成（框架已完成）
- [ ] 二维码/条形码生成库集成
- [ ] 模板编辑器 UI
- [ ] 联调测试

---

## 📄 依赖项

```xml
<PackageReference Include="Fleck" Version="1.2.0" />
<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
<PackageReference Include="CommunityToolkit.Mvvm" Version="8.2.2" />
```

### 推荐添加
- `ZXing.Net` - 二维码生成
- `BarcodeLib` - 条形码生成
- `FFmpeg.AutoGen` - FFmpeg 集成

---

## 🐛 常见问题

### Q: WebSocket 连接失败？
A: 检查端口是否被占用，防火墙是否允许。

### Q: 打印机无法识别？
A: 检查打印机驱动是否正确安装，确保打印机在线。

### Q: 模板渲染错误？
A: 检查 XML 语法是否正确，变量路径是否匹配数据。

### Q: 日志不显示？
A: 确保 `Logger.Instance.BindToObservable()` 已调用。

---

## 📞 技术支持

- 📧 Email: support@example.com
- 🐛 Issue: [Gitee Issues](https://gitee.com/ai-code_4/warehouse-web-socket-tools/issues)

---

## 📜 许可证

MIT License

---

_最后更新：2026-03-16_