leniu-dev 2.0.0

package/.claude/skills/api-development/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: api-development
+description: |
+  后端 API 接口设计规范。基于 Spring Boot 的 RESTful API 开发指南。
+
+  触发场景：
+  - 设计 RESTful API 接口
+  - 编写 Controller 层代码
+  - 配置接口权限、日志注解
+  - 接口返回值类型选择
+  - 数据验证和参数校验
+
+  触发词：API、接口、RESTful、Controller、GetMapping、PostMapping、权限注解、日志注解、分页查询、接口规范
+
+  注意：
+  - 参考项目实际架构层次选择合适的分层模式
+---
+
+# API 接口设计规范
+
+## 核心规范
+
+| 原则 | 说明 |
+|------|------|
+| RESTful 风格 | 使用标准 HTTP 方法表达语义 |
+| 认证保护 | 所有业务接口必须添加认证注解 |
+| 参数校验 | 使用分组校验区分新增/修改场景 |
+| 统一响应 | 使用统一的响应格式包装返回数据 |
+
+### HTTP 方法规范
+
+| 操作 | 方法 | 路径示例 |
+|------|------|---------|
+| 列表查询 | GET | `/list` 或 `/page` |
+| 获取详情 | GET | `/{id}` |
+| 新增 | POST | `/` 或 `/add` |
+| 修改 | PUT | `/` 或 `/update` |
+| 删除 | DELETE | `/{ids}` |
+| 导出 | POST | `/export` |
+| 导入 | POST | `/import` |
+
+---
+
+## Controller 标准模板
+
+```java
+@Slf4j
+@RestController
+@RequiredArgsConstructor
+@RequestMapping("/api/v1/[模块]/[功能]")
+public class XxxController {
+
+    private final XxxService xxxService;
+
+    /**
+     * 分页查询
+     */
+    @GetMapping("/page")
+    public Result<PageResult<XxxVO>> page(XxxQueryDTO query) {
+        return Result.ok(xxxService.pageList(query));
+    }
+
+    /**
+     * 获取详情
+     */
+    @GetMapping("/{id}")
+    public Result<XxxVO> getById(@PathVariable Long id) {
+        return Result.ok(xxxService.getById(id));
+    }
+
+    /**
+     * 新增
+     */
+    @PostMapping
+    public Result<Long> add(@Validated(InsertGroup.class) @RequestBody XxxDTO dto) {
+        return Result.ok(xxxService.add(dto));
+    }
+
+    /**
+     * 修改
+     */
+    @PutMapping
+    public Result<Void> update(@Validated(UpdateGroup.class) @RequestBody XxxDTO dto) {
+        xxxService.update(dto);
+        return Result.ok();
+    }
+
+    /**
+     * 删除
+     */
+    @DeleteMapping("/{ids}")
+    public Result<Void> delete(@PathVariable List<Long> ids) {
+        xxxService.deleteByIds(ids);
+        return Result.ok();
+    }
+}
+```
+
+---
+
+## 统一响应封装
+
+### Result 包装类（通用模式）
+
+```java
+@Data
+public class Result<T> {
+    private int code;
+    private String message;
+    private T data;
+
+    public static <T> Result<T> ok() {
+        return ok(null);
+    }
+
+    public static <T> Result<T> ok(T data) {
+        Result<T> result = new Result<>();
+        result.setCode(200);
+        result.setMessage("success");
+        result.setData(data);
+        return result;
+    }
+
+    public static <T> Result<T> fail(String message) {
+        Result<T> result = new Result<>();
+        result.setCode(500);
+        result.setMessage(message);
+        return result;
+    }
+}
+```
+
+### 分页响应
+
+```java
+@Data
+public class PageResult<T> {
+    private List<T> records;
+    private long total;
+    private long current;
+    private long size;
+}
+```
+
+---
+
+## 参数校验
+
+### 分组校验
+
+```java
+// DTO 中使用分组
+@Data
+public class XxxDTO {
+    @NotNull(message = "ID不能为空", groups = {UpdateGroup.class})
+    private Long id;
+
+    @NotBlank(message = "名称不能为空", groups = {InsertGroup.class, UpdateGroup.class})
+    @Size(max = 100, message = "名称长度不能超过100个字符")
+    private String name;
+
+    @Min(value = 0, message = "排序不能为负数")
+    private Integer sort;
+}
+
+// Controller 中应用
+@PostMapping
+public Result<Long> add(@Validated(InsertGroup.class) @RequestBody XxxDTO dto) { ... }
+
+@PutMapping
+public Result<Void> update(@Validated(UpdateGroup.class) @RequestBody XxxDTO dto) { ... }
+```
+
+> Jakarta Validation: JDK 17+ 必须 `import jakarta.validation.constraints.*`
+
+### 查询参数
+
+```java
+@Data
+public class XxxQueryDTO {
+    private String keyword;
+    private Integer status;
+
+    @Min(value = 1)
+    private Integer pageNum = 1;
+
+    @Min(value = 1) @Max(value = 100)
+    private Integer pageSize = 10;
+}
+```
+
+---
+
+## 常见场景
+
+### 带分布式锁的导入
+
+```java
+@PostMapping("/import")
+public Result<Void> importExcel(@RequestPart("file") MultipartFile file) {
+    if (file == null || file.isEmpty()) {
+        throw new [你的异常类]("文件不能为空");
+    }
+    RLock lock = redissonClient.getLock("import:lock:" + getCurrentTenantId());
+    try {
+        if (!lock.tryLock(5, 60, TimeUnit.SECONDS)) {
+            throw new [你的异常类]("正在处理中，请稍后再试");
+        }
+        try {
+            xxxService.importExcel(file);
+        } finally {
+            if (lock.isLocked() && lock.isHeldByCurrentThread()) {
+                lock.unlock();
+            }
+        }
+    } catch (InterruptedException e) {
+        Thread.currentThread().interrupt();
+        throw new [你的异常类]("导入被中断");
+    }
+    return Result.ok();
+}
+```
+
+### 批量删除
+
+```java
+@DeleteMapping("/{ids}")
+public Result<Void> delete(@PathVariable List<Long> ids) {
+    if (ids == null || ids.isEmpty()) {
+        throw new [你的异常类]("ID列表不能为空");
+    }
+    xxxService.deleteByIds(ids);
+    return Result.ok();
+}
+```
+
+### 文件上传
+
+```java
+@PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+public Result<UploadResult> upload(@RequestPart("file") MultipartFile file) {
+    return Result.ok(ossService.upload(file));
+}
+```
+
+---
+
+## API 文档注解
+
+### Swagger / SpringDoc 注解
+
+```java
+// SpringDoc (OpenAPI 3.0, 推荐)
+@Tag(name = "用户管理")                              // Controller 类
+@Operation(summary = "新增用户")                      // 方法
+@Schema(description = "用户DTO")                      // DTO/VO 类
+@Schema(description = "主键ID", requiredMode = REQUIRED) // 字段
+
+// Swagger 2 (旧项目)
+@Api(value = "用户管理", tags = "用户管理")
+@ApiOperation(value = "新增用户")
+@ApiModel("用户DTO")
+@ApiModelProperty(value = "主键ID", required = true)
+```
+
+---
+
+## 全局异常处理
+
+```java
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    @ExceptionHandler([你的异常类].class)
+    public Result<Void> handleBusinessException([你的异常类] e) {
+        return Result.fail(e.getMessage());
+    }
+
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public Result<Void> handleValidException(MethodArgumentNotValidException e) {
+        String message = e.getBindingResult().getFieldErrors().stream()
+            .map(FieldError::getDefaultMessage)
+            .collect(Collectors.joining(", "));
+        return Result.fail(message);
+    }
+
+    @ExceptionHandler(Exception.class)
+    public Result<Void> handleException(Exception e) {
+        log.error("系统异常", e);
+        return Result.fail("系统繁忙，请稍后再试");
+    }
+}
+```
+
+---
+
+## 检查清单
+
+- [ ] 认证注解（`@PreAuthorize` / `[你的认证注解]`）
+- [ ] API 文档注解（`@Operation` / `@ApiOperation`）
+- [ ] 参数校验 `@Validated` + 分组
+- [ ] 统一响应包装 `Result<T>`
+- [ ] 敏感操作加分布式锁
+- [ ] 全局异常处理器已配置
+
+---
+
+## 相关技能
+
+| 需要了解 | Skill |
+|---------|-------|
+| 异常处理 | `error-handler` |
+| 数据库设计 | `database-ops` |
+| 缓存 | `redis-cache` |
+| 文件上传 | `file-oss-management` |

package/.claude/skills/architecture-design/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: architecture-design
+description: |
+  通用架构设计指南。涵盖分层架构、模块划分、依赖管理等架构决策方法论。
+  触发场景：系统设计、模块拆分、架构评审、技术选型。
+  触发词：架构设计、分层架构、模块划分、系统设计、技术选型。
+  注意：如果项目有专属技能（如 `leniu-architecture`），优先使用专属版本。
+---
+
+# 架构设计指南
+
+> 通用模板。如果项目有专属技能（如 `leniu-architecture`），优先使用。
+
+## 核心规范
+
+### 分层架构对比
+
+#### 三层架构（标准 Spring Boot）
+
+```
+Controller  ->  Service  ->  Mapper/Repository
+（接口层）     （业务层）    （数据访问层）
+```
+
+- **适用场景**：中小型项目、业务逻辑相对简单
+- **优点**：结构清晰、上手快、团队共识强
+- **缺点**：Service 层容易膨胀为"上帝类"
+
+#### 四层架构（增加编排层）
+
+```
+Controller  ->  Business/Facade  ->  Service  ->  Mapper/Repository
+（接口层）      （业务编排层）       （领域服务）   （数据访问层）
+```
+
+- **适用场景**：大型项目、复杂业务编排、跨 Service 协调
+- **优点**：职责更细粒度、Service 保持纯净
+- **缺点**：层次多、小项目过度设计
+
+#### 选择建议
+
+| 条件 | 推荐 |
+|------|------|
+| 单表 CRUD 为主 | 三层架构 |
+| 跨模块协调频繁 | 四层架构 |
+| 团队 < 5 人 | 三层架构 |
+| 微服务拆分 | 三层 + DDD |
+
+### 模块划分原则
+
+1. **高内聚低耦合**：模块内部紧密关联，模块间依赖最小化
+2. **按业务域拆分**：而非按技术层拆分
+3. **单一职责**：每个模块只负责一个业务领域
+4. **接口隔离**：模块间通过接口/API 通信，不直接依赖实现
+
+### 推荐模块结构
+
+```
+project-root/
+├── project-common/          # 公共模块（工具类、通用常量）
+├── project-api/             # 对外 API 定义（Feign 接口、DTO）
+├── project-module-order/    # 订单模块
+├── project-module-user/     # 用户模块
+├── project-module-payment/  # 支付模块
+└── project-gateway/         # 网关（微服务场景）
+```
+
+### 每个模块内部结构
+
+```
+[你的包名].[module]/
+├── controller/       # 接口层
+├── service/
+│   └── impl/         # 业务实现
+├── mapper/           # 数据访问
+├── entity/           # 实体
+├── dto/              # 请求参数
+├── vo/               # 响应对象
+├── enums/            # 枚举
+└── config/           # 模块配置
+```
+
+## 代码示例
+
+### 依赖方向（必须单向）
+
+```
+Controller  -->  Service  -->  Mapper
+    |               |
+    v               v
+   DTO/VO        Entity
+```
+
+- 上层可以依赖下层，下层不能依赖上层
+- 同层之间避免循环依赖
+- 公共模块被所有业务模块依赖，但公共模块不依赖任何业务模块
+
+### 模块间通信模式
+
+```java
+// 方式一：直接依赖（单体应用）
+@Service
+@RequiredArgsConstructor
+public class OrderServiceImpl implements IOrderService {
+    private final IUserService userService;  // 直接注入其他模块 Service
+}
+
+// 方式二：事件驱动（解耦）
+@Service
+@RequiredArgsConstructor
+public class OrderServiceImpl implements IOrderService {
+    private final ApplicationEventPublisher eventPublisher;
+
+    public void createOrder(OrderCreateDTO dto) {
+        // ... 创建订单
+        eventPublisher.publishEvent(new OrderCreatedEvent(order));
+    }
+}
+
+// 方式三：Feign 调用（微服务）
+@FeignClient(name = "user-service")
+public interface UserFeignClient {
+    @GetMapping("/api/v1/users/{id}")
+    UserVO getUserById(@PathVariable Long id);
+}
+```
+
+### 配置分层
+
+```yaml
+# application.yml - 通用配置
+spring:
+  profiles:
+    active: ${SPRING_PROFILES_ACTIVE:dev}
+
+# application-dev.yml - 开发环境
+# application-test.yml - 测试环境
+# application-prod.yml - 生产环境
+```
+
+## 常见错误
+
+| 错误 | 正确做法 |
+|------|---------|
+| Controller 直接调 Mapper | 必须经过 Service 层 |
+| Service 之间循环依赖 | 提取公共 Service 或事件驱动 |
+| Entity 直接暴露给前端 | 用 VO 封装响应 |
+| 公共模块依赖业务模块 | 公共模块必须独立，被业务模块依赖 |
+| 按技术层拆分模块（all-controller、all-service） | 按业务域拆分 |
+| 所有逻辑堆在 Service 一个方法里 | 拆分私有方法或引入编排层 |
+| 硬编码配置值 | 使用配置文件 + `@Value` 或 `@ConfigurationProperties` |
+| 跨模块直接操作其他模块的数据库表 | 通过对方 Service 接口调用 |