| | |
|---|
| | | # Repository Guidelines |
|---|
| | | # Repository Guidelines |
|---|
| | | |
|---|
| | | ## Project Structure & Module Organization |
|---|
| | | This repository is a .NET 6 + Vue 3 split-stack S7 PLC simulator. |
|---|
| | | ## 项目结构与模块组织 |
|---|
| | | 本仓库是基于 .NET 6 + Vue 3 的 S7 PLC 模拟器，采用前后端分离架构。 |
|---|
| | | |
|---|
| | | - `WIDESEAWCS_S7Simulator.Core`: domain entities, memory regions (`M/DB/I/Q/T/C`), simulator runtime, persistence. |
|---|
| | | - `WIDESEAWCS_S7Simulator.Application`: application-layer abstractions and protocol/application services. |
|---|
| | | - `WIDESEAWCS_S7Simulator.Server`: ASP.NET Core Web API (`Controllers/`, `Program.cs`), runtime data under `Data/`. |
|---|
| | | - `WIDESEAWCS_S7Simulator.Web`: Vue 3 + TypeScript frontend (`src/views`, `src/api`, `src/router`, `src/types`). |
|---|
| | | - `WIDESEAWCS_S7Simulator.UnitTests`: xUnit tests for core/application behavior. |
|---|
| | | - `docs/`: design and protocol notes. |
|---|
| | | - `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/`：设计说明与协议文档。 |
|---|
| | | |
|---|
| | | ## Build, Test, and Development Commands |
|---|
| | | Run from repository root unless noted. |
|---|
| | | ## 构建、测试与本地开发命令 |
|---|
| | | 以下命令默认在仓库根目录执行。 |
|---|
| | | |
|---|
| | | - `dotnet restore WIDESEAWCS_S7Simulator.slnx`: restore NuGet packages. |
|---|
| | | - `dotnet build WIDESEAWCS_S7Simulator.slnx`: build backend projects. |
|---|
| | | - `dotnet test WIDESEAWCS_S7Simulator.UnitTests`: run xUnit tests. |
|---|
| | | - `dotnet run --project WIDESEAWCS_S7Simulator.Server`: start API (default `http://localhost:5137`). |
|---|
| | | - `cd WIDESEAWCS_S7Simulator.Web && pnpm install`: install frontend deps. |
|---|
| | | - `cd WIDESEAWCS_S7Simulator.Web && pnpm dev`: start Vite dev server (typically `http://localhost:3000` or `5173`). |
|---|
| | | - `cd WIDESEAWCS_S7Simulator.Web && pnpm build`: type-check + production build. |
|---|
| | | - `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`：执行类型检查并构建生产包。 |
|---|
| | | |
|---|
| | | ## Coding Style & Naming Conventions |
|---|
| | | - C#: 4-space indentation, `PascalCase` for types/methods, `camelCase` for locals/parameters, interfaces prefixed with `I`. |
|---|
| | | - TypeScript/Vue: `PascalCase` for view components (e.g., `DetailsView.vue`), `camelCase` for variables/functions, keep API DTO types in `src/types`. |
|---|
| | | - Keep controllers thin; put business rules in Core/Application services. |
|---|
| | | - Prefer small, focused files over large mixed-responsibility classes. |
|---|
| | | ## 代码风格与命名规范 |
|---|
| | | - C#：4 空格缩进；类型/方法使用 `PascalCase`，局部变量/参数使用 `camelCase`，接口使用 `I` 前缀。 |
|---|
| | | - TypeScript/Vue：页面组件使用 `PascalCase`（如 `DetailsView.vue`）；变量与函数使用 `camelCase`；API DTO 类型集中在 `src/types`。 |
|---|
| | | - 控制器保持轻量，业务逻辑尽量下沉到 Core/Application 服务。 |
|---|
| | | - 优先编写职责单一、体量可控的文件，避免“大而全”类。 |
|---|
| | | - 新增或修改代码时，必须补充必要注释：说明关键业务意图、协议字段含义、边界条件或非直观实现；避免无意义注释。 |
|---|
| | | - 所有新增注释必须使用中文，并确保以 UTF-8 等统一编码保存，提交前需自检注释显示正常，严禁出现乱码。 |
|---|
| | | |
|---|
| | | ## Testing Guidelines |
|---|
| | | - Framework: xUnit (`Microsoft.NET.Test.Sdk`, `coverlet.collector`). |
|---|
| | | - Name tests by behavior, e.g., `MemoryStoreTests.ReadBit_ReturnsExpectedValue`. |
|---|
| | | - Add/update tests for any change to memory parsing, protocol templates, persistence, or instance lifecycle. |
|---|
| | | - Run `dotnet test` before opening a PR. |
|---|
| | | ## 测试规范 |
|---|
| | | - 测试框架：xUnit（配套 `Microsoft.NET.Test.Sdk`、`coverlet.collector`）。 |
|---|
| | | - 测试命名建议采用“行为_结果”模式，例如：`MemoryStoreTests.ReadBit_ReturnsExpectedValue`。 |
|---|
| | | - 涉及内存地址解析、协议模板、持久化、实例生命周期的改动，必须同步补充或更新测试。 |
|---|
| | | - 提交 PR 前至少执行一次 `dotnet test`。 |
|---|
| | | |
|---|
| | | ## Commit & Pull Request Guidelines |
|---|
| | | - Follow Conventional Commit style seen in history: `feat: ...`, `fix: ...`, `refactor: ...` (Chinese summaries are acceptable). |
|---|
| | | - Keep one logical change per commit; avoid bundling unrelated files. |
|---|
| | | - PRs should include: purpose, key changes, test evidence (`dotnet test`, `pnpm build`), and screenshots/GIFs for UI changes. |
|---|
| | | - Link related issue/task IDs and call out any config/data migration impacts. |
|---|
| | | ## 提交与 Pull Request 规范 |
|---|
| | | - 提交信息遵循当前仓库习惯：`feat: ...`、`fix: ...`、`refactor: ...`、`docs: ...`（可使用中文描述）。 |
|---|
| | | - 提交代码时必须编写明确的提交详情，至少说明：做了什么、为什么做、影响了哪些模块或文件。 |
|---|
| | | - 每次提交聚焦一个逻辑变更，避免混入无关文件。 |
|---|
| | | - PR 需包含：变更目的、关键改动、测试结果（如 `dotnet test`、`pnpm build`），UI 改动附截图或录屏。 |
|---|
| | | - 若关联任务/缺陷，请附上编号，并注明配置或数据迁移影响。 |
|---|
| | | - 未收到明确“提交”指令前，禁止执行 `git commit`、`git push` 或创建 PR。 |
|---|
