# 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。