CLAUDE.md

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

项目概述

WIDESEAWCS_S7Simulator 是一个 S7 PLC 模拟器系统，用于模拟西门子 S7 系列 PLC 的服务器行为。采用前后端分离架构，支持同时运行多个 PLC 实例，并提供 Web 界面进行管理。

技术栈

后端
- .NET 6.0 / ASP.NET Core Web API
- HslCommunication 12.6.3（S7 通信库）
- Swagger/OpenAPI

前端
- Vue 3.5 + TypeScript 5.7
- Vite 6.0（开发服务器 + 构建）
- Element Plus 2.9（UI 组件库）
- Pinia（状态管理）
- Vue Router 4.5
- Axios（HTTP 客户端）

常用命令

后端开发

# 运行后端服务器（默认端口 5137）
cd WIDESEAWCS_S7Simulator.Server
dotnet run

# 构建解决方案
dotnet build WIDESEAWCS_S7Simulator.slnx

# 运行单元测试
dotnet test WIDESEAWCS_S7Simulator.UnitTests

# 发布 Release 版本
dotnet publish -c Release

前端开发

# 进入前端目录
cd WIDESEAWCS_S7Simulator.Web

# 安装依赖（使用 pnpm）
pnpm install

# 启动开发服务器（默认端口 3000，代理 /api 到后端 5137）
pnpm dev

# 构建生产版本
pnpm build

# 预览生产构建
pnpm preview

同时启动前后端

在两个终端中分别运行：
- 终端 1：cd WIDESEAWCS_S7Simulator.Server && dotnet run
- 终端 2：cd WIDESEAWCS_S7Simulator.Web && pnpm dev

访问 http://localhost:3000 使用 Web 界面。

项目架构

高层架构

┌─────────────────────────────────────────────────────────────┐
│                        Vue 3 前端                            │
│  (WIDESEAWCS_S7Simulator.Web - 端口 3000)                   │
│  - 实例列表、创建、编辑页面                                  │
│  - Axios API 客户端（代理到 /api）                          │
└─────────────────────────────────────────────────────────────┘
                              ↓
                              ↓ HTTP/REST API
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   ASP.NET Core API                          │
│  (WIDESEAWCS_S7Simulator.Server - 端口 5137)                │
│  - SimulatorInstancesController (实例 CRUD)                 │
│  - MemoryController (内存读写)                              │
│  - ClientsController (客户端连接)                          │
└─────────────────────────────────────────────────────────────┘
                              ↓
                              ↓ 依赖注入
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                   Core 业务逻辑层                            │
│  (WIDESEAWCS_S7Simulator.Core)                              │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  SimulatorInstanceManager - 实例生命周期管理          │   │
│  └─────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  S7ServerInstance - 单个 S7 服务器实例               │   │
│  │  - HslCommunication.SiemensS7Server                  │   │
│  │  - MemoryStore (内存区域管理)                        │   │
│  │  - 客户端连接监控                                    │   │
│  └─────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  MemoryStore - 内存区域抽象                          │   │
│  │  - MRegion / DBRegion / IRegion / QRegion            │   │
│  │  - TRegion / CRegion                                 │   │
│  └─────────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  FilePersistenceService - 配置持久化到 Data 目录      │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

项目结构说明

WIDESEAWCS_S7Simulator.Core - 核心业务逻辑
- Entities/: 实体类（InstanceConfig, InstanceState, S7ClientConnection）
- Enums/: 枚举（SiemensPLCType, InstanceStatus）
- Interfaces/: 核心接口（IS7ServerInstance, ISimulatorInstanceManager, IMemoryStore）
- Manager/: SimulatorInstanceManager（管理多个实例）
- Server/: S7ServerInstance（单个 S7 服务器实现）
- Memory/: 内存区域实现（MRegion, DBRegion, IRegion, QRegion, TRegion, CRegion, MemoryStore）
- Persistence/: FilePersistenceService（配置持久化）

WIDESEAWCS_S7Simulator.Server - ASP.NET Core Web API
- Controllers/: API 控制器
- Program.cs: 应用入口，配置 CORS、依赖注入、Swagger

WIDESEAWCS_S7Simulator.Application - 应用层（目前为空）

WIDESEAWCS_S7Simulator.Web - Vue 3 前端
- src/api/index.ts: Axios API 客户端
- src/types/index.ts: TypeScript 类型定义
- src/views/: 页面组件（HomeView, CreateView, EditView, DetailsView）
- src/router/: Vue Router 配置
- vite.config.ts: Vite 配置（开发服务器代理到后端）

WIDESEAWCS_S7Simulator.UnitTests - 单元测试
- Memory/: 内存区域测试

数据持久化

实例配置保存在 WIDESEAWCS_S7Simulator.Server/Data/ 目录下，每个实例一个 JSON 文件。

启动时会自动加载已保存的实例（默认不自动启动，需通过 API 或 UI 手动启动）。

API 端点说明

所有 API 以 /api/ 为前缀，主要控制器：
- /api/SimulatorInstances/* - 实例管理（CRUD、启动/停止/重启）
- /api/Memory/* - 内存读写
- /api/Clients/* - 客户端连接信息

完整 API 文档：启动后端后访问 http://localhost:5137/swagger

内存区域说明

S7 PLC 内存区域由 MemoryStore 统一管理：
- M 区：位存储器（默认 1024 字节）
- DB 区：数据块（可配置块数量和大小）
- I 区：输入区（默认 128 字节）
- Q 区：输出区（默认 128 字节）
- T 区：定时器（默认 100 个）
- C 区：计数器（默认 100 个）

地址格式支持：M100, DB1.DBD0, I0.0, Q0.0, T1, C1

开发注意事项

提交代码规范

代码修改后不要自动提交 git
只有用户明确说"提交"时才执行 git commit

序列化配置

后端使用 camelCase JSON 命名策略（System.Text.Json），枚举会序列化为字符串。

CORS 配置

开发环境允许以下源访问 API：http://localhost:3000, http://localhost:5173, http://localhost:5174, http://localhost:3001

HSL 激活码

S7ServerInstance 支持通过 InstanceConfig.ActivationKey 设置 HSL Communication 库的激活码。

客户端连接监控

S7ServerInstance 每 5 秒通过检查 TCP 连接来监控客户端连接状态（使用 IPGlobalProperties.GetActiveTcpConnections()）。

端口冲突

创建实例时需确保端口未被占用，多个实例不能使用相同端口。