CLAUDE.md

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

项目概述

WIDESEAWCS 是一个仓库控制系统，基于 ASP.NET Core 6.0 构建。用于管理自动化物料处理设备（堆垛机、输送线、机器人、穿梭车等）的工业仓储环境。

构建与运行命令

# 构建整个解决方案
dotnet build WIDESEAWCS_Server.sln

# 运行服务器（端口 9292）
dotnet run --project WIDESEAWCS_Server/WIDESEAWCS_Server.csproj

# 运行测试
dotnet test WIDESEAWCS_Tests/WIDESEAWCS_Tests.csproj

架构

项目结构

项目	用途
`WIDESEAWCS_Server`	主 Web API 入口（端口 9292）
`WIDESEAWCS_Core`	框架工具（数据库、缓存、依赖注入、日志、认证）
`WIDESEAWCS_Common`	常量、枚举、Redis 键定义
`WIDESEAWCS_Model`	数据库实体模型
`WIDESEAWCS_DTO`	数据传输对象
`WIDESEAWCS_Communicator`	工业设备通信协议（Modbus、Siemens S7、Omron 等）
`WIDESEAWCS_Tasks`	后台设备控制作业
`WIDESEAWCS_QuartzJob`	Quartz.NET 调度和派发逻辑
`WIDESEAWCS_RedisService`	L1+L2 混合缓存服务

关键设计模式

仓储模式：数据访问抽象（WIDESEAWCS_*Repository 项目）
服务层：业务逻辑封装（WIDESEAWCS_*Service 项目）
Autofac 依赖注入：通过 AutofacModuleRegister 模块注册
AOP 拦截：通过 UseServiceDIAttribute 实现缓存和日志切面
SqlSugar ORM：支持 MySQL、SQL Server、SQLite、Oracle、PostgreSQL

数据流向

API Controllers → Services → Repositories → SqlSugar → SQL Server
Quartz Jobs（定时调度） → 设备控制作业 → Communicators → 物理设备
Redis L1（内存） + L2（Redis）缓存层位于数据库前方

关键配置（appsettings.json）

Web API： http://*:9292
WebSocket： http://localhost:9296
TCP Socket 服务器： 0.0.0.0:2000
数据库： SQL Server，实例 .\WIDESEAWCS_ShanMei
Redis： 127.0.0.1:6379，密码 P@ssw0rd
JWT 过期时间： 120 分钟
Quartz： 自动启动

设备通信

WIDESEAWCS_Communicator 项目实现了多种工业协议：

ModbusTcpCommunicator
SiemensS7Communicator、SiemensS7200SmartCommunicator
OmronEtherNetCommunicator
AllenBrandlyEtherNetCommunicator
InovanceTcpCommunicator、InovanceAMTcp
SerialPortCommunicator

基础接口：IBaseCommunicator

后台作业

设备控制作业位于 WIDESEAWCS_Tasks/：

StackerCraneJob - 堆垛机控制
ConveyorLineJob、ConveyorLineNewJob - 输送线管理
RobotJob - 机械手控制
ShuttleCarJob - 穿梭车控制
SocketServer - 设备通信 TCP 服务器

API 结构

QuartzJob/Controllers/ - 设备信息、协议、派发、调度器
System/Controllers/ - 用户、角色、菜单、字典、日志
Task/Controllers/ - 任务管理和机器人任务
BasicInfo/Controllers/ - 路由配置

日志

使用 Serilog，按天滚动保留 30 天日志文件，同时集成 Seq（http://localhost:5341）。

重要实现注意事项

启动初始化顺序很重要：Redis 就绪后才能运行 ApiRouteCacheWarmupHostedService
Quartz 任务表 通过 QuartzJobDataTableHostedService 在启动时自动创建
Socket 服务器 作为单例 TcpSocketServer 由托管服务运行
Redis 缓存同步：可配置 EnableAutoSync 选项，定期将 Redis 同步到 L1 内存缓存
设备协议配置 存储在数据库（Dt_DeviceProtocol 表），而非配置文件中

注释与文档 (强制)

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

通用规范

异步编程: 所有 I/O 操作必须使用 async/await。库代码请使用 ConfigureAwait(false)。
命名:
接口以 "I" 开头 (例如: IUserService)。
类名、方法名使用 PascalCase。
私有字段、局部变量使用 camelCase。
命名空间: 使用 文件作用域命名空间 (namespace MyApp.Api;)。

🚫 严禁事项

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

🛠 技术栈

框架: .NET 8.0 (LTS)
语言: C# 12
ORM: SqlSugar
数据库: SQL Server
验证: FluentValidation
序列化: Newtonsoft.Json