Repository Guidelines

项目结构与模块组织

本仓库是基于 .NET 6 + Vue 3 的 S7 PLC 模拟器，采用前后端分离架构。

• WIDESEAWCS_S7Simulator.Core：核心领域模型、内存区域（M/DB/I/Q/T/C）、模拟器运行时与持久化能力。
• WIDESEAWCS_S7Simulator.Application：应用层抽象与协议/应用服务。
• WIDESEAWCS_S7Simulator.Server：ASP.NET Core Web API（Controllers/、Program.cs），运行数据位于 Data/。
• WIDESEAWCS_S7Simulator.Web：Vue 3 + TypeScript 前端（src/views、src/api、src/router、src/types）。
• WIDESEAWCS_S7Simulator.UnitTests：xUnit 单元测试项目。
• docs/：设计说明与协议文档。

构建、测试与本地开发命令

以下命令默认在仓库根目录执行。

• dotnet restore WIDESEAWCS_S7Simulator.slnx：还原 NuGet 依赖。
• dotnet build WIDESEAWCS_S7Simulator.slnx：构建后端所有项目。
• dotnet test WIDESEAWCS_S7Simulator.UnitTests：运行 xUnit 测试。
• dotnet run --project WIDESEAWCS_S7Simulator.Server：启动后端 API（默认 http://localhost:5137）。
• cd WIDESEAWCS_S7Simulator.Web && pnpm install：安装前端依赖。
• cd WIDESEAWCS_S7Simulator.Web && pnpm dev：启动前端开发服务（通常为 http://localhost:3000 或 5173）。
• cd WIDESEAWCS_S7Simulator.Web && pnpm build：执行类型检查并构建生产包。

代码风格与命名规范

• C#：4 空格缩进；类型/方法使用 PascalCase，局部变量/参数使用 camelCase，接口使用 I 前缀。
• TypeScript/Vue：页面组件使用 PascalCase（如 DetailsView.vue）；变量与函数使用 camelCase；API DTO 类型集中在 src/types。
• 控制器保持轻量，业务逻辑尽量下沉到 Core/Application 服务。
• 优先编写职责单一、体量可控的文件，避免“大而全”类。
• 新增或修改代码时，必须补充必要注释：说明关键业务意图、协议字段含义、边界条件或非直观实现；避免无意义注释。
• 所有新增注释必须使用中文，并确保以 UTF-8 等统一编码保存，提交前需自检注释显示正常，严禁出现乱码。

测试规范

• 测试框架：xUnit（配套 Microsoft.NET.Test.Sdk、coverlet.collector）。
• 测试命名建议采用“行为_结果”模式，例如：MemoryStoreTests.ReadBit_ReturnsExpectedValue。
• 涉及内存地址解析、协议模板、持久化、实例生命周期的改动，必须同步补充或更新测试。
• 提交 PR 前至少执行一次 dotnet test。

提交与 Pull Request 规范

• 提交信息遵循当前仓库习惯：feat: ...、fix: ...、refactor: ...、docs: ...（可使用中文描述）。
• 提交代码时必须编写明确的提交详情，至少说明：做了什么、为什么做、影响了哪些模块或文件。
• 每次提交聚焦一个逻辑变更，避免混入无关文件。
• PR 需包含：变更目的、关键改动、测试结果（如 dotnet test、pnpm build），UI 改动附截图或录屏。
• 若关联任务/缺陷，请附上编号，并注明配置或数据迁移影响。
• 未收到明确“提交”指令前，禁止执行 git commit、git push 或创建 PR。