# 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 构建。用于管理自动化物料处理设备（堆垛机、输送线、机器人、穿梭车等）的工业仓储环境。

## 构建与运行命令

```bash
# 构建整个解决方案
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

### 数据流向

1. API Controllers → Services → Repositories → SqlSugar → SQL Server
2. Quartz Jobs（定时调度） → 设备控制作业 → Communicators → 物理设备
3. 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`）。

## 重要实现注意事项

1. **启动初始化顺序很重要**：Redis 就绪后才能运行 `ApiRouteCacheWarmupHostedService`
2. **Quartz 任务表** 通过 `QuartzJobDataTableHostedService` 在启动时自动创建
3. **Socket 服务器** 作为单例 `TcpSocketServer` 由托管服务运行
4. **Redis 缓存同步**：可配置 `EnableAutoSync` 选项，定期将 Redis 同步到 L1 内存缓存
5. **设备协议配置** 存储在数据库（`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