From d086ca9f39f757b53ff75fcf7783e4092bf7b902 Mon Sep 17 00:00:00 2001
From: Leo <98382335+gaoziman@users.noreply.github.com>
Date: Sat, 27 Sep 2025 14:22:20 +0800
Subject: [PATCH] =?UTF-8?q?docs(claude):=20=E6=9B=B4=E6=96=B0=E5=BC=80?=
 =?UTF-8?q?=E5=8F=91=E8=A7=84=E8=8C=83=E5=92=8C=E9=98=B2=E9=94=99=E6=9C=BA?=
 =?UTF-8?q?=E5=88=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 添加Controller Swagger注解强制要求规范
- 添加依赖配置验证标准和检查原则
- 完善API文档中文化要求和实现方法
- 增强权限验证和模块依赖管理指导
- 新增定时任务开发和集成说明
---
 CLAUDE.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 54 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index e7fbb8a..3644a05 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -206,6 +206,44 @@ mvn test -pl coder-common-thin-web
       - 严禁在Sa-Token配置中添加业务接口的排除路径
       - 严禁通过其他方式绕过权限验证
 
+5. **Controller接口文档规范**: 所有Controller必须配置Swagger注解以生成规范的中文接口文档
+   - **强制要求**: 每个Controller类和方法都必须添加完整的Swagger注解
+   - **类级别注解**: 必须添加`@Tag(name = "中文模块名", description = "详细描述")`
+   - **方法级别注解**: 必须添加`@Operation(summary = "中文接口名", description = "详细功能描述")`
+   - **必要导入**: 在Controller类中导入：
+     ```java
+     import io.swagger.v3.oas.annotations.Operation;
+     import io.swagger.v3.oas.annotations.tags.Tag;
+     ```
+   - **依赖配置**: 使用Swagger注解的模块必须在pom.xml中添加SpringDoc依赖：
+     ```xml
+     <!-- SpringDoc OpenAPI 3.0 -->
+     <dependency>
+         <groupId>org.springdoc</groupId>
+         <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+     </dependency>
+     ```
+   - **标准示例**:
+     ```java
+     @Tag(name = "定时任务管理", description = "系统定时任务的增删改查和执行控制")
+     @RestController
+     @RequestMapping("/coder")
+     public class SysJobController {
+         
+         @Operation(summary = "分页查询定时任务", description = "根据查询条件分页获取系统定时任务列表")
+         @SaCheckPermission("monitor:job:list")
+         @GetMapping("/sysJob/listPage")
+         public IPage<SysJob> listPage(SysJobVo vo) {
+             // 业务逻辑
+         }
+     }
+     ```
+   - **接口文档效果**: 正确配置后，接口文档将显示中文模块名和接口名，而不是英文类名和方法名
+   - **禁止行为**:
+      - 严禁创建没有Swagger注解的Controller
+      - 严禁使用英文summary和description
+      - 严禁在缺少SpringDoc依赖的模块中使用Swagger注解
+
 ### 工具类使用
 项目提供了丰富的工具类，位于`coder-common-thin-common/utils`：
 - **缓存工具**: `RedisUtil`, `LocalCacheUtil`
@@ -264,4 +302,19 @@ mvn test -pl coder-common-thin-web
 6. **禁止自动编译**: Claude在完成新功能代码或修改代码后，严禁自动执行任何编译操作（如mvn compile、mvn package等）
    - **禁止行为**: 严禁在代码修改完成后自动运行编译命令
    - **原因说明**: 编译操作应由开发者根据实际需要手动执行，避免不必要的编译开销和潜在的环境冲突
-   - **允许行为**: 仅在用户明确要求时才执行编译操作
\ No newline at end of file
+   - **允许行为**: 仅在用户明确要求时才执行编译操作
+
+7. **Swagger注解强制要求**: 所有Controller必须配置完整的Swagger注解，确保接口文档显示中文
+   - **强制配置**: 新建Controller时必须同时添加`@Tag`和`@Operation`注解
+   - **依赖检查**: 使用Swagger注解前必须确保模块pom.xml包含SpringDoc依赖
+   - **中文规范**: 所有summary和description必须使用中文描述
+   - **编译验证**: 添加Swagger注解后必须确保项目能正常编译，如遇到"Cannot resolve symbol"错误，立即检查依赖配置
+   - **示例配置**:
+     ```xml
+     <!-- 在模块pom.xml中添加 -->
+     <dependency>
+         <groupId>org.springdoc</groupId>
+         <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
+     </dependency>
+     ```
+   - **验证标准**: 接口文档中必须显示中文模块名和接口名，而非英文类名和方法名
\ No newline at end of file