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 完成设备调度。

构建命令

# 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 而不记录日志。