# Repository Guidelines ## 项目结构与模块组织 本仓库包含两个核心应用： - `WIDESEAWCS_Client/`：Vue 3 + Vite 前端，主要目录包括 `src/views`、`src/components`、`src/api`、`src/router`、`src/store`。 - `WIDESEAWCS_Server/`：ASP.NET Core 后端解决方案（`WIDESEAWCS_Server.sln`），按分层组织为 `WIDESEAWCS_*Service`、`WIDESEAWCS_*Repository`、`WIDESEAWCS_Core`、`WIDESEAWCS_Domain`，调度与设备相关代码在 `WIDESEAWCS_Tasks` 与 `WIDESEAWCS_QuartzJob`。 测试主要位于 `WIDESEAWCS_Server/WIDESEAWCS_Tests`（xUnit），另外还有领域与集成测试项目。 ## 构建、测试与本地开发命令 - 前端（在 `WIDESEAWCS_Client/` 执行）： - `npm install`：安装依赖。 - `npm run serve`：启动本地开发服务（Vite）。 - `npm run build`：构建生产资源。 - `npm run lint`：执行 ESLint 检查。 - 后端（在 `WIDESEAWCS_Server/` 执行）： - `dotnet restore WIDESEAWCS_Server.sln`：还原 NuGet 依赖。 - `dotnet build WIDESEAWCS_Server.sln`：编译全部后端项目。 - `dotnet run --project WIDESEAWCS_Server`：本地启动 API。 - `dotnet test WIDESEAWCS_Tests/WIDESEAWCS_Tests.csproj`：运行单元测试。 ## 开发流程强制规范 - 所有任务必须在 `Code/WCS/.worktrees/` 独立 worktree 中开发，不直接在主工作区改动。 - 分支命名统一：`feat/<模块>-<主题>`、`fix/<模块>-<问题>`、`refactor/<模块>-<主题>`、`docs/<主题>`。 - 每次提交前至少执行与改动相关的最小验证（前端改动跑 `npm run lint`；后端改动跑 `dotnet test` 或最小可运行验证）。 - 禁止一次提交混入无关重构、格式化噪声或大面积文件移动。 ## 代码风格与命名规范 - C#：4 空格缩进；类型/方法/属性使用 `PascalCase`；局部变量和参数使用 `camelCase`；接口使用 `I` 前缀。 - Vue/JS：遵循现有 ESLint 配置与项目既有模式；文件名应与功能一致（如 `TaskController.cs`、功能目录下 `index.vue`）。 - 默认要求：对新增或修改的代码添加详细中文注释，至少包含方法目的、参数含义、返回值、关键逻辑步骤和异常处理说明。 - 注释要求可读、可维护，禁止“重复代码字面意思”的无效注释。 ## 数据一致性与事务规范 - 同一业务操作涉及多个数据对象（多表、多仓储、跨服务写入）同时改动时，必须使用数据库事务（Transaction）保证原子性。 - 事务范围只覆盖必要写操作，禁止将长耗时 IO/网络调用放入事务内，避免长事务锁表。 - 发生异常时必须回滚事务，并记录事务上下文（业务单号、关键主键、调用链标识）。 - 若涉及分布式或跨边界写入，需在 PR 中明确一致性策略（补偿、重试、幂等键）。 ## 接口、日志与异常规范 - API 返回结构保持统一，字段命名与现有后端序列化策略一致，避免随意变更响应字段。 - Service 层抛出的业务异常需包含可定位上下文（任务号、设备号、关键参数）。 - 日志级别规范：调试细节用 `Debug`，业务关键路径用 `Information`，可恢复异常用 `Warning`，不可恢复错误用 `Error`。 - 严禁吞异常；捕获后必须记录上下文并决定重抛或转换为业务错误。 - 涉及外部系统调用、IO、网络通信、设备通信、数据库访问的关键路径必须使用 `try-catch`；`catch` 中至少记录错误信息与关键参数，并保留原始堆栈（`throw;`），禁止仅 `throw ex;`。 ## 测试规范 - 主要测试框架为 xUnit，项目已引入 `Moq`、`FluentAssertions`、`coverlet.collector`。 - 测试命名建议：`MethodName_ShouldExpectedBehavior`。 - 涉及行为变化的改动，必须同步新增或更新测试后再合并。 ## 提交与 Pull Request 规范 - 提交历史以聚焦型前缀为主：`feat:`、`fix:`、`refactor:`、`docs:`、`chore:`（中文摘要）。 - 每条提交信息必须包含详细提交内容：至少说明改了什么、为什么改、影响了哪些模块/文件；禁止仅写“修改代码”“优化”这类模糊描述。 - PR 必须说明：改动内容、改动原因、影响路径、验证方式与结果、潜在风险与回滚方案。 - 仅在前端界面变更时附截图；接口变更需附请求/响应示例。 ## 安全与配置规范 - 禁止提交密钥、令牌、连接串明文；敏感配置必须放入环境变量或本地受控配置。 - `appsettings*.json` 的环境差异项需文档化，避免把开发机配置带入测试/生产。 - 涉及权限、鉴权、中间件顺序的改动，必须在 PR 中单独标注。