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/<task-name> 独立 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 中单独标注。