From d01295c254063b3349a86a4474e04a62b284bd19 Mon Sep 17 00:00:00 2001
From: wanshenmean <cathay_xy@163.com>
Date: 星期二, 24 三月 2026 16:26:07 +0800
Subject: [PATCH] 一些配置
---
Code/WMS/AGENTS.md | 68 ++++++++++++++++++++++++++++++++++
1 files changed, 68 insertions(+), 0 deletions(-)
diff --git a/Code/WMS/AGENTS.md b/Code/WMS/AGENTS.md
new file mode 100644
index 0000000..5497ed3
--- /dev/null
+++ b/Code/WMS/AGENTS.md
@@ -0,0 +1,68 @@
+# Repository Guidelines
+
+## 项目结构与模块组织
+仓库由两个主项目组成：
+- `WIDESEA_WMSServer/`：ASP.NET Core 后端（解决方案：`WIDESEA_WMSServer.sln`）。
+- `WIDESEA_WMSClient/`：Vue 3 前端（Vite + Yarn）。
+
+后端按职责拆分：`WIDESEA_WMSServer/`（API 启动项目）、`WIDESEA_Core/`（基础设施/基类能力）、`WIDESEA_Model/`（实体模型）、`WIDESEA_DTO/`（数据传输对象）、`WIDESEA_I*Service/`（服务接口）、`WIDESEA_*Service/`（服务实现）。前端源码位于 `WIDESEA_WMSClient/src/`，单元测试位于 `WIDESEA_WMSClient/tests/unit/`。
+
+## 构建、测试与开发命令
+后端（在 `WIDESEA_WMSServer` 目录执行）：
+- `dotnet restore WIDESEA_WMSServer.sln`：还原 NuGet 依赖。
+- `dotnet build WIDESEA_WMSServer.sln`：构建全部后端项目。
+- `dotnet run --project WIDESEA_WMSServer/WIDESEA_WMSServer.csproj`：本地启动 API。
+
+前端（在 `WIDESEA_WMSClient` 目录执行）：
+- `npm install`：安装依赖。
+- `npm run serve`：启动本地开发服务（Vite）。
+- `npm run build`：构建生产资源。
+- `npm run lint`：执行 ESLint 检查。
+
+## 开发流程强制规范
+
+- 所有任务必须在 `Code/WMS/.worktrees/<task-name>` 独立 worktree 中开发，不直接在主工作区改动。
+- 分支命名统一：`feat/<模块>-<主题>`、`fix/<模块>-<问题>`、`refactor/<模块>-<主题>`、`docs/<主题>`。
+- 每次提交前至少执行与改动相关的最小验证（前端改动跑 `npm run lint`；后端改动跑 `dotnet test` 或最小可运行验证）。
+- 禁止一次提交混入无关重构、格式化噪声或大面积文件移动。
+
+## 代码风格与命名约定
+
+前端使用 Vue Standard ESLint 规则，缩进为 4 空格（见 `package.json`）。Vue 组件采用 PascalCase；扩展配置建议放在 `src/extension/{domain}/{entity}.js`。
+
+后端遵循现有分层与命名：`I{Entity}Service`（接口）、`{Entity}Service`（实现）、`{Entity}Controller`（控制器）。新增代码应保持与现有 Autofac 注册、基础 Controller/Service 模式一致。
+
+默认要求：对新增或修改的代码添加详细中文注释，至少包含方法目的、参数含义、返回值、关键逻辑步骤和异常处理说明。
+
+注释要求可读、可维护，禁止“重复代码字面意思”的无效注释。
+
+## 数据一致性与事务规范
+
+- 同一业务操作涉及多个数据对象（多表、多仓储、跨服务写入）同时改动时，必须使用数据库事务（Transaction）保证原子性。
+- 事务范围只覆盖必要写操作，禁止将长耗时 IO/网络调用放入事务内，避免长事务锁表。
+- 发生异常时必须回滚事务，并记录事务上下文（业务单号、关键主键、调用链标识）。
+- 若涉及分布式或跨边界写入，需在 PR 中明确一致性策略（补偿、重试、幂等键）。
+
+## 接口、日志与异常规范
+
+- API 返回结构保持统一，字段命名与现有后端序列化策略一致，避免随意变更响应字段。
+- Service 层抛出的业务异常需包含可定位上下文（任务号、设备号、关键参数）。
+- 日志级别规范：调试细节用 `Debug`，业务关键路径用 `Information`，可恢复异常用 `Warning`，不可恢复错误用 `Error`。
+- 严禁吞异常；捕获后必须记录上下文并决定重抛或转换为业务错误。
+- 涉及外部系统调用、IO、网络通信、设备通信、数据库访问的关键路径必须使用 `try-catch`；`catch` 中至少记录错误信息与关键参数，并保留原始堆栈（`throw;`），禁止仅 `throw ex;`。
+
+## 测试指南
+
+前端测试采用 Vue 单元测试（`tests/unit/*.spec.js`）。涉及 UI 逻辑或接口交互变更时，应补充或更新测试，并执行 `yarn test:unit`。
+
+当前解决方案中未包含独立后端测试项目。后端改动至少需完成构建与关键 API 手工验证；复杂业务逻辑建议新增测试项目（如 xUnit）并纳入解决方案。
+
+## 提交与合并请求规范
+最近提交普遍采用 Conventional Commit 前缀：`feat:`、`fix:`、`refactor:`、`docs:`、`chore:`（中文描述）。建议一次提交聚焦一个明确改动点。
+
+PR 建议包含：
+- 变更目的与业务影响说明；
+- 涉及模块与目录范围（前端/后端）；
+- 验证证据（已执行命令与结果）；
+- UI 变更截图或录屏；
+- 关联任务或问题编号（如有）。
--
Gitblit v1.9.3