# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

**WIDESEA** 是一个工业仓储自动化系统，包含两个核心子系统：

- **WCS**（仓库控制系统）：直接控制堆垛机、输送线、机器人、穿梭车等物理设备，与 PLC 通信
- **WMS**（仓库管理系统）：管理库存、入库、出库任务、盘点等业务逻辑

两个系统通过 HTTP API 交互，WMS 依赖 WCS 完成设备调度。

## 构建命令

```bash
# WCS 后端（端口 9292）
dotnet build WCS/WIDESEAWCS_Server/WIDESEAWCS_Server.sln
dotnet run --project WCS/WIDESEAWCS_Server/WIDESEAWCS_Server/WIDESEAWCS_Server.csproj

# WMS 后端（端口 9291）
dotnet build WMS/WIDESEA_WMSServer/WIDESEA_WMSServer.sln
dotnet run --project WMS/WIDESEA_WMSServer/WIDESEA_WMSServer/WIDESEA_WMSServer.csproj

# WCS 前端
cd WCS/WIDESEAWCS_Client && npm run serve

# WMS 前端
cd WMS/WIDESEA_WMSClient && npm run serve

# S7 模拟器
cd 测试工具/WIDESEAWCS_S7Simulator/WIDESEAWCS_S7Simulator.Web && npm run dev
```

## 架构概览

```
┌─────────────────────────────────────────────────────────────┐
│                        WCS (端口 9292)                       │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────┐  │
│  │   Quartz    │  │  Communicator │  │   Redis L1+L2      │  │
│  │   Jobs      │→ │  (PLC协议)    │  │   Cache            │  │
│  └─────────────┘  └──────────────┘  └────────────────────┘  │
│         ↓                                                    │
│  ┌─────────────────────────────────────────────────────┐     │
│  │  TcpSocketServer (端口 2000) / WebSocket (端口 9296) │     │
│  └─────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────┘
                              ↑ HTTP API
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                        WMS (端口 9291)                       │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────┐  │
│  │   Tasks     │  │    Stock     │  │    Inbound/        │  │
│  │   Service   │  │    Service   │  │    Outbound        │  │
│  └─────────────┘  └──────────────┘  └────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

## WCS 项目结构

| 项目 | 用途 |
|------|------|
| `WIDESEAWCS_Server` | 主 API 入口（端口 9292） |
| `WIDESEAWCS_Core` | 框架（数据库、缓存、DI、日志） |
| `WIDESEAWCS_Common` | 常量、枚举、Redis 键 |
| `WIDESEAWCS_Model` | 实体模型 |
| `WIDESEAWCS_DTO` | 数据传输对象 |
| `WIDESEAWCS_Communicator` | 工业协议（Modbus、S7、Omron 等） |
| `WIDESEAWCS_Tasks` | 后台设备控制作业 |
| `WIDESEAWCS_QuartzJob` | Quartz.NET 调度 |

**详细 WCS 规范**：见 `WCS/WIDESEAWCS_Server/CLAUDE.md`

## WMS 项目结构

| 项目 | 用途 |
|------|------|
| `WIDESEA_WMSServer` | 主 API 入口（端口 9291） |
| `WIDESEA_Core` | 框架工具 |
| `WIDESEA_Common` | 常量、枚举 |
| `WIDESEA_Model` | 实体模型 |
| `WIDESEA_*Service` | 业务逻辑服务 |

## 关键设计

- **ORM**：SqlSugar（支持多数据库）
- **依赖注入**：Autofac，通过 `AutofacModuleRegister` 注册
- **缓存**：Redis L1（内存）+ L2（Redis）混合缓存
- **调度**：Quartz.NET
- **实时通信**：SignalR WebSocket
- **设备协议**：存储在数据库 `Dt_DeviceProtocol` 表，非配置文件

## 技术栈

- **后端**：.NET 6/8，ASP.NET Core，C# 12
- **前端**：Vue 3，Element Plus，Vite，Pinia
- **数据库**：SQL Server
- **缓存**：Redis

## 注释与文档 (强制)

- **XML 文档注释**: 所有 `public` 类、接口、方法、属性**必须**包含 XML 文档注释 (`/// <summary>...</summary>`)，解释其用途、参数和返回值。
- **行内注释**: 对于复杂的业务逻辑、算法实现或非直观的代码块，**必须**添加 `//` 行内注释解释“为什么这么做”。
- **TODO 标记**: 如果代码未完成或有临时方案，必须使用 `// TODO: 说明` 标记。

## 通用规范

- **异步编程**: 所有 I/O 操作必须使用 `async/await`。库代码请使用 `ConfigureAwait(false)`。

- **命名**:

  - 接口以 "I" 开头 (例如: `IUserService`)。
  - 类名、方法名使用 **PascalCase**。
  - 私有字段、局部变量使用 **camelCase**。

- **命名空间**: 使用 **文件作用域命名空间** (`namespace MyApp.Api;`)。

- 当需要对两个或以上的数据库执行修改/添加操作并保证事务一致性时，请使用工作单元管理器（`IUnitOfWorkManage`）的事务方法：

  - **同步场景**：调用 `BeginTran(Func<WebResponseContent> func)`，传入同步委托。
  - **异步场景**：调用 `BeginTranAsync(Func<Task<WebResponseContent>> funcAsync)`，传入异步委托。

  **注意**：`IUnitOfWorkManage` 需通过依赖注入（DI）获取。该方法会自动管理事务的提交与回滚，只需确保所有数据库操作在传入的委托内完成。

## 🚫 严禁事项

- **严禁** 生成没有注释的代码 (尤其是公共方法)。
- **严禁** 使用 `Task.Result` 或 `Task.Wait()`。
- **严禁** 在异步上下文中使用 `.ToList()` (必须用 `.ToListAsync()`)。
- **严禁** 直接暴露实体 (Entity)，必须使用 DTO。
- **严禁** 捕获 `Exception` 而不记录日志。