# CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。

## 项目概述

这是一个 **WCS（仓库控制系统）** - 鄯美新能源仓库控制系统，包含：

- **WIDESEAWCS_Client** - Vue 3 前端应用（Element Plus UI）
- **WIDESEAWCS_Server** - ASP.NET Core 6.0 后端 API 服务器

系统管理自动化仓库作业，包括堆垛机、输送线、穿梭车和机械手的物料搬运任务（组盘、换盘、拆盘）。

---

## 常用命令

### 前端 (WIDESEAWCS_Client)

```bash
# 安装依赖（在 Client 目录中）
cd WIDESEAWCS_Client
npm install

# 开发服务器
npm run serve

# 生产构建
npm run build

# 代码检查
npm run lint
```

**Node.js 18+ 注意事项**：如果 `npm run serve` 因 OpenSSL 错误失败，`package.json` 脚本已包含 `SET NODE_OPTIONS=--openssl-legacy-provider` 解决方案。

### 后端 (WIDESEAWCS_Server)

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

# 运行服务器
dotnet run --project WIDESEAWCS_Server

# 运行测试
dotnet test WIDESEAWCS_Tests
```

**服务器端口**：API 运行在 `http://*:9292`（可在 `appsettings.json` 中配置）

---

## 架构

### 前端架构 (Vue 3)

**技术栈**：
- Vue 3 + Vite
- Element Plus UI 框架
- Vue Router（hash 模式）
- Vuex 状态管理
- Axios HTTP 请求
- SignalR 实时通信（可选）

**关键目录**：
- `src/views/` - 页面组件（Home、Login、system、basicinfo、taskinfo、charts）
- `src/components/basic/` - 可复用组件，包括 `ViewGrid`（数据表格组件）
- `src/api/` - HTTP 客户端（`http.js`），带令牌管理和拦截器
- `src/router/` - 路由定义，带身份验证守卫
- `src/store/` - Vuex 存储，用于用户信息和权限
- `src/uitils/` - 工具函数

**HTTP 客户端** (`src/api/http.js`)：
- 基础 URL 默认值：开发环境（`http://127.0.0.1:9292/`）、生产环境（`http://115.159.85.185:9292/`）
- 自动包含 `Authorization: Bearer {token}` 请求头
- 收到 `wideseawcs_exp` 响应头时自动刷新令牌
- 401 自动重定向到登录页
- 导出方法：`post()`、`get()`、`download()`、`ajax()`

**全局属性**（在 `main.js` 中挂载）：
- `this.$http` - HTTP 客户端
- `this.base` - 通用工具
- `this.permission` - 权限检查
- `this.$global` - 全局配置（SignalR 启用标志、表格标签显示）

### 后端架构 (ASP.NET Core)

**技术栈**：
- ASP.NET Core 6.0 Web API
- Autofac DI，使用 `IDependency` 标记接口实现自动注册
- Quartz.NET 定时任务（设备通信循环）
- SqlSugar ORM 数据库访问
- Redis（通过 `WIDESEAWCS_RedisService` 实现 L1+L2 混合缓存）
- TCP Socket 服务器（端口 2000）用于实时设备通信
- HslCommunication 库用于 PLC/硬件通信

**项目结构**：
```
WIDESEAWCS_Server/          # 主 API 服务器
WIDESEAWCS_Core/            # 核心基础设施：基类、DI、扩展、中间件
WIDESEAWCS_Model/           # 数据模型和 DTO
WIDESEAWCS_Communicator/    # 硬件通信驱动（西门子、欧姆龙、Modbus 等）
WIDESEAWCS_QuartzJob/       # 任务调度基础设施和设备抽象
WIDESEAWCS_Tasks/           # Quartz 任务实现（设备通信循环）
WIDESEAWCS_RedisService/    # Redis 服务：缓存、锁、计数器、发布订阅
WIDESEAWCS_*Repository/     # 数据访问层实现
WIDESEAWCS_*Service/        # 业务服务层
WIDESEAWCS_Tests/           # 单元测试
```

**依赖注入模式**：
- 实现 `IDependency` 标记接口的服务由 Autofac **自动注册**
- 位于 `AutofacModuleRegister` 中扫描所有程序集
- 添加前使用 `services.Remove()` 覆盖现有注册

**缓存层** (`ICacheService`)：
- L1（内存）+ L2（Redis）混合缓存
- 实现：`MemoryCacheService`、`RedisCacheService`、`HybridCacheService`
- 常用方法：`Add`、`Get<T>`、`Remove`、`RemoveByPrefix`、`GetOrAdd<T>`

**设备通信**：
- 任务继承 `JobBase` 并实现 `IJob`
- 设备类型：`IStackerCrane`（堆垛机）、`IConveyorLine`（输送线）、`IShuttleCar`（穿梭车）、`IRobot`（机械手）
- 通信器：`SiemensS7Communicator`、`OmronEtherNetCommunicator`、`ModbusTcpCommunicator`、`SerialPortCommunicator`
- TCP Socket 服务器（端口 2000）由 `SocketServerHostedService` 管理

---

## 关键集成点

### 系统集成 URL (BaseAPI 常量)
- WMS：`http://localhost:9291/api/`
- WCS（本服务器）：`http://localhost:9292/api/`
- MES：`http://localhost:9293/api/`
- ERP：`http://localhost:9294/api/`

### 机械手通信系统
机械手控制的模块化架构：
- `RobotClientManager` - TCP 客户端连接管理
- `RobotStateManager` - 线程安全的机械手状态缓存
- `RobotMessageHandler` - TCP 消息解析
- `RobotTaskProcessor` - 任务执行和状态转换
- 任务类型：`GroupPallet (500)` 组盘、`ChangePallet (510)` 换盘、`SplitPallet (520)` 拆盘

### 配置 (appsettings.json)
关键设置：
- `"urls": "http://*:9292"` - 服务器端口
- `"QuartzJobAutoStart": true` - 自动启动定时任务
- `"SocketServer:Enabled": true` - 启用 TCP 服务器
- `"RedisConfig:Enabled": true` - 启用 Redis 缓存
- `"DBType": "SqlServer"` - 数据库类型

---

## 开发指南

### 添加新功能

**后端**：
1. 在 `WIDESEAWCS_IService/` 中创建服务接口
2. 在 `WIDESEAWCS_Service/` 中创建服务实现，实现 `IDependency`
3. 在 `WIDESEAWCS_Tasks/` 中创建任务，继承 `JobBase` 和 `IJob`
4. 在 `WIDESEAWCS_QuartzJob/Device/` 中添加设备类型

**前端**：
1. 在 `src/views/` 中添加视图
2. 在 `src/router/index.js` 中添加路由
3. 使用 `$http.post()` 和 `$http.get()` 进行 API 调用
4. 使用 `ViewGrid` 组件显示数据表格

### 代码风格
- **C#**：类型/方法/属性使用 PascalCase，局部变量/参数使用 camelCase。4 空格缩进，大括号换行。
- **JavaScript/Vue**：遵循现有模式，新组件使用 Vue 3 Composition API
- **注释**：为新增/修改的代码添加详细的中文注释（方法目的、参数、返回值、逐行说明、异常处理）

### 重要说明
- 后端使用 **CamelCase** JSON 序列化
- 所有服务通过 Autofac 默认使用 **scoped** 生命周期
- Redis 连接在首次访问时延迟初始化
- 在任务中使用 `ConsoleHelper.WriteSuccessLine()` / `WriteErrorLine()` 进行控制台输出
- TCP Socket 服务器独立于 HTTP API 运行