@deepstorm/cli 0.1.0

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

@@ -0,0 +1,202 @@
+# 后端 Service/Entity/Repository 示例
+
+## 1. Service（getEntity 模式 + @Transactional）
+
+```java
+@Service
+@AllArgsConstructor
+public class FormService {
+  private final FormRepository formRepository;
+  private final ApplicationService appService;
+
+  public FormDetailsDto getForm(Long appId, Long formId) {
+    return FormMapper.INSTANCE.mapToDetails(getFormEntity(appId, formId));
+  }
+
+  public Form getFormEntity(Long appId, Long formId) {
+    return formRepository.findByIdAndAppId(formId, appId).orElseThrow(
+        () -> new NotFoundException("表单不存在", new ResourceInfo("Form", formId)));
+  }
+
+  @Transactional
+  public FormDetailsDto createForm(Long appId, CreateFormRequest request) {
+    var app = appService.getApplicationEntity(appId);
+    var form = new Form("新的表单", request.approvalEnabled(), app.getId());
+    return FormMapper.INSTANCE.mapToDetails(formRepository.save(form));
+  }
+
+  @Transactional
+  public void deleteForm(Long appId, Long formId) {
+    formRepository.delete(getFormEntity(appId, formId));
+  }
+}
+```
+
+## 2. Repository（多租户感知）
+
+```java
+public interface FormRepository extends JpaRepository<Form, Long> {
+  List<Form> findAllByAppId(Long appId);
+  Optional<Form> findByIdAndAppId(Long id, Long appId);
+
+  @Query("""
+      select distinct f from Form f
+      left join fetch f.revisions r
+      left join fetch r.items
+      where f.id = ?1 and f.appId = ?2
+      """)
+  Optional<Form> findByIdAndAppIdWithRevisionsAndItems(
+      @Param("id") Long id, @Param("appId") Long appId);
+}
+```
+
+## 3. 实体
+
+| 场景 | 基类 |
+|------|------|
+| 普通多租户，可变 | `AbstractTenantAwareEntity` |
+| 多租户 + 审计字段 | `AbstractTenantAwareAuditable` |
+| 多租户，不可变 + 审计 | `AbstractTenantAwareImmutableAuditable` |
+| 非租户实体（极少） | `AbstractEntity` 或 `AbstractAuditable` |
+
+```java
+@Entity
+@Table(name = "app_form", indexes = { @Index(columnList = "app_id") })
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+public class Form extends AbstractTenantAwareEntity {
+  @NotBlank @Column(nullable = false)
+  private String title;
+  @Column(name = "approval_enabled", nullable = false)
+  private boolean approvalEnabled;
+  @Column(name = "app_id", nullable = false)
+  private Long appId;
+  @OneToMany(mappedBy = "form", cascade = CascadeType.ALL, orphanRemoval = true)
+  private List<FormRevision> revisions = new ArrayList<>();
+
+  @Default
+  public Form(Long id) { super(id); }
+
+  public Form(String title, boolean approvalEnabled, Long appId) {
+    this.title = title; this.approvalEnabled = approvalEnabled; this.appId = appId;
+  }
+}
+```
+
+## 4. 事件驱动级联删除
+
+跨 Service 的关联数据清理通过事件驱动解耦。三个原则：谁删除谁发布事件，谁清理谁监听事件，事件参数最小化。
+
+```mermaid
+flowchart LR
+    DELETE["FormService.deleteForm()"] --> REPO["formRepository.delete(form)"]
+    DELETE --> EVENT["eventPublisher.publishEvent(event)"]
+    EVENT --> FRS["FormResponseService @EventListener<br/>删除 FormResponse"]
+    EVENT --> LES["LogEntryService @EventListener<br/>删除相关日志"]
+```
+
+```java
+// 发布方
+@Service @AllArgsConstructor
+public class FormService {
+  private final ApplicationEventPublisher eventPublisher;
+
+  @Transactional
+  public void deleteForm(Long appId, Long formId) {
+    var form = getFormEntity(appId, formId);
+    formRepository.delete(form);
+    eventPublisher.publishEvent(new FormDeletedEvent(appId, formId, form.getTitle()));
+  }
+}
+
+// 事件类（@Getter @AllArgsConstructor，private final 不可变）
+@Getter @AllArgsConstructor
+public class FormDeletedEvent {
+  private final Long appId;
+  private final Long formId;
+  private final String formTitle;
+}
+
+// 监听方（各自处理自己的数据范围）
+@Service
+public class FormResponseService {
+  @EventListener @Transactional
+  public void handleFormDeletedEvent(FormDeletedEvent event) {
+    formResponseRepository.deleteByFormId(event.getFormId());
+  }
+}
+```
+
+事件发布注意事项：事件参数顺序 `appId` → 父级 ID → 自身 ID → name；监听方法加 `@Transactional`；事务提交后事件才派发。
+
+## 5. Reference Contributor 模式
+
+删除资源前查询哪些其他资源引用了它。完整代码示例见 [`contributor-pattern.md`](contributor-pattern.md)。
+
+## 6. 日志实体继承
+
+所有日志使用 `SINGLE_TABLE` 策略，统一存储在 `log_entry` 表：
+
+```mermaid
+classDiagram
+    class LogEntry { +appId }
+    class ActionLogEntry { +title +record +actionTitle +时间 +status }
+    class FormActionLogEntry { +formResponseId }
+    class TableActionLogEntry
+    class FormDeletionLogEntry { +formId +formTitle }
+    LogEntry <|-- ActionLogEntry
+    ActionLogEntry <|-- FormActionLogEntry
+    ActionLogEntry <|-- TableActionLogEntry
+    LogEntry <|-- FormDeletionLogEntry
+```
+
+```java
+@Entity @NoArgsConstructor(access = AccessLevel.PROTECTED) @Getter
+public class FormDeletionLogEntry extends LogEntry {
+  private Long formId;
+  private String formTitle;
+
+  public FormDeletionLogEntry(Long appId, Long formId, String formTitle) {
+    super(appId);
+    this.formId = formId; this.formTitle = formTitle;
+  }
+}
+```
+
+关键规则：新日志类型继承 `LogEntry`，不直接继承 `AbstractTenantAwareImmutableAuditable`；构造函数调 `super(appId)`；`createdById` 由 `AuditingEntityListener` 自动填充；新增字段在 Liquibase 中 `nullable = true`。
+
+## 7. 长时运行异步操作（AIP-151）
+
+耗时操作（如 CSV 导入）通过 `Operation` 抽象实体 + `@DomainEvents` 模式实现异步状态管理：
+
+```mermaid
+classDiagram
+    class Operation { <<abstract>> +Status +Metadata metadata +Result result +run() +doRun() }
+    class Metadata { <<abstract>> }
+    class Result { <<abstract>> }
+    class EmptyResult
+    class ErrorResult
+    Operation --> Metadata : @Embedded
+    Operation --> Result : @Embedded
+    Result <|-- EmptyResult
+    Result <|-- ErrorResult
+```
+
+```java
+@Service @AllArgsConstructor
+public class DictionaryItemService {
+  private final Validator validator;
+
+  @Transactional
+  public OperationDto importDictionaryItems(Long appId, Long dictId, MultipartFile file) {
+    var items = parseCsvFile(file);
+    List<String> messages = validateItems(items);
+    if (!messages.isEmpty()) {
+      return new ImportDictionaryItemsOperationDto(/* ... */);
+    }
+    repository.saveAll(items);
+    return new ImportDictionaryItemsOperationDto(/* ... */);
+  }
+}
+```
+
+关键规则：校验失败返回 `Status.FAILED` + 错误信息，不抛异常；`@DomainEvents` 在实体保存后自动派发；`@Embedded Metadata` / `Result` 支持子类型多态。DTO 层次使用 `@JsonTypeInfo` + `@JsonSubTypes` 实现多态 JSON 序列化。

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

@@ -0,0 +1,107 @@
+# 后端测试示例
+
+---
+
+## 1. Controller 测试
+
+```java
+@WebMvcTest(FormController.class)
+@Import({SecurityConfig.class, TestUserConfig.class})
+@WithUserDetails(
+    value = "admin", userDetailsServiceBeanName = "testUserDetailsService")
+@ActiveProfiles("test")
+class FormControllerTest {
+  @Autowired private MockMvc mvc;
+  @Autowired private ObjectMapper objectMapper;
+  @MockitoBean private FormService service;
+
+  @Test
+  void shouldReturnNotFound_whenFormDoesNotExist() throws Exception {
+    when(service.getForm(1L, 2L))
+        .thenThrow(new NotFoundException("表单不存在", new ResourceInfo("Form", 2L)));
+    mvc.perform(get("/api/v1/apps/1/forms/2"))
+        .andExpect(status().isNotFound())
+        .andExpect(jsonPath("$.code").value(404))
+        .andExpect(jsonPath("$.message").value("表单不存在"));
+  }
+
+  @Test
+  void shouldPublishForm() throws Exception {
+    var request = new PublishFormRequest(List.of(control), List.of());
+    when(service.publishForm(
+        eq(1L), eq(2L), any(PublishFormRequest.class)))
+        .thenReturn(FormMapper.INSTANCE.mapToDetails(form));
+    mvc.perform(post("/api/v1/apps/1/forms/2:publish")
+            .contentType(MediaType.APPLICATION_JSON)
+            .content(objectMapper.writeValueAsString(request)))
+        .andExpect(status().isOk())
+        .andExpect(jsonPath("$.title").value("form1"));
+  }
+}
+```
+
+---
+
+## 2. 多 Controller 测试
+
+```java
+@WebMvcTest({ FormController.class, FormRevisionController.class })
+@Import({SecurityConfig.class, TestUserConfig.class})
+@WithUserDetails(
+    value = "admin", userDetailsServiceBeanName = "testUserDetailsService")
+@ActiveProfiles("test")
+class FormRevisionControllerTest {
+  @Autowired private MockMvc mvc;
+  @MockitoBean private FormService formService;
+  @MockitoBean private FormRevisionService formRevisionService;
+}
+```
+
+---
+
+## 3. Service 集成测试
+
+```java
+@SpringBootTest
+@Transactional
+@ActiveProfiles("test")
+class ApplicationServiceTest {
+  @Autowired private ApplicationService service;
+  @Autowired private ApplicationRepository repository;
+
+  @Test
+  void shouldCreateApplication() {
+    var request = new CreateApplicationRequest("app1", null, null);
+    var dto = service.createApplication(request);
+    assertThat(dto.getName()).isEqualTo("app1");
+    assertThat(dto.getId()).isNotNull();
+  }
+}
+```
+
+---
+
+## 4. Service 事件测试
+
+```java
+@SpringBootTest
+@Transactional
+@ActiveProfiles("test")
+class FormServiceTest {
+
+  @Autowired private FormService formService;
+  @MockitoBean private FormRepository formRepository;
+  @Autowired private ApplicationEventPublisher eventPublisher;
+
+  @Test
+  void should_publish_event_when_delete_form() {
+    var captor = ArgumentCaptor.forClass(FormDeletedEvent.class);
+    verify(eventPublisher).publishEvent(captor.capture());
+    assertThat(captor.getValue().formId()).isEqualTo(1L);
+  }
+}
+```
+
+关键点：
+- `ArgumentCaptor` 验证事件发布，不直接 Mock `ApplicationEventPublisher`
+- `@Transactional` 确保每个测试回滚，互不干扰

package/dist/skills/reef-style-backend/fragments/java/framework/spring-boot/quick-reference.md

@@ -0,0 +1,83 @@
+# Spring Boot 规范
+
+按需加载。仅当需要编写对应组件类型时阅读相关章节。
+
+> **完整示例代码见 `examples/` 目录**（controller.md、service-entity.md、dto-mapper.md、testing.md、infrastructure.md）。
+
+## 速查
+
+| 场景 | 决策 |
+| --- | --- |
+| 新建 Controller | `@RestController` + `@RequestMapping("/api/v1/apps/{appId}/...")` + `@RequiredArgsConstructor` |
+| 新建 Service | `@Service` + `@Transactional` + `@RequiredArgsConstructor`，字段 `private final` |
+| 新建 Repository | 继承 `JpaRepository<Entity, Long>` |
+| 新建立方 DTO | 继承 `AbstractDto` 等基类或使用 `@Value` |
+| 新建写请求 | 独立 `record CreateRequest` / `UpdateRequest` |
+| 对象映射 | MapStruct `@Mapper(config = MapStructConfig.class)` |
+| 异常处理 | 使用项目自定义异常（`NotFoundException` 等） |
+| 多租户查询 | 禁止裸 `findById`，使用 `findByIdAndAppId`；禁止 `createNativeQuery` |
+| Controller 权限 | 写操作接口加 `@PreAuthorize("hasAuthority('...')")` |
+| 密码存储 | `BCryptPasswordEncoder` |
+| 弃用 API | 编译警告中的 `@Deprecated` API 在同一次 PR 中替换为新 API |
+
+## 核心规范
+
+### Controller 层
+
+- `@RestController` + `@RequestMapping("/api/v1/apps/{appId}/...")` + `@AllArgsConstructor`
+- 标准 CRUD：list / get / create / update / delete
+- 自定义方法用 AIP-136 冒号语法：`@PostMapping("/{id}:publish")`
+- 写操作 DTO 加 `@Valid`，嵌套对象加 `@Valid`
+- API 版本策略：非破坏性变更停留在当前版本；破坏性变更创建新 API 版本
+
+### Service 层
+
+- `@Service` + `@AllArgsConstructor`，依赖 `private final`
+- 提取 `getEntity()` 复用查找 + 异常抛出
+- 写操作加 `@Transactional`
+- 多租户查询：`repository.findByIdAndAppId(id, appId)` — 禁止裸 `findById`
+- 级联清理通过事件驱动（`eventPublisher.publishEvent(event)`）
+
+### Repository 层
+
+继承 `JpaRepository<Entity, Long>`。多租户实体提供 `findAllByAppId` 和 `findByIdAndAppId`。`@TenantId` 由 Hibernate 自动过滤，禁止 `createNativeQuery`。
+
+### DTO / MapStruct
+
+DTO 继承基类，写请求用独立 CreateRequest/UpdateRequest record。MapStruct：
+
+- `@Mapper(config = MapStructConfig.class, uses = { ... })`
+- 声明 `INSTANCE = Mappers.getMapper(...)`
+- 子映射通过 `uses` 组合
+- 映射方法命名区分：`toSummary()` / `toDetail()`
+
+### 异常处理
+
+| 异常 | HTTP | 场景 |
+| --- | --- | --- |
+| `NotFoundException` | 404 | 资源不存在 |
+| `AlreadyExistsException` | 409 | 重复创建 |
+| `InvalidArgumentException` | 400 | 参数校验失败 |
+| `PermissionDeniedException` | 403 | 无权限 |
+| `FailedPreconditionException` | 400 | 前置条件不满足 |
+
+所有自定义异常通过 `@RestControllerAdvice` `GlobalExceptionHandler` 统一处理，返回 AIP-193 兼容的 `CustomError` 结构：
+
+```java
+@RestControllerAdvice
+public class GlobalExceptionHandler {
+  @ExceptionHandler(ResourceNotFoundException.class)
+  public ResponseEntity<ErrorResponse> handleNotFound(ResourceNotFoundException ex) {
+    return ResponseEntity.status(NOT_FOUND).body(new ErrorResponse(ex.getMessage()));
+  }
+}
+```
+
+### 安全编码规范
+
+- Controller 写操作接口必须加 `@PreAuthorize("hasAuthority('PERMISSION_NAME')")`，禁止在方法内硬编码权限字符串
+- 请求体参数加 `@Valid`，嵌套对象加 `@Valid`
+- DTO 中密码/token 用 `@JsonIgnore` 或从响应 DTO 中排除
+- 密码使用 `BCryptPasswordEncoder`
+- 禁止 `createNativeQuery`（绕过多租户 + SQL 注入风险）
+- `@Query` 始终使用命名参数（`:paramName`），不用 `?1` 位置参数

package/dist/skills/reef-style-backend/fragments/java/orm/hibernate/quick-reference.md

@@ -0,0 +1,150 @@
+# Hibernate / JPA 规范
+
+按需加载。仅当需要编写对应组件类型时阅读相关章节。
+
+## 速查
+
+| 场景 | 决策 |
+| --- | --- |
+| 新建实体 | 继承 `AbstractTenantAwareEntity` 或 `AbstractTenantAwareAuditable` |
+| 实体 `@Table` 命名 | 小写蛇形复数，如 `app_forms` |
+| 审计字段 | `createdById` 由 `AuditingEntityListener` 自动填充 |
+| 日志实体 | 继承 `LogEntry`（SINGLE_TABLE），不直接继承基类 |
+| `open-in-view` | 设为 `false` |
+
+## 概述
+
+使用 Hibernate 作为 JPA 实现进行对象关系映射。
+
+## Entity 规范
+
+```java
+@Entity
+@Table(name = "users")
+@NoArgsConstructor(access = PROTECTED)
+@Getter
+@SuperBuilder
+public class User extends AbstractAuditable {
+
+  @Id
+  @GeneratedValue(strategy = GenerationType.IDENTITY)
+  private Long id;
+
+  @Column(nullable = false, length = 100)
+  private String name;
+
+  @Column(unique = true, nullable = false)
+  private String email;
+
+  @ManyToOne(fetch = LAZY)
+  @JoinColumn(name = "department_id")
+  private Department department;
+
+  @OneToMany(mappedBy = "user", cascade = ALL, orphanRemoval = true)
+  private List<Order> orders = new ArrayList<>();
+}
+```
+
+**规则：**
+- 继承正确的基类（参见「实体/DTO 层次」章节）
+- 三件套：`@Entity` + `@NoArgsConstructor(access = PROTECTED)`（final 字段加 `force = true`），`@Getter` 类级别或字段级别，`@SuperBuilder` 按需使用
+- `@Table(name = "...")` 命名：小写蛇形，复数
+- 字段用 `@Column(nullable = false)` 等约束
+- 关联关系：多租户实体间的关联用 `@ManyToOne(fetch = LAZY)` + `@JoinColumn(name = "...")`，避免 EAGER
+- 日志实体继承 `LogEntry`（SINGLE_TABLE），不要直接继承 `AbstractTenantAwareImmutableAuditable`
+- `createdById` 由 `AuditingEntityListener` 自动填充，构造函数不需要传递
+
+## 实体/DTO 层次
+
+```mermaid
+classDiagram
+    class AbstractImmutable {
+        +id
+        +createdAt
+    }
+    class AbstractEntity {
+        +lastModifiedAt
+        +version @Version
+    }
+    class AbstractTenantAwareEntity {
+        +tenantId @TenantId
+    }
+    class AbstractTenantAwareAuditable {
+        +createdBy
+        +lastModifiedBy
+    }
+    class AbstractImmutableAuditable {
+        +createdBy
+    }
+    class AbstractTenantAwareImmutableAuditable {
+        +tenantId @TenantId
+        +lastModifiedBy
+    }
+
+    AbstractImmutable <|-- AbstractEntity
+    AbstractEntity <|-- AbstractTenantAwareEntity
+    AbstractTenantAwareEntity <|-- AbstractTenantAwareAuditable
+    AbstractImmutable <|-- AbstractImmutableAuditable
+    AbstractImmutableAuditable <|-- AbstractTenantAwareImmutableAuditable
+```
+
+- 所有实体使用 Lombok（`@Getter`、`@NoArgsConstructor`、`@SuperBuilder` 按需使用）和 `@MappedSuperclass`。
+- 每个实体有独立的数据库序列，`incrementBy=50`（匹配 Hibernate 默认序列优化）。
+- 审计字段由 `AuditingConfig` 通过 Spring Security `SecurityContextHolder` 自动填充。
+
+**后端 DTO**
+`AbstractImmutableDto` / `AbstractDto` / `AbstractImmutableAuditableDto` / `AbstractAuditableDto` 对应实体层次。`PagedResponse<T>` 统一分页响应（`items` + `totalItems`）。
+
+> 完整集成示例（含 Service + Entity + Repository）见框架维度的 `examples/service-entity.md`。
+
+## 关系映射
+
+| 关系 | 注解 | Fetch 策略 | 使用场景 |
+|------|------|-----------|---------|
+| 多对一 | `@ManyToOne` | LAZY (默认) | 子→父引用 |
+| 一对多 | `@OneToMany` | LAZY (默认) | 父→子集合 |
+| 一对一 | `@OneToOne` | LAZY (显式) | 用户→档案 |
+| 多对多 | `@ManyToMany` | LAZY (显式) | 用户→角色 |
+
+## 查询
+
+### JPQL / Criteria
+
+```java
+@Repository
+public interface UserRepository extends JpaRepository<User, Long> {
+
+  // 方法命名查询
+  List<User> findByDepartmentId(Long departmentId);
+
+  // JPQL
+  @Query("SELECT u FROM User u WHERE u.email LIKE :domain")
+  List<User> findByEmailDomain(@Param("domain") String domain);
+
+  // 更新操作
+  @Modifying
+  @Query("UPDATE User u SET u.active = false WHERE u.lastLogin < :date")
+  int deactivateInactiveUsers(@Param("date") LocalDateTime date);
+}
+```
+
+### EntityGraph (N+1 问题)
+
+```java
+@Entity
+@NamedEntityGraph(name = "User.orders", attributeNodes = @NamedAttributeNode("orders"))
+public class User { ... }
+
+// Repository
+@Query("SELECT u FROM User u WHERE u.id = :id")
+@EntityGraph("User.orders")
+Optional<User> findByIdWithOrders(@Param("id") Long id);
+```
+
+## 最佳实践
+
+- ✅ `open-in-view: false`（避免懒加载异常掩盖性能问题）
+- ✅ `ddl-auto: validate`（生产环境不做自动 DDL）
+- ✅ 使用 `@DynamicUpdate` 优化更新语句
+- ❌ 避免 EAGER fetch（一律使用 LAZY + EntityGraph）
+- ❌ 避免在循环中查询数据库（批量使用 `findAllById` / `IN` 查询）