@deepstorm/cli 0.1.0

package/dist/skills/reef-style-backend/fragments/java/exception-handling/quick-reference.md

@@ -0,0 +1,181 @@
+# 异常处理规范
+
+## 速查
+
+| 场景 | 决策 |
+| --- | --- |
+| 业务异常 | 继承 `BusinessException` → 按场景选子类：`ResourceNotFoundException` / `AlreadyExistsException` / `InvalidArgumentException` / `PermissionDeniedException` / `FailedPreconditionException` |
+| 全局捕获 | `@RestControllerAdvice` + `GlobalExceptionHandler` |
+| 错误响应 | `ErrorResponse(code, message, detail)` — AIP-193 兼容 |
+| 错误码 | `{MODULE}_{NNN}` 枚举：`ErrorCode` enum 统一管理 |
+| 参数校验失败 | `MethodArgumentNotValidException` → `InvalidArgumentException` 统一处理 |
+| 未知异常 | 兜底 500 — `GENERIC_001`，记录完整堆栈 |
+
+## 核心规范
+
+### 业务异常继承层次
+
+```
+RuntimeException
+└── BusinessException          ← 抽象基类，含 errorCode + httpStatus
+    ├── ResourceNotFoundException       (404)
+    ├── AlreadyExistsException          (409)
+    ├── InvalidArgumentException        (400)
+    ├── PermissionDeniedException       (403)
+    └── FailedPreconditionException     (400)
+```
+
+```java
+// 基类
+public abstract class BusinessException extends RuntimeException {
+    private final String errorCode;
+    private final HttpStatus httpStatus;
+    private final Map<String, Object> detail;
+
+    protected BusinessException(String errorCode, HttpStatus httpStatus, String message) {
+        super(message);
+        this.errorCode = errorCode;
+        this.httpStatus = httpStatus;
+        this.detail = Map.of();
+    }
+
+    protected BusinessException(String errorCode, HttpStatus httpStatus,
+                                String message, Map<String, Object> detail) {
+        super(message);
+        this.errorCode = errorCode;
+        this.httpStatus = httpStatus;
+        this.detail = detail;
+    }
+
+    public String getErrorCode() { return errorCode; }
+    public HttpStatus getHttpStatus() { return httpStatus; }
+    public Map<String, Object> getDetail() { return detail; }
+}
+
+// 子类示例
+public class ResourceNotFoundException extends BusinessException {
+    public ResourceNotFoundException(String errorCode, String resourceType, Object id) {
+        super(errorCode, HttpStatus.NOT_FOUND,
+              resourceType + " not found: " + id,
+              Map.of("resourceType", resourceType, "id", id));
+    }
+}
+```
+
+**规范：**
+- 业务异常**必须**继承 `BusinessException`，不得直接抛 `RuntimeException` 或 `ResponseStatusException`
+- 每个构造函数传入 `ErrorCode` 枚举值，而非硬编码字符串
+- 可选的 `detail` map 携带上下文信息（如资源 ID、字段名）用于调试
+
+### 错误码枚举
+
+```java
+public enum ErrorCode {
+    // User module — 001~099 输入验证, 100~199 资源状态, 200~299 权限
+    USER_001("USER_001", "用户名已存在"),
+    USER_002("USER_002", "邮箱格式无效"),
+    USER_100("USER_100", "用户不存在"),
+    USER_101("USER_101", "用户已禁用"),
+    USER_200("USER_200", "无权操作该用户"),
+
+    // Order module
+    ORDER_001("ORDER_001", "订单金额无效"),
+    ORDER_100("ORDER_100", "订单不存在"),
+    ORDER_101("ORDER_101", "订单状态不允许操作"),
+
+    // Auth module
+    AUTH_001("AUTH_001", "Token 已过期"),
+    AUTH_002("AUTH_002", "Token 无效"),
+    AUTH_201("AUTH_201", "无权限访问"),
+
+    // Generic
+    GENERIC_001("GENERIC_001", "系统内部错误");
+
+    private final String code;
+    private final String defaultMessage;
+
+    ErrorCode(String code, String defaultMessage) {
+        this.code = code;
+        this.defaultMessage = defaultMessage;
+    }
+
+    public String code() { return code; }
+    public String defaultMessage() { return defaultMessage; }
+}
+```
+
+### @RestControllerAdvice 全局处理
+
+```java
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+
+    // 业务异常
+    @ExceptionHandler(BusinessException.class)
+    public ResponseEntity<ErrorResponse> handleBusiness(BusinessException ex) {
+        return ResponseEntity
+            .status(ex.getHttpStatus())
+            .body(ErrorResponse.of(ex.getErrorCode(), ex.getMessage(), ex.getDetail()));
+    }
+
+    // 参数校验失败
+    @ExceptionHandler(MethodArgumentNotValidException.class)
+    public ResponseEntity<ErrorResponse> handleValidation(MethodArgumentNotValidException ex) {
+        var errors = ex.getBindingResult().getFieldErrors().stream()
+            .map(e -> Map.of("field", e.getField(), "message", e.getDefaultMessage()))
+            .toList();
+        return ResponseEntity
+            .status(HttpStatus.BAD_REQUEST)
+            .body(ErrorResponse.of("VALIDATION_001", "参数校验失败", Map.of("errors", errors)));
+    }
+
+    // 404 未命中路由
+    @ExceptionHandler(NoHandlerFoundException.class)
+    public ResponseEntity<ErrorResponse> handleNotFound(NoHandlerFoundException ex) {
+        return ResponseEntity
+            .status(HttpStatus.NOT_FOUND)
+            .body(ErrorResponse.of("GENERIC_404", "接口不存在: " + ex.getRequestURL()));
+    }
+
+    // 兜底：未捕获异常 → 500
+    @ExceptionHandler(Exception.class)
+    public ResponseEntity<ErrorResponse> handleUnexpected(Exception ex) {
+        log.error("Unexpected error", ex);  // 完整堆栈只打日志，不返回客户端
+        return ResponseEntity
+            .status(HttpStatus.INTERNAL_SERVER_ERROR)
+            .body(ErrorResponse.of("GENERIC_001", "系统内部错误"));
+    }
+}
+```
+
+**规范：**
+- 不要在每个 Controller 中写 try-catch
+- 不要吞异常后返回 null 或空集合
+- 兜底 handler 必须 `log.error` 记录完整堆栈
+
+### 异常使用示例
+
+```java
+// Service 层
+@Service
+public class UserService {
+    public UserResponse getUser(Long id) {
+        return userRepository.findById(id)
+            .map(UserResponse::from)
+            .orElseThrow(() -> new ResourceNotFoundException(
+                ErrorCode.USER_100.code(), "User", id));
+    }
+}
+
+// Controller 层不需要 try-catch
+@RestController
+@RequestMapping("/api/v1/users")
+public class UserController {
+    private final UserService userService;
+
+    @GetMapping("/{id}")
+    public ResponseEntity<ApiResponse<UserResponse>> getUser(@PathVariable Long id) {
+        return ResponseEntity.ok(ApiResponse.success(userService.getUser(id)));
+    }
+}
+```

package/dist/skills/reef-style-backend/fragments/java/framework/spring-boot/examples/controller.md

@@ -0,0 +1,95 @@
+# 后端 Controller 示例
+
+---
+
+## 1. 标准 Controller（CRUD + 自定义方法）
+
+```java
+@RestController
+@RequestMapping("/api/v1/apps/{appId}/forms")
+@AllArgsConstructor
+public class FormController {
+  private final FormService service;
+
+  @GetMapping
+  public ListFormsResponse listForms(@PathVariable Long appId) {
+    return service.listForms(appId);
+  }
+
+  @GetMapping("/{formId}")
+  public FormDetailsDto getForm(
+      @PathVariable Long appId, @PathVariable Long formId) {
+    return service.getForm(appId, formId);
+  }
+
+  @PostMapping
+  public FormDetailsDto createForm(
+      @PathVariable Long appId, @Valid @RequestBody CreateFormRequest request) {
+    return service.createForm(appId, request);
+  }
+
+  @PatchMapping("/{formId}")
+  public FormDetailsDto updateForm(
+      @PathVariable Long appId,
+      @PathVariable Long formId,
+      @Valid @RequestBody UpdateFormRequest request) {
+    return service.updateForm(appId, formId, request);
+  }
+
+  @DeleteMapping("/{formId}")
+  public void deleteForm(
+      @PathVariable Long appId, @PathVariable Long formId) {
+    service.deleteForm(appId, formId);
+  }
+
+  // AIP-136 自定义方法：冒号语法
+  @PostMapping("/{formId}:publish")
+  public FormDetailsDto publishForm(
+      @PathVariable Long appId,
+      @PathVariable Long formId,
+      @RequestBody PublishFormRequest request) {
+    return service.publishForm(appId, formId, request);
+  }
+}
+```
+
+---
+
+## 2. Controller 含 @AuthenticationPrincipal
+
+```java
+@RestController
+@RequestMapping("/api/v1/apps/{appId}/forms/{formId}")
+@AllArgsConstructor
+public class FormResponseController {
+  private final FormResponseService service;
+
+  @GetMapping("/responses")
+  public ListFormResponsesResponse listFormResponses(
+      @PathVariable Long appId,
+      @PathVariable Long formId,
+      @AuthenticationPrincipal User user) {
+    return service.listFormResponses(appId, formId, user);
+  }
+
+  @PostMapping("/responses")
+  public FormResponseDto createFormResponse(
+      @PathVariable Long appId,
+      @PathVariable Long formId,
+      @RequestBody CreateFormResponseRequest request,
+      @AuthenticationPrincipal User user) {
+    return service.createFormResponse(appId, formId, request, user);
+  }
+
+  // AIP-136 自定义方法
+  @PostMapping("/responses/{responseId}:approve")
+  public FormResponseDto approveFormResponse(
+      @PathVariable Long appId,
+      @PathVariable Long formId,
+      @PathVariable Long responseId,
+      @RequestBody ApproveFormResponseRequest request,
+      @AuthenticationPrincipal User user) {
+    return service.approveFormResponse(appId, formId, responseId, request, user);
+  }
+}
+```

package/dist/skills/reef-style-backend/fragments/java/framework/spring-boot/examples/dto-mapper.md

@@ -0,0 +1,121 @@
+# 后端 DTO/MapStruct 示例
+
+---
+
+## 1. DTO 层次
+
+DTO 层次镜像实体层次，基类定义通用字段：
+
+```mermaid
+classDiagram
+    class AbstractImmutableDto {
+        +id
+        +createdAt
+    }
+    class AbstractDto {
+        +lastModifiedAt
+    }
+    class AbstractAuditableDto~U~ {
+        +createdBy
+        +lastModifiedBy
+    }
+    class AbstractImmutableAuditableDto~U~ {
+        +createdBy
+    }
+
+    AbstractImmutableDto <|-- AbstractDto
+    AbstractDto <|-- AbstractAuditableDto~U~
+    AbstractImmutableDto <|-- AbstractImmutableAuditableDto~U~
+```
+
+`<U>` 为解析后的用户对象类型（如 `UserSummaryDto`），与实体的 `Long createdById` 不同。
+
+---
+
+## 2. DTO 定义
+
+### 读 DTO（@Value，不可变）
+
+```java
+@Value
+public class FormSummaryDto extends AbstractDto {
+  String title;
+  boolean approvalEnabled;
+}
+
+// 含审计字段：<U> 为 UserSummaryDto
+@Value
+public class FormResponseDto extends AbstractAuditableDto<UserSummaryDto> {
+  Long formId;
+  Map<String, Object> data;
+}
+```
+
+### 写 record（可变，独立于读 DTO）
+
+```java
+public record CreateFormRequest(boolean approvalEnabled) {}
+
+public record UpdateFormRequest(
+    @NotBlank String title,
+    @Valid PrintConfigDto printConfig,
+    @NotEmpty List<@Valid FormActionDto> actions) {}
+```
+
+---
+
+## 3. MapStruct Mapper
+
+### 基础 Mapper
+
+```java
+@Mapper(config = MapStructConfig.class, uses = { FormRevisionMapper.class, FormItemMapper.class })
+public interface FormMapper {
+  FormMapper INSTANCE = Mappers.getMapper(FormMapper.class);
+
+  FormSummaryDto mapToSummary(Form form);
+  FormDetailsDto mapToDetails(Form form);
+}
+```
+
+### 嵌套子映射（uses）
+
+包含关联实体的 Mapper 通过 `uses` 组合子 Mapper，MapStruct 自动递归映射：
+
+```java
+// 父 Mapper：声明依赖子 Mapper
+@Mapper(config = MapStructConfig.class, uses = DataObjectFieldMapper.class)
+public interface DataObjectMapper {
+  DataObjectMapper INSTANCE = Mappers.getMapper(DataObjectMapper.class);
+
+  DataObjectSummaryDto mapToSummary(DataObject entity);
+  DataObjectDetailsDto mapToDetails(DataObject entity);
+}
+
+// 子 Mapper：处理嵌套字段
+@Mapper(config = MapStructConfig.class)
+public interface DataObjectFieldMapper {
+  DataObjectFieldMapper INSTANCE = Mappers.getMapper(DataObjectFieldMapper.class);
+
+  DataObjectFieldDto mapToDto(DataObjectField field);
+}
+```
+
+当 `DataObject` 包含 `List<DataObjectField> fields` 时，`DataObjectMapper` 自动通过 `DataObjectFieldMapper` 映射到 `List<DataObjectFieldDto>`，无需额外配置。
+
+### 命名约定
+
+| 方法名 | 用途 |
+|--------|------|
+| `mapToSummary(entity)` | 精简 DTO（列表用） |
+| `mapToDetails(entity)` | 完整 DTO（详情用） |
+
+---
+
+## 4. MapStructConfig
+
+```java
+@MapperConfig(
+    subclassExhaustiveStrategy = SubclassExhaustiveStrategy.RUNTIME_EXCEPTION)
+public interface MapStructConfig {}
+```

package/dist/skills/reef-style-backend/fragments/java/framework/spring-boot/examples/infrastructure.md

@@ -0,0 +1,179 @@
+# 后端基础设施示例
+
+---
+
+## 1. 异常定义
+
+```java
+public class NotFoundException extends RuntimeException {
+  public NotFoundException(String message) {
+    super(message);
+  }
+
+  public NotFoundException(String message, ResourceInfo resourceInfo) {
+    super(message);
+    this.resourceInfo = resourceInfo;
+  }
+}
+```
+
+使用：`throw new NotFoundException("资源不存在", new ResourceInfo("Form", id));`
+
+---
+
+## 2. Error Status 枚举
+
+```java
+public enum Status {
+  OK(200),
+  INVALID_ARGUMENT(400),
+  FAILED_PRECONDITION(400),
+  NOT_FOUND(404),
+  ALREADY_EXISTS(409),
+  PERMISSION_DENIED(403),
+  INTERNAL(500),
+  ;
+}
+```
+
+---
+
+## 3. 多租户基类
+
+### AbstractTenantAwareEntity（无审计）
+
+```java
+@MappedSuperclass
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+public abstract class AbstractTenantAwareEntity extends AbstractEntity {
+  @Getter
+  @org.hibernate.annotations.TenantId
+  private Long tenantId;
+
+  protected AbstractTenantAwareEntity(Long id) {
+    super(id);
+  }
+
+  protected AbstractTenantAwareEntity(Long id, Long tenantId) {
+    super(id);
+    this.tenantId = tenantId;
+  }
+}
+```
+
+### AbstractTenantAwareAuditable（有审计字段）
+
+审计字段来自 `AbstractAuditable`（`AbstractEntity` → `AbstractAuditable` → `AbstractTenantAwareAuditable`）：
+
+```java
+@MappedSuperclass
+@EntityListeners(AuditingEntityListener.class)
+@NoArgsConstructor(access = AccessLevel.PROTECTED, force = true)
+@Getter
+public abstract class AbstractAuditable extends AbstractEntity {
+  @NotNull @CreatedBy  private Long createdById;
+  @NotNull @LastModifiedBy  private Long lastModifiedById;
+
+  protected AbstractAuditable(Long id, Long createdById) {
+    super(id);
+    this.createdById = createdById;
+    this.lastModifiedById = createdById;
+  }
+}
+
+@MappedSuperclass
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+public abstract class AbstractTenantAwareAuditable extends AbstractAuditable {
+  @org.hibernate.annotations.TenantId
+  private Long tenantId;
+
+  protected AbstractTenantAwareAuditable(Long id, Long createdById) {
+    super(id, createdById);
+  }
+}
+```
+
+- `createdById` / `lastModifiedById` 由 `AuditingEntityListener` 通过 Spring Security 自动填充
+- 实体构造函数传一次 `createdById`，后续修改由 `@LastModifiedBy` 自动更新
+- `AbstractTenantAwareAuditable` 同时具备审计字段 + 多租户过滤
+
+---
+
+## 4. 校验
+
+### DTO 字段校验
+
+用 `jakarta.validation` 注解声明在 DTO/record 字段上：
+
+```java
+public record CreateFormRequest(
+    @NotBlank String title,
+
+    @Size(max = 200)
+    String description,
+
+    @Valid   // 嵌套对象必须加 @Valid 才能递归校验
+    PrintConfigDto printConfig,
+
+    @NotEmpty
+    List<@Valid FormActionDto> actions
+) {}
+```
+
+Controller 参数加 `@Valid` 触发校验：
+
+```java
+@PostMapping
+public FormDetailsDto createForm(
+    @PathVariable Long appId,
+    @Valid @RequestBody CreateFormRequest request) { ... }
+```
+
+### 跨字段校验
+
+跨字段逻辑（如结束日期 ≥ 开始日期）在 Service 中显式判断：
+
+```java
+@Transactional
+public void updateForm(Long appId, Long formId, UpdateFormRequest request) {
+  if (request.endDate() != null && request.startDate() != null
+      && request.endDate().isBefore(request.startDate())) {
+    throw new InvalidArgumentException("结束日期不能早于开始日期");
+  }
+  ...
+}
+```
+
+### 程序化校验
+
+复杂校验注入 `jakarta.validation.Validator` 手动调用：
+
+```java
+@Service
+@AllArgsConstructor
+public class ImportService {
+  private final Validator validator;
+
+  public void importForms(List<ImportItem> items) {
+    for (var item : items) {
+      var violations = validator.validate(item);
+      if (!violations.isEmpty()) {
+        throw new InvalidArgumentException(
+            "导入数据校验失败: " + violations.iterator().next().getMessage());
+      }
+    }
+  }
+}
+```
+
+---
+
+## 5. 分页响应
+
+```java
+@Value
+public final class PagedResponse<T extends AbstractImmutableDto> {
+  List<T> items;
+  long totalItems;
+}
+```