leniu-dev 2.0.0

package/.cursor/skills/error-handler/SKILL.md

@@ -0,0 +1,310 @@
+---
+name: error-handler
+description: |
+  通用异常处理指南。涵盖自定义业务异常、全局异常处理器、参数校验等。
+  触发场景：异常设计、错误处理、参数校验、全局异常捕获。
+  触发词：异常处理、错误处理、参数校验、validation、异常捕获。
+  注意：如果项目有专属技能（如 `leniu-error-handler`），优先使用专属版本。
+---
+
+# 异常处理指南
+
+> 通用模板。如果项目有专属技能（如 `leniu-error-handler`），优先使用。
+
+## 核心规范
+
+### 异常分层设计
+
+```
+RuntimeException
+└── BusinessException          # 业务异常基类
+    ├── NotFoundException      # 资源不存在 (404)
+    ├── ForbiddenException     # 无权限 (403)
+    ├── BadRequestException    # 参数错误 (400)
+    └── ConflictException      # 数据冲突 (409)
+```
+
+### 异常处理原则
+
+1. **业务异常用自定义异常类**，不要直接抛 `RuntimeException`
+2. **全局统一捕获**，通过 `@RestControllerAdvice` 处理
+3. **区分异常层级**：Controller 层不 try-catch（交给全局处理器），Service 层只捕获需要转换的异常
+4. **异常信息面向用户**：不暴露堆栈、SQL 等技术细节
+5. **日志记录完整**：异常日志包含完整上下文和堆栈
+
+## 代码示例
+
+### 1. 自定义业务异常
+
+```java
+package [你的包名].exception;
+
+import lombok.Getter;
+
+@Getter
+public class BusinessException extends RuntimeException {
+
+    private final int code;
+
+    public BusinessException(String message) {
+        super(message);
+        this.code = 500;
+    }
+
+    public BusinessException(int code, String message) {
+        super(message);
+        this.code = code;
+    }
+
+    public BusinessException(int code, String message, Throwable cause) {
+        super(message, cause);
+        this.code = code;
+    }
+}
+```
+
+```java
+package [你的包名].exception;
+
+public class NotFoundException extends BusinessException {
+
+    public NotFoundException(String message) {
+        super(404, message);
+    }
+
+    public static NotFoundException of(String resource, Object id) {
+        return new NotFoundException(resource + " 不存在: " + id);
+    }
+}
+```
+
+### 2. 全局异常处理器
+
+```java
+package [你的包名].handler;
+
+import [你的包名].exception.BusinessException;
+import [你的包名].exception.NotFoundException;
+import jakarta.validation.ConstraintViolation;
+import jakarta.validation.ConstraintViolationException;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.validation.FieldError;
+import org.springframework.web.bind.MethodArgumentNotValidException;
+import org.springframework.web.bind.MissingServletRequestParameterException;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+
+import java.util.Map;
+import java.util.stream.Collectors;
+
+@Slf4j
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    /**
+     * 业务异常
+     */
+    @ExceptionHandler(BusinessException.class)
+    public ResponseEntity<Result<Void>> handleBusinessException(BusinessException e) {
+        log.warn("业务异常: {}", e.getMessage());
+        return ResponseEntity
+                .status(HttpStatus.BAD_REQUEST)
+                .body(Result.fail(e.getCode(), e.getMessage()));
+    }
+
+    /**
+     * 资源不存在
+     */
+    @ExceptionHandler(NotFoundException.class)
+    public ResponseEntity<Result<Void>> handleNotFoundException(NotFoundException e) {
+        log.warn("资源不存在: {}", e.getMessage());
+        return ResponseEntity
+                .status(HttpStatus.NOT_FOUND)
+                .body(Result.fail(404, e.getMessage()));
+    }
+
+    /**
+     * @RequestBody 参数校验失败
+     */
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public ResponseEntity<Result<Map<String, String>>> handleValidationException(
+            MethodArgumentNotValidException e) {
+        Map<String, String> errors = e.getBindingResult().getFieldErrors().stream()
+                .collect(Collectors.toMap(
+                        FieldError::getField,
+                        fe -> fe.getDefaultMessage() != null ? fe.getDefaultMessage() : "校验失败",
+                        (v1, v2) -> v1
+                ));
+        log.warn("参数校验失败: {}", errors);
+        return ResponseEntity
+                .status(HttpStatus.BAD_REQUEST)
+                .body(Result.fail(400, "参数校验失败"));
+    }
+
+    /**
+     * @RequestParam / @PathVariable 校验失败
+     */
+    @ExceptionHandler(ConstraintViolationException.class)
+    public ResponseEntity<Result<Void>> handleConstraintViolation(ConstraintViolationException e) {
+        String message = e.getConstraintViolations().stream()
+                .map(ConstraintViolation::getMessage)
+                .collect(Collectors.joining("; "));
+        log.warn("约束校验失败: {}", message);
+        return ResponseEntity
+                .status(HttpStatus.BAD_REQUEST)
+                .body(Result.fail(400, message));
+    }
+
+    /**
+     * 缺少请求参数
+     */
+    @ExceptionHandler(MissingServletRequestParameterException.class)
+    public ResponseEntity<Result<Void>> handleMissingParam(MissingServletRequestParameterException e) {
+        log.warn("缺少请求参数: {}", e.getParameterName());
+        return ResponseEntity
+                .status(HttpStatus.BAD_REQUEST)
+                .body(Result.fail(400, "缺少参数: " + e.getParameterName()));
+    }
+
+    /**
+     * 兜底：未知异常
+     */
+    @ExceptionHandler(Exception.class)
+    public ResponseEntity<Result<Void>> handleException(Exception e) {
+        log.error("系统异常", e);
+        return ResponseEntity
+                .status(HttpStatus.INTERNAL_SERVER_ERROR)
+                .body(Result.fail(500, "系统繁忙，请稍后重试"));
+    }
+}
+```
+
+### 3. 参数校验（jakarta.validation）
+
+```java
+package [你的包名].dto;
+
+import jakarta.validation.constraints.*;
+import lombok.Data;
+
+@Data
+public class UserCreateDTO {
+
+    @NotBlank(message = "用户名不能为空")
+    @Size(min = 2, max = 32, message = "用户名长度 2-32 位")
+    private String username;
+
+    @NotBlank(message = "邮箱不能为空")
+    @Email(message = "邮箱格式不正确")
+    private String email;
+
+    @NotNull(message = "年龄不能为空")
+    @Min(value = 1, message = "年龄最小为 1")
+    @Max(value = 150, message = "年龄最大为 150")
+    private Integer age;
+
+    @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不正确")
+    private String phone;
+}
+```
+
+**Controller 中使用**：
+```java
+@PostMapping
+public ResponseEntity<Result<Long>> create(@Valid @RequestBody UserCreateDTO dto) {
+    return ResponseEntity.ok(Result.ok(userService.create(dto)));
+}
+```
+
+### 4. 分组校验
+
+```java
+public interface CreateGroup {}
+public interface UpdateGroup {}
+
+@Data
+public class UserDTO {
+
+    @Null(groups = CreateGroup.class, message = "创建时不能指定 ID")
+    @NotNull(groups = UpdateGroup.class, message = "更新时必须指定 ID")
+    private Long id;
+
+    @NotBlank(groups = {CreateGroup.class, UpdateGroup.class})
+    private String username;
+}
+
+// Controller 使用
+@PostMapping
+public Result<Long> create(@Validated(CreateGroup.class) @RequestBody UserDTO dto) { ... }
+
+@PutMapping("/{id}")
+public Result<Void> update(@Validated(UpdateGroup.class) @RequestBody UserDTO dto) { ... }
+```
+
+### 5. Service 层异常使用
+
+```java
+@Service
+public class UserServiceImpl implements IUserService {
+
+    @Override
+    public UserVO getById(Long id) {
+        User user = userMapper.selectById(id);
+        if (user == null) {
+            throw NotFoundException.of("用户", id);
+        }
+        // ... 转换为 VO
+        return userVO;
+    }
+
+    @Override
+    public void updateEmail(Long id, String email) {
+        // 检查邮箱是否已被使用
+        User existing = userMapper.selectByEmail(email);
+        if (existing != null && !existing.getId().equals(id)) {
+            throw new BusinessException(409, "邮箱已被其他用户使用");
+        }
+        // ... 更新逻辑
+    }
+}
+```
+
+### 6. 日志规范
+
+```java
+@Slf4j
+@Service
+public class OrderServiceImpl {
+
+    // 使用占位符（性能更好）
+    log.info("创建订单: orderNo={}, amount={}", dto.getOrderNo(), dto.getAmount());
+
+    // 异常日志带堆栈（第三个参数传异常对象）
+    log.error("处理失败: {}", e.getMessage(), e);
+
+    // 事务方法：所有异常都回滚
+    @Transactional(rollbackFor = Exception.class)
+    public void createOrder(OrderCreateDTO dto) {
+        log.info("开始创建订单, orderNo={}", dto.getOrderNo());
+        // ... 业务逻辑
+        log.info("订单创建成功, id={}", order.getId());
+    }
+}
+```
+
+## 常见错误
+
+| 错误 | 正确做法 |
+|------|---------|
+| 抛 `RuntimeException("xxx")` | 使用自定义业务异常类 |
+| Controller 里 try-catch 所有异常 | 交给 `@RestControllerAdvice` 统一处理 |
+| 异常信息暴露 SQL / 堆栈 | 对用户返回友好提示，日志记录完整信息 |
+| 用 `javax.validation` 包 | JDK 17+ 使用 `jakarta.validation` |
+| 吞掉异常：`catch (Exception e) {}` | 至少记录日志 `log.error("...", e)` |
+| 所有异常都返回 200 状态码 | 根据异常类型返回对应 HTTP 状态码 |
+| 用 `e.getMessage()` 直接返回给用户 | 第三方异常信息可能包含敏感信息，需要包装 |
+| 校验逻辑写在 Controller 里 | 用 `@Valid` + DTO 注解声明式校验 |
+| 日志用字符串拼接 `"失败:" + msg` | 用占位符 `log.error("失败: {}", msg, e)` |
+| `@Transactional` 不指定回滚 | 加 `rollbackFor = Exception.class` |

package/.cursor/skills/file-oss-management/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: file-oss-management
+description: |
+  当需要进行文件上传、下载、存储管理时自动使用此 Skill。支持本地存储、阿里云OSS、腾讯云COS、七牛云、MinIO等。
+
+  触发场景：
+  - 文件上传下载
+  - 云存储配置
+  - 预签名URL生成
+  - 文件元数据管理
+  - OSS服务商切换
+
+  触发词：文件上传、OSS、云存储、MinIO、阿里云、腾讯云、七牛、图片上传、文件下载、预签名、presigned、S3
+---
+
+# 文件与云存储指南
+
+> 统一协议：基于 AWS S3 SDK v2，兼容所有 S3 协议云服务
+
+## 架构概述
+
+| 组件 | 说明 |
+|----|------|
+| `[你的OssClient]` | 统一操作入口（基于 AWS S3 SDK v2） |
+| `S3Client` | AWS SDK 底层客户端 |
+| `UploadResult` | 上传结果（url, filename, eTag） |
+
+---
+
+## 一、S3 Client 初始化
+
+```java
+import software.amazon.awssdk.services.s3.S3Client;
+import software.amazon.awssdk.services.s3.presigner.S3Presigner;
+import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider;
+import software.amazon.awssdk.auth.credentials.AwsBasicCredentials;
+import software.amazon.awssdk.regions.Region;
+
+// 通用 S3 客户端构建（兼容 MinIO / 阿里云 / 腾讯云等）
+S3Client s3Client = S3Client.builder()
+    .endpointOverride(URI.create(endpoint))
+    .credentialsProvider(StaticCredentialsProvider.create(
+        AwsBasicCredentials.create(accessKey, secretKey)))
+    .region(Region.of(region))
+    .forcePathStyle(true)   // MinIO 需要开启
+    .build();
+```
+
+---
+
+## 二、文件上传
+
+### 基础上传
+
+```java
+import software.amazon.awssdk.services.s3.model.PutObjectRequest;
+import software.amazon.awssdk.core.sync.RequestBody;
+
+// 上传文件
+PutObjectRequest request = PutObjectRequest.builder()
+    .bucket(bucketName)
+    .key("images/photo.jpg")
+    .contentType("image/jpeg")
+    .build();
+
+s3Client.putObject(request, RequestBody.fromFile(file.toPath()));
+
+// 上传输入流
+s3Client.putObject(request, RequestBody.fromInputStream(inputStream, contentLength));
+
+// 上传字节数组
+s3Client.putObject(request, RequestBody.fromBytes(data));
+```
+
+### 封装上传服务（推荐模式）
+
+```java
+@Service
+@RequiredArgsConstructor
+public class OssService {
+
+    private final S3Client s3Client;
+    private final OssProperties properties;
+
+    /**
+     * 上传文件，自动生成路径
+     */
+    public UploadResult upload(MultipartFile file) {
+        String suffix = getFileSuffix(file.getOriginalFilename());
+        String key = generateObjectKey(suffix);  // 如 2026/03/07/uuid.jpg
+
+        PutObjectRequest request = PutObjectRequest.builder()
+            .bucket(properties.getBucketName())
+            .key(key)
+            .contentType(file.getContentType())
+            .build();
+
+        s3Client.putObject(request,
+            RequestBody.fromInputStream(file.getInputStream(), file.getSize()));
+
+        return UploadResult.builder()
+            .url(properties.getDomain() + "/" + key)
+            .filename(key)
+            .build();
+    }
+
+    private String generateObjectKey(String suffix) {
+        String datePath = LocalDate.now().format(DateTimeFormatter.ofPattern("yyyy/MM/dd"));
+        return datePath + "/" + UUID.randomUUID() + suffix;
+    }
+}
+```
+
+---
+
+## 三、文件下载
+
+```java
+import software.amazon.awssdk.services.s3.model.GetObjectRequest;
+import software.amazon.awssdk.core.ResponseInputStream;
+
+// 下载到输出流（推荐用于HTTP响应）
+GetObjectRequest getRequest = GetObjectRequest.builder()
+    .bucket(bucketName)
+    .key("images/photo.jpg")
+    .build();
+
+ResponseInputStream<?> response = s3Client.getObject(getRequest);
+
+// 写入 HTTP 响应
+try (InputStream is = response) {
+    httpResponse.setContentType("image/jpeg");
+    httpResponse.setContentLengthLong(response.response().contentLength());
+    is.transferTo(httpResponse.getOutputStream());
+}
+```
+
+---
+
+## 四、文件删除
+
+```java
+import software.amazon.awssdk.services.s3.model.DeleteObjectRequest;
+
+DeleteObjectRequest deleteRequest = DeleteObjectRequest.builder()
+    .bucket(bucketName)
+    .key("images/photo.jpg")
+    .build();
+
+s3Client.deleteObject(deleteRequest);
+```
+
+---
+
+## 五、预签名 URL
+
+```java
+import software.amazon.awssdk.services.s3.presigner.S3Presigner;
+import software.amazon.awssdk.services.s3.presigner.model.*;
+
+S3Presigner presigner = S3Presigner.builder()
+    .endpointOverride(URI.create(endpoint))
+    .credentialsProvider(credentialsProvider)
+    .region(Region.of(region))
+    .build();
+
+// 下载预签名URL
+GetObjectPresignRequest getPresignRequest = GetObjectPresignRequest.builder()
+    .signatureDuration(Duration.ofMinutes(60))
+    .getObjectRequest(b -> b.bucket(bucketName).key("images/photo.jpg"))
+    .build();
+String downloadUrl = presigner.presignGetObject(getPresignRequest).url().toString();
+
+// 上传预签名URL（前端直传）
+PutObjectPresignRequest putPresignRequest = PutObjectPresignRequest.builder()
+    .signatureDuration(Duration.ofHours(1))
+    .putObjectRequest(b -> b.bucket(bucketName).key("images/upload.jpg"))
+    .build();
+String uploadUrl = presigner.presignPutObject(putPresignRequest).url().toString();
+```
+
+---
+
+## 六、Controller 接口（设计模式）
+
+```java
+@RestController
+@RequiredArgsConstructor
+@RequestMapping("/api/oss")
+public class OssController {
+
+    private final OssService ossService;
+
+    @PostMapping(value = "/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    public UploadResult upload(@RequestPart("file") MultipartFile file) {
+        return ossService.upload(file);
+    }
+
+    @GetMapping("/download/{id}")
+    public void download(@PathVariable Long id, HttpServletResponse response) throws IOException {
+        ossService.download(id, response);
+    }
+
+    @DeleteMapping("/{ids}")
+    public void delete(@PathVariable List<Long> ids) {
+        ossService.deleteByIds(ids);
+    }
+}
+```
+
+---
+
+## 七、配置模型
+
+```yaml
+# application.yml
+oss:
+  endpoint: https://s3.amazonaws.com    # 或 MinIO/阿里云/腾讯云端点
+  access-key: your-access-key
+  secret-key: your-secret-key
+  bucket-name: your-bucket
+  region: us-east-1
+  domain: https://cdn.example.com       # 自定义域名（可选）
+```
+
+```java
+@Data
+@ConfigurationProperties(prefix = "oss")
+public class OssProperties {
+    private String endpoint;
+    private String accessKey;
+    private String secretKey;
+    private String bucketName;
+    private String region;
+    private String domain;
+}
+```
+
+---
+
+## 八、服务商对照
+
+| 服务商 | endpoint 示例 | 备注 |
+|--------|-------------|------|
+| 阿里云 OSS | `https://oss-cn-hangzhou.aliyuncs.com` | S3 兼容 |
+| 腾讯云 COS | `https://cos.ap-guangzhou.myqcloud.com` | S3 兼容 |
+| 七牛云 | `https://s3-cn-south-1.qiniucs.com` | S3 兼容 |
+| MinIO | `http://localhost:9000` | 需 `forcePathStyle(true)` |
+| AWS S3 | `https://s3.amazonaws.com` | 原生支持 |
+
+---
+
+## 九、设计要点
+
+1. **统一封装**：通过 S3 协议统一对接多个云服务商，切换只需改配置
+2. **路径生成**：按日期+UUID生成对象路径，避免冲突
+3. **私有桶**：私有桶文件通过预签名URL访问，设置合理的过期时间
+4. **文件记录**：上传后保存数据库记录，关联业务数据
+5. **大文件**：超过 100MB 考虑分片上传（`CreateMultipartUpload`）
+6. **安全**：前端直传使用预签名URL，不暴露密钥

package/.cursor/skills/file-oss-management/references/entities.md

@@ -0,0 +1,105 @@
+# OSS 数据库实体类定义
+
+## SysOss 实体
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+@TableName("sys_oss")
+public class SysOss extends TenantEntity {
+
+    @TableId(value = "oss_id")
+    private Long ossId;
+
+    private String fileName;         // OSS对象键
+    private String originalName;     // 原始文件名
+    private String fileSuffix;       // 后缀名（如 .jpg）
+    private String url;              // URL地址
+    private String ext1;             // 扩展字段（JSON）
+    private String service;          // 服务商标识
+
+    // 继承自 TenantEntity: tenantId, createTime, createBy, updateTime, updateBy, delFlag
+}
+```
+
+## SysOssVo 视图对象
+
+```java
+@Data
+@AutoMapper(target = SysOss.class)
+public class SysOssVo implements Serializable {
+
+    private Long ossId;
+    private String fileName;
+    private String originalName;
+    private String fileSuffix;
+    private String url;
+    private String ext1;
+    private Date createTime;
+    private Long createBy;
+
+    @Translation(type = TransConstant.USER_ID_TO_NAME, mapper = "createBy")
+    private String createByName;  // 上传人名称（自动翻译）
+
+    private String service;
+}
+```
+
+## SysOssBo 业务对象
+
+```java
+@Data
+@EqualsAndHashCode(callSuper = true)
+@AutoMapper(target = SysOss.class, reverseConvertGenerate = false)
+public class SysOssBo extends BaseEntity {
+
+    private Long ossId;
+    private String fileName;
+    private String originalName;
+    private String fileSuffix;
+    private String url;
+    private String ext1;
+    private String service;
+}
+```
+
+## SysOssExt 扩展信息对象
+
+> 以 JSON 字符串形式存储在 ext1 字段中
+
+```java
+@Data
+public class SysOssExt implements Serializable {
+
+    private String bizType;         // 业务类型（avatar、report等）
+    private Long fileSize;          // 文件大小（字节）
+    private String contentType;     // MIME类型
+    private String source;          // 来源标识
+    private String uploadIp;        // 上传IP
+    private String remark;          // 备注
+    private List<String> tags;      // 标签
+    private String refId;           // 绑定业务ID
+    private String refType;         // 绑定业务类型
+    private Boolean isTemp;         // 是否临时文件
+    private String md5;             // 文件MD5值
+}
+```
+
+## OssProperties 配置类
+
+```java
+@Data
+public class OssProperties {
+
+    private String tenantId;
+    private String endpoint;       // 访问站点
+    private String domain;         // 自定义域名
+    private String prefix;         // 文件前缀
+    private String accessKey;
+    private String secretKey;
+    private String bucketName;
+    private String region;
+    private String isHttps;        // Y/N
+    private String accessPolicy;   // 0-private, 1-public, 2-custom
+}
+```