@zhouhao4221/devflow-skills 0.3.6 → 0.3.7

package/plugins/req/skills/test_new/SKILL.md

@@ -3,31 +3,26 @@ name: test_new
 description: 创建测试 - 为新功能编写自动化测试用例或手动测试用例文档
 ---
 
-> **重要**：本命令的测试文件位置、运行命令、代码示例均从项目 CLAUDE.md 的「测试规范」章节读取，不内置任何项目细节。
-
 # 创建测试
 
-为新开发的功能创建自动化测试用例，包括单元测试、API 测试和 E2E 测试。
+为新开发的功能创建自动化测试用例，包括 UT、API 测试和 E2E 测试。
 
-> 存储路径和缓存同步规则见 [_storage.md](./_storage.md)
+> 测试文件位置、运行命令、代码示例从项目 `docs/prompt/testing.md` 和 CLAUDE.md「测试规范」读取。
 
 ## 命令格式
 
 ```
-/req:test_new [REQ-XXX] [--type=ut|api|e2e|all]
+/req:test_new [REQ-XXX] [--type=ut|api|e2e|all|manual] [--dry-run]
 ```
 
-### 参数
-
-| 参数 | 说明 | 示例 |
-|-----|------|------|
-| `REQ-XXX` | 需求编号（可选） | `/req:test_new REQ-001` |
-| `--type=ut` | 仅创建单元测试 | `/req:test_new --type=ut` |
-| `--type=api` | 仅创建 API 测试 | `/req:test_new --type=api` |
-| `--type=e2e` | 仅创建 E2E 测试 | `/req:test_new --type=e2e` |
-| `--type=all` | 创建所有类型测试 | `/req:test_new --type=all` |
-| `--type=manual` | 生成人工复测用例文档 | `/req:test_new --type=manual` |
-| `--dry-run` | 预览不实际创建 | `/req:test_new --dry-run` |
+| 参数 | 说明 |
+|------|------|
+| `--type=ut` | 仅单元测试 |
+| `--type=api` | 仅 API 测试 |
+| `--type=e2e` | 仅 E2E 测试 |
+| `--type=all` | 所有类型 |
+| `--type=manual` | 生成人工复测用例文档 |
+| `--dry-run` | 预览不实际创建 |
 
 ---
 
@@ -35,379 +30,64 @@ description: 创建测试 - 为新功能编写自动化测试用例或手动测
 
 ### 1. 选择需求
 
-- 指定编号 → 使用该需求
-- 未指定 → 查找「开发中」或「测试中」的需求
-- 多个候选 → 让用户选择
+指定编号 → 使用；未指定 → 查找「开发中/测试中」的需求，多个候选让用户选择。
 
 ### 2. 分析需求文档
 
-```
-分析需求文档...
-
-需求：REQ-001 <需求标题>
-状态：开发中
-
-功能清单：
-1. <功能点 1>
-2. <功能点 2>
-3. <功能点 3>
-
-涉及文件：
-<source-file-1>
-<source-file-2>
-<source-file-3>
-<source-file-N>
-
-识别测试点：
-
-
-类型     测试点                       数量     
-
-UT       业务层方法                    N        
-API      接口端点                     N        
-E2E      用户流程                     N        
-
-```
+提取功能清单、涉及文件，识别三类测试点（UT/API/E2E）及其数量。
 
 ### 3. 选择测试类型
 
-```
-请选择要创建的测试类型：
-
-[1] 单元测试 (UT)
-    - 测试业务层逻辑
-    - 使用 Mock 隔离依赖
-    - 预计生成 N 个测试用例
-
-[2] API 测试
-    - 测试接口端点
-    - 验证请求/响应/错误码
-    - 预计生成 N 个测试文件
-
-[3] E2E 测试
-    - 测试完整用户流程
-    - 端到端场景验证
-    - 预计生成 N 个测试文件
-
-[4] 全部自动化
-
-[5] 手动测试用例文档 (manual)
-    - 供测试人员逐条复测
-    - 覆盖后端接口 + 前端交互 + 业务规则
-    - 生成 docs/test-cases/REQ-XXX-testcases.md
-
-请输入选择 (1/2/3/4/5)：
-```
-
-### 4. 生成单元测试 (UT)
-
-#### 4.1 分析被测方法
-
-```
-分析业务层方法...
-
-<source-file>:
-<方法签名 1>
-<方法签名 2>
-<方法签名 3>
-<方法签名 N>
-```
-
-#### 4.2 生成测试用例
-
-根据 CLAUDE.md 中定义的测试框架和规范，生成对应的测试代码。
-
-测试用例遵循 **Arrange-Act-Assert** 模式：
+交互式选择或从 `--type` 参数确定。
 
-```
-生成文件：<CLAUDE.md中定义的测试文件路径>
-
-测试用例列表：
-<TestCase_Method1_Success>        - 正常流程
-<TestCase_Method1_ErrorCase>      - 异常场景
-<TestCase_Method2_ValidInput>     - 输入校验
-<TestCase_Method2_InvalidInput>   - 边界条件
-<TestCase_Method3_NormalCase>     - 正常流程
-<TestCase_Method3_EdgeCase>       - 边界条件
-
-每个测试用例结构：
-1. Arrange - 准备数据和 Mock 依赖
-2. Act - 执行被测方法
-3. Assert - 验证结果
-```
-
-#### 4.3 生成 Mock 文件（如需要）
-
-```
-按 CLAUDE.md 测试规范生成 Mock 文件...
+---
 
-<CLAUDE.md中定义的Mock生成命令>
+### 4. 生成 UT
 
-✅ 生成：<mock-file-path>
-```
+- **分析被测方法**：读取源文件，列出所有方法签名
+- **生成测试用例**：按项目测试框架规范（从 CLAUDE.md 读取），遵循 Arrange-Act-Assert 模式
+- **生成 Mock 文件**（如需要）：按项目 Mock 生成命令执行
 
 ### 5. 生成 API 测试
 
-#### 5.1 提取 API 定义
-
-```
-提取 API 定义...
-
-从需求文档提取：
-<HTTP_METHOD> <endpoint-1>    <描述>
-<HTTP_METHOD> <endpoint-2>    <描述>
-<HTTP_METHOD> <endpoint-3>    <描述>
-```
-
-#### 5.2 生成测试代码
-
-根据 CLAUDE.md 中定义的 API 测试框架生成测试代码。
-
-每个接口的测试覆盖：
-
-```
-生成文件：<CLAUDE.md中定义的API测试文件路径>
-
-<endpoint-1> 测试用例：
-正常请求 - 完整参数         → 期望成功响应
-正常请求 - 可选参数缺省      → 期望成功响应（默认值）
-异常请求 - 缺少必填字段      → 期望参数校验错误
-异常请求 - 业务规则冲突      → 期望业务错误码
-异常请求 - 无权限            → 期望权限错误
-
-采用表驱动测试模式，每组包含：
-- name: 场景描述
-- input: 请求参数
-- wantStatus: 期望状态码
-- wantBody: 期望响应内容（可选）
-```
+- **提取 API 定义**：从需求文档获取接口端点
+- **生成测试代码**：覆盖正常请求（完整/缺省参数）、异常请求（缺少必填字段、业务规则冲突、无权限）
 
 ### 6. 生成 E2E 测试
 
-**前提条件**：E2E 测试需要完整的测试环境
-
-```
-⚠️ E2E 测试需要启动测试环境：
-- 依赖服务（数据库、缓存等）
-- 后端服务（本地）
-- 前端服务（本地）
-```
-
-#### 6.1 识别用户流程
-
-```
-识别用户流程...
-
-核心流程：<功能名称>
-1. <用户操作步骤 1>
-2. <用户操作步骤 2>
-3. <用户操作步骤 3>
-4. <验证步骤>
-```
-
-#### 6.2 生成测试代码
-
-根据 CLAUDE.md 中定义的 E2E 测试框架生成测试代码。
-
-```
-生成文件：<CLAUDE.md中定义的E2E测试文件路径>
-
-测试场景：
-<场景 1>: <用户流程描述>
-  前置：<数据准备 / 登录>
-  操作：<页面交互步骤>
-  断言：<预期结果>
-<场景 2>: <边界条件描述>
-  前置：<特定状态准备>
-  操作：<触发边界条件>
-  断言：<预期错误提示>
-<场景 3>: <修改流程描述>
-    前置：<已有数据>
-    操作：<修改操作>
-    断言：<修改后状态>
-```
+- **前提**：需要完整测试环境
+- **识别用户流程**：从需求文档提取核心用户操作流程
+- **生成测试代码**：覆盖正常流程、边界条件、修改流程，含前置数据准备和断言
 
 ### 7. 生成手动测试用例文档 (manual)
 
-> 适用场景：需要给测试人员一份可逐条执行的复测清单，前后端项目均适用。
-
-#### 7.1 分析信息源
-
-同时读取两处：
-
-```
-读取需求文档...
-功能清单（待验证的功能点）
-业务规则（边界条件、约束）
-使用场景（正常流程 + 异常流程）
-测试要点（已有的验收标准）
-
-读取源代码...
-后端：handler/controller → 提取接口路径、参数、返回码
-后端：service/logic     → 提取分支逻辑、边界判断
-前端：页面/组件          → 提取交互逻辑、表单校验、跳转规则
-```
-
-源码补充需求文档未覆盖的细节（如实际返回的错误码、字段校验规则）。
-
-#### 7.2 生成用例
+同时读取需求文档 + 源代码，按模块分组生成表格化用例：
 
-按模块分组，每条用例包含：编号、场景、前置条件、操作步骤、预期结果、实际结果（空）、通过（空）。
+- **后端接口**：每个接口覆盖正常路径、参数缺失/非法、业务规则冲突、权限不足
+- **前端交互**：覆盖正常操作、表单校验、异常提示、边界状态
+- **业务规则**：每条规则至少一条用例
 
-**后端接口** — 每个接口至少覆盖：正常路径、参数缺失/非法、业务规则冲突、权限不足。
+输出到 `docs/test-cases/REQ-XXX-testcases.md`，包含编号、场景、前置条件、操作步骤、预期结果、实际结果、通过列。
 
-**前端交互** — 每个页面/功能至少覆盖：正常操作流程、表单校验、异常提示、边界状态（空数据、超长文本、加载失败等）。
-
-**业务规则** — 需求文档中的每条业务规则对应至少一条用例。
-
-输出格式：
-
-````
-生成手动测试用例...
-
-生成文件：docs/test-cases/REQ-XXX-testcases.md
-
-# REQ-XXX <需求标题> · 手动测试用例
-
-> 需求：[REQ-XXX](../../requirements/active/REQ-XXX-xxx.md)
-> 生成日期：YYYY-MM-DD
-> 状态：待测试
+更新需求文档第六章追加用例文件引用。
 
 ---
 
-## 后端接口
-
-| 编号 | 场景 | 前置条件 | 操作步骤 | 预期结果 | 实际结果 | 通过 |
-|-----|------|---------|---------|---------|---------|-----|
-| TC-001 | <接口名>-正常 | <前置数据/权限> | `<HTTP_METHOD> <path>`<br>参数：`{...}` | HTTP <状态码>，返回 `{...}` | | |
-| TC-002 | <接口名>-缺少必填字段 | - | 省略字段 `<field>` | HTTP 400，`message` 含"<字段名>不能为空" | | |
-| TC-003 | <接口名>-无权限 | 未登录 / 低权限账号 | 发起请求 | HTTP 401 / 403 | | |
-| TC-004 | <接口名>-业务规则冲突 | <冲突前置条件> | <触发冲突的参数> | HTTP 4XX，业务错误码 `<code>` | | |
-
----
-
-## 前端交互
-
-| 编号 | 页面/功能 | 场景 | 前置条件 | 操作步骤 | 预期结果 | 实际结果 | 通过 |
-|-----|---------|------|---------|---------|---------|---------|-----|
-| TC-101 | <页面名> | 正常流程 | <登录状态/数据> | 1. <操作1><br>2. <操作2><br>3. <操作3> | <可观测的页面状态> | | |
-| TC-102 | <页面名> | 表单校验-<字段> | - | 1. 不填 `<字段>`<br>2. 点击提交 | 字段下方显示"<校验提示>" | | |
-| TC-103 | <页面名> | 空数据状态 | 无相关数据 | 进入页面 | 显示空状态占位 | | |
-| TC-104 | <页面名> | 操作成功反馈 | <正常前置> | <完成操作> | 显示成功提示，数据刷新 | | |
-
----
-
-## 业务规则验证
-
-| 编号 | 规则 | 场景 | 操作 | 预期结果 | 实际结果 | 通过 |
-|-----|------|------|------|---------|---------|-----|
-| TC-201 | <业务规则描述> | <触发场景> | <操作步骤> | <预期约束生效表现> | | |
-
----
-
-## 测试执行记录
-
-- **执行人**：
-- **执行日期**：
-- **测试环境**：
-- **总计**：N 条，通过 0 条，失败 0 条，跳过 0 条
-````
-
-#### 7.3 更新需求文档
-
-在需求文档「六、测试要点」末尾追加引用行：
+### 8. 汇总 & 运行验证
 
-```markdown
-手动测试用例：[docs/test-cases/REQ-XXX-testcases.md](../../../test-cases/REQ-XXX-testcases.md)（生成于 YYYY-MM-DD）
-```
+生成文件汇总表（类型、文件、用例数）。运行新创建的测试验证通过率。
 
 ---
 
-### 8. 测试文件汇总
-
-```
-测试文件生成完成
-
-
-类型     文件                                                用例数   
-
-UT       <ut-test-file>                                     N        
-API      <api-test-file>                                    N        
-E2E      <e2e-test-file>                                    N        
-手动用例  docs/test-cases/REQ-XXX-testcases.md              N        
-
-合计     N 个文件                                            N        
-
-
-✅ 已生成 Mock 文件（如需要）
-✅ 已添加测试数据 fixtures（如需要）
-```
-
-### 9. 运行验证
-
-```
-运行新创建的测试...
-
-<CLAUDE.md中定义的UT运行命令> <ut-test-file>
-<TestCase_1>    --- PASS
-<TestCase_2>    --- PASS
-...
-
-<CLAUDE.md中定义的API测试运行命令> <api-test-file>
-<TestCase_API_1>    --- PASS
-<TestCase_API_2>    --- PASS
-...
+### 9. 更新需求文档
 
-验证结果：N/N 通过
-
-下一步：
-- 运行全量回归：/req:test_regression
-- 继续开发：/req:dev
-- 完成需求：/req:done
-```
-
-### 10. 更新需求文档
-
-自动更新需求文档的测试覆盖章节：
-
-```markdown
-## 测试覆盖
-
-| 类型 | 文件 | 用例数 | 覆盖率 |
-|-----|------|-------|-------|
-| UT | <ut-test-file> | N | XX% |
-| API | <api-test-file> | N | XX% |
-| E2E | <e2e-test-file> | N | - |
-
-创建时间：<date>
-最后运行：<date> ✅ 全部通过
-```
+在需求文档追加测试覆盖章节（类型、文件、用例数、覆盖率、创建时间）。
 
 ---
 
-## 测试模板
-
-测试模板从项目 CLAUDE.md 的「测试规范」章节读取，包括：
-
-### UT 模板
-
-- 测试框架、断言库、Mock 工具由 CLAUDE.md 定义
-- 遵循 Arrange-Act-Assert 模式
-- 命名规范：`Test{被测对象}_{方法}_{场景}`
-
-### API 测试模板
-
-- 测试框架由 CLAUDE.md 定义
-- 采用表驱动测试模式
-- 覆盖正常路径、异常路径、权限校验
-- 命名规范：`Test{Endpoint}_{场景}`
-
-### E2E 测试模板
+## 测试规范来源
 
-- E2E 框架由 CLAUDE.md 定义
-- 包含前置数据准备（如登录、数据重置）
-- 模拟真实用户操作流程
-- 验证页面状态和交互结果
+测试框架、断言库、Mock 工具、命名规范、文件路径等均从项目 CLAUDE.md「测试规范」读取，不内置任何项目细节。
 
 ---
 

package/plugins/req/skills/test_regression/SKILL.md

@@ -9,7 +9,7 @@ description: 回归测试 - 运行已有自动化测试用例
 
 运行项目中已存在的自动化测试用例，验证功能正确性。
 
-> 存储路径和缓存同步规则见 [_storage.md](./_storage.md)
+> 存储路径和缓存同步规则见 `_storage.md`
 
 ## 命令格式
 

package/plugins/req/skills/update-template/SKILL.md

@@ -7,7 +7,7 @@ description: 更新模板 - 将插件最新模板同步到项目本地
 
 将插件 `templates/` 目录下的最新模板同步到项目本地 `docs/requirements/`，覆盖旧版本。
 
-> 存储路径规则见 [_storage.md](./_storage.md)
+> 存储路径规则见 `_storage.md`
 
 ## 命令格式
 

package/plugins/req/skills/use/SKILL.md

@@ -48,7 +48,7 @@ description: 切换需求项目 - 将当前仓库绑定到不同的项目
 
 ### 4. 更新仓库绑定
 
-> 写入规范见 [_storage.md](./_storage.md#settings-文件写入规范)。
+> 写入规范见 `_storage.md`。
 
 读取已有 `.claude/settings.json`，合并以下字段后写回（不覆盖已有的 `branchStrategy` 等字段）：
 

package/plugins/req/templates/claude-md-snippets/frontend-react.md

@@ -0,0 +1,48 @@
+# 前端项目架构（CLAUDE.md 建议片段）
+
+> 请将以下内容追加到项目的 CLAUDE.md 中，并根据实际情况调整。
+
+## 项目架构
+
+### 技术栈
+
+- 框架：React 18+ / Next.js 16（根据实际选择）
+- 语言：TypeScript
+- 状态管理：Zustand / Redux Toolkit
+- UI 组件：Ant Design / shadcn/ui
+- 样式：Tailwind CSS / CSS Modules
+- 构建：Vite / Turbopack
+- 测试：Vitest + React Testing Library + Playwright
+
+### 目录结构
+
+| 目录 | 职责 | 说明 |
+|------|------|------|
+| `src/components/` | UI 组件 | 通用组件、业务组件 |
+| `src/pages/` 或 `app/` | 页面/路由 | 文件系统路由或手动路由 |
+| `src/hooks/` | 自定义 Hooks | 复用逻辑抽取 |
+| `src/services/` 或 `src/api/` | API 调用 | 接口封装、类型定义 |
+| `src/stores/` | 状态管理 | 全局状态 |
+| `src/types/` | 类型定义 | 共享 TypeScript 类型 |
+| `src/utils/` | 工具函数 | 通用工具 |
+
+### 文件命名
+
+- 组件文件：PascalCase（如 `UserProfile.tsx`）
+- 工具/hooks：camelCase（如 `useAuth.ts`）
+- 样式文件：与组件同名（如 `UserProfile.module.css`）
+
+### 开发规范
+
+- 组件：函数组件 + Hooks，避免 class 组件
+- 类型：所有 props 和 API 响应定义 TypeScript 接口
+- API 调用：统一封装 fetch/axios，集中管理接口地址
+- 错误处理：ErrorBoundary + Toast 提示
+- 国际化：i18next（如需）
+
+### 测试规范
+
+- 组件测试：`*.test.tsx`，React Testing Library
+- 工具函数测试：`*.test.ts`，Vitest
+- E2E 测试：`tests/e2e/`，Playwright
+- 运行命令：`npm test` / `npx vitest` / `npx playwright test`

package/plugins/req/templates/claude-md-snippets/generic.md

@@ -0,0 +1,43 @@
+# 项目架构（CLAUDE.md 建议片段）
+
+> 请将以下内容追加到项目的 CLAUDE.md 中，并根据实际情况填写。
+> 此信息供 AI 辅助开发时理解项目结构，是需求开发引导和测试引导的基础。
+
+## 项目架构
+
+### 技术栈
+
+- 语言：<!-- 如 Go / Java / TypeScript / Python -->
+- 框架：<!-- 如 Gin / Spring Boot / Next.js / FastAPI -->
+- ORM/数据库：<!-- 如 GORM+MySQL / JPA+PostgreSQL / Prisma+PostgreSQL -->
+- 测试框架：<!-- 如 go test / JUnit / Vitest / pytest -->
+
+### 分层架构
+
+<!-- 按开发顺序列出项目的分层，AI 会按此顺序引导开发 -->
+
+| 层 | 职责 | 目录 | 说明 |
+|----|------|------|------|
+| <!-- 数据层 --> | <!-- 数据模型定义 --> | <!-- 目录路径 --> | <!-- 补充说明 --> |
+| <!-- 数据访问层 --> | <!-- CRUD 操作 --> | <!-- 目录路径 --> | |
+| <!-- 业务层 --> | <!-- 业务逻辑 --> | <!-- 目录路径 --> | |
+| <!-- 接口层 --> | <!-- 请求处理 --> | <!-- 目录路径 --> | |
+| <!-- 路由层 --> | <!-- 路由注册 --> | <!-- 目录路径 --> | |
+
+### 文件命名
+
+- <!-- 如：Go 文件 kebab-case，Java 文件 PascalCase，组件 PascalCase.tsx -->
+
+### 开发规范
+
+- 错误处理：<!-- 如何处理错误 -->
+- 日志：<!-- 日志格式和方法 -->
+- API 风格：<!-- RESTful / GraphQL -->
+- <!-- 其他项目特有规范 -->
+
+### 测试规范
+
+- UT 位置：<!-- 测试文件目录和命名规则 -->
+- 集成/API 测试：<!-- 位置和工具 -->
+- E2E 测试：<!-- 位置和工具 -->
+- 运行命令：<!-- 如 go test ./... / npm test -->

package/plugins/req/templates/claude-md-snippets/go-backend.md

@@ -0,0 +1,47 @@
+# Go 后端项目架构（CLAUDE.md 建议片段）
+
+> 请将以下内容追加到项目的 CLAUDE.md 中，并根据实际情况调整。
+
+## 项目架构
+
+### 技术栈
+
+- 语言：Go 1.22+
+- Web 框架：Gin
+- ORM：GORM
+- 数据库：MySQL 8.0, Redis 7
+- API 风格：RESTful + Swagger 注解
+- 测试：go test + gomock
+
+### 分层架构
+
+按以下顺序开发，每层职责明确：
+
+| 层 | 职责 | 目录 | 说明 |
+|----|------|------|------|
+| Model | 数据模型定义 | `internal/model/` | 结构体、表名、字段标签 |
+| Store | 数据访问 | `internal/store/` | CRUD 操作，SQL 查询 |
+| Biz | 业务逻辑 | `internal/biz/` | 校验、组合、事务 |
+| Controller | 接口处理 | `internal/controller/v1/` | 参数绑定、响应封装 |
+| Router | 路由注册 | `internal/router/` | 路由分组、中间件 |
+
+### 文件命名
+
+- Go 文件：kebab-case（如 `sys-dept-channel.go`）
+- 测试文件：与源文件同目录 `*_test.go`
+
+### 开发规范
+
+- 错误处理：`errno.ErrXxx` 错误码，非裸 error
+- 日志：`log.Info/Error(msg, ctx, k, v...)` 结构化日志，非 `fmt.Println`
+- 多租户：所有业务表包含 `TenantID` 字段
+- 权限标识：`module:resource:action` 格式
+- Controller：Swagger 注解（Summary、Param、Success、Failure），`ShouldBindJSON`/`ShouldBindQuery` 参数绑定，`response.Success(c, data)`/`response.Error(c, err)` 响应
+
+### 测试规范
+
+- UT：与源文件同目录 `*_test.go`，gomock 模拟依赖
+- API 测试：`tests/api/` 目录
+- E2E 测试：`tests/e2e/`（如有前端）
+- 测试环境：`docker-compose.test.yml`（MySQL + Redis 容器）
+- 运行命令：`go test ./...`

package/plugins/req/templates/claude-md-snippets/java-backend.md

@@ -0,0 +1,46 @@
+# Java 后端项目架构（CLAUDE.md 建议片段）
+
+> 请将以下内容追加到项目的 CLAUDE.md 中，并根据实际情况调整。
+
+## 项目架构
+
+### 技术栈
+
+- 语言：Java 17+
+- 框架：Spring Boot 3.x
+- ORM：MyBatis-Plus / JPA
+- 数据库：MySQL 8.0, Redis 7
+- API 风格：RESTful
+- 构建：Maven / Gradle
+- 测试：JUnit 5 + Mockito
+
+### 分层架构
+
+按以下顺序开发，每层职责明确：
+
+| 层 | 职责 | 目录 | 说明 |
+|----|------|------|------|
+| Entity | 数据模型 | `src/main/java/.../entity/` | 实体类、表映射 |
+| Mapper/Repository | 数据访问 | `src/main/java/.../mapper/` | SQL 映射、CRUD |
+| Service | 业务逻辑 | `src/main/java/.../service/` | 接口 + Impl 实现 |
+| Controller | 接口处理 | `src/main/java/.../controller/` | 参数校验、响应封装 |
+
+### 文件命名
+
+- Java 文件：PascalCase（如 `SysDeptChannel.java`）
+- 包名：小写（如 `com.example.system`）
+
+### 开发规范
+
+- 异常处理：自定义 BusinessException + 全局异常处理器
+- 日志：`@Slf4j` + `log.info/error` 结构化日志
+- 参数校验：`@Valid` + `@NotNull`/`@Size` 注解
+- API 文档：SpringDoc / Swagger 注解
+- 事务：`@Transactional` 注解
+
+### 测试规范
+
+- UT：`src/test/java/` 对应目录，Mockito 模拟依赖
+- 集成测试：`@SpringBootTest` + `@TestContainers`
+- API 测试：`MockMvc` 或 `RestAssured`
+- 运行命令：`mvn test` / `gradle test`