陕煤新能源立库
编辑 | blame | 历史 | 原始文档

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)

# 安装依赖（在 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)

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