@deepstorm/cli 0.1.0

package/dist/skills/reef-style-backend/fragments/python/sqlalchemy-orm/quick-reference.md

@@ -0,0 +1,91 @@
+# SQLAlchemy ORM 使用规范（v2.0+）
+
+## 异步会话管理
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker, AsyncSession
+
+# ✅ 好：异步引擎 + sessionmaker
+engine = create_async_engine(
+    "postgresql+asyncpg://user:pass@localhost/db",
+    echo=False,
+    pool_size=10,
+    max_overflow=20,
+)
+async_session = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+
+# ✅ 好：在 Service 中作为依赖
+class UserService:
+    def __init__(self, db: AsyncSession = Depends(get_async_session)):
+        self.db = db
+
+    async def get_user(self, user_id: int) -> User | None:
+        stmt = select(User).where(User.id == user_id)
+        result = await self.db.execute(stmt)
+        return result.scalar_one_or_none()
+```
+
+**规范：**
+- **强制**使用 `AsyncSession` + `async_sessionmaker`
+- 禁止同步 `Session` 或 `scoped_session`
+- `expire_on_commit=False` 避免 commit 后属性不可访问
+- 不要在 Router 中直接操作 `db`，放到 Service 层
+
+## 模型定义（v2.0 style）
+
+```python
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from sqlalchemy import String, Integer, DateTime, func
+
+class Base(DeclarativeBase):
+    pass
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    name: Mapped[str] = mapped_column(String(100), nullable=False)
+    email: Mapped[str] = mapped_column(String(255), unique=True, nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now())
+    updated_at: Mapped[datetime] = mapped_column(DateTime, server_default=func.now(), onupdate=func.now())
+```
+
+**规范：**
+- **强制**使用 `Mapped` + `mapped_column`（v2.0 style）
+- 禁止旧版 `Column`(name, Type) 写法
+- 所有模型继承共享 `Base`
+- 必要字段声明 `nullable=False`
+
+## 关联关系预加载（防 N+1）
+
+```python
+from sqlalchemy.orm import selectinload, joinedload
+
+# ✅ 好：selectinload 预加载
+stmt = select(Post).options(selectinload(Post.author)).where(Post.published == True)
+result = await db.execute(stmt)
+
+# ✅ 好：joinedload 用于单条查询
+stmt = select(Post).options(joinedload(Post.author)).where(Post.id == post_id)
+```
+
+**规范：**
+- 批量列表查询用 `selectinload()`（发出额外 IN 查询，对列表友好）
+- 单条查询用 `joinedload()`（JOIN 一次）
+- **禁止**在循环中逐条访问关联属性
+
+## 查询最佳实践
+
+```python
+# ✅ 好：参数化查询（防 SQL 注入）
+stmt = select(User).where(User.email == email)
+
+# ❌ 坏：⚠️ 禁止裸 SQL 拼接
+text(f"SELECT * FROM users WHERE email = '{email}'")   # ← SQL 注入风险
+
+# ✅ 好：批量更新
+stmt = update(User).where(User.is_active == False).values(status="inactive")
+await db.execute(stmt)
+await db.commit()
+```

package/dist/skills/reef-style-backend/variants/java/examples/code-wrapping.md

@@ -0,0 +1,227 @@
+# 后端代码折行示例（100 列限制）
+
+Checkstyle 配置行宽 110，折行目标 100 列。
+
+## 方法签名
+
+一行放得下就一行，放不下则每个参数独立一行（4 格缩进）。不与「同行放多个参数」的混合分组混淆：
+
+```java
+public FormDetailsDto getForm(Long appId, Long formId) { ... }
+
+public FormDetailsDto publishForm(
+    Long appId, Long formId, PublishFormRequest request) { ... }
+
+public FormResponseDto updateFormResponse(
+    @PathVariable Long appId,
+    @PathVariable Long formId,
+    @PathVariable Long responseId,
+    @RequestBody UpdateFormResponseRequest request,
+    @AuthenticationPrincipal User user) { ... }
+```
+
+## Stream 管道
+
+每个算子一行，行首 `.`，4 格缩进（相对方法体 8 格）：
+
+```java
+var forms = formRepository.findAllByAppId(appId.getId()).stream()
+    .map(FormMapper.INSTANCE::mapToSummary)
+    .toList();
+
+var options = response.getRecords().stream()
+    .limit(FormExcelUtils.DATASET_PAGE_SIZE)
+    .collect(Collectors.toMap(
+        record -> String.valueOf(record.get(labelField)),
+        record -> new Option(...),
+        (existing, _) -> existing));
+```
+
+## Builder 模式
+
+每个 `.method()` 一行，4 格缩进（相对方法体 8 格）：
+
+```java
+var templateContext = TemplateContext.builder()
+    .context(formulaContext)
+    .urlQueryParams(request.getUrlQueryParams())
+    .build();
+
+var csvMapper = CsvMapper.builder()
+    .enable(CsvParser.Feature.TRIM_SPACES)
+    .addModule(new SimpleModule().addDeserializer(
+        boolean.class, new CsvBooleanDeserializer()))
+    .build();
+```
+
+## 注解
+
+单属性一行。多属性 `uses` 每个一行：
+
+```java
+@Pattern(
+    regexp = "[a-zA-Z_][a-zA-Z0-9_]*",
+    message = "字段名称只能包含字母、数字和下划线")
+
+@Mapper(
+    config = MapStructConfig.class,
+    uses = { FormRevisionMapper.class, FormItemMapper.class, PrintConfigMapper.class })
+```
+
+## Constructor / new 调用
+
+参数放不下则每行一个（4 格缩进）：
+
+```java
+var user = new InternalUser(
+    request.getUsername(),
+    passwordEncoder.encode(request.getPassword()),
+    request.getFullName(),
+    request.getRole());
+
+var items = importedItems.stream()
+    .map(item -> new DictionaryItem(
+        null, item.getCode(), item.getValue(), item.isDisabled(), dict.getId()))
+    .toList();
+```
+
+## 方法调用参数换行
+
+所有参数在 100 列内能一行放完则一行，放不完则每个参数独立一行。不与 Google 风格的「混合分组」（几个参数一行、最后一个另起一行）混淆：
+
+```java
+// ✓ 正确：参数少，一行放得下
+var result = MetricAnswer.found("急诊人次", "C001", "急诊人次", 1500, "人次", dateRange);
+
+// ✓ 正确：参数较多且一行放不下，每个参数独立一行
+var result = MetricAnswer.foundWithGrid(
+    query.metricName(),
+    matched.code(),
+    name,
+    apiGridResults,
+    apiLastGridResults,
+    apiChainGridResults,
+    dateRange,
+    chartType,
+    unresolvedDimensions);
+
+// ✓ 正确：静态工厂方法同理
+return MetricAnswer.foundWithComparison(
+    query.metricName(),
+    matched.code(),
+    name,
+    result.getValue(),
+    result.getUnit(),
+    lastResults,
+    chainResults,
+    dateRange,
+    chartType);
+
+// ✗ 错误：混合分组，一行的结尾参数和后续参数混在一起
+return MetricAnswer.foundWithGrid(
+    query.metricName(), matched.code(), name,      // ← 混在同一行
+    apiGridResults, apiLastGridResults, apiChainGridResults,  // ← 混在同一行
+    dateRange, chartType);                           // ← 混在同一行
+```
+
+## `new ResponseEntity<>()` 换行 / `if` 条件
+
+```java
+return new ResponseEntity<>(
+    new CustomError(Status.NOT_FOUND, ex.getMessage(), ex.getResourceInfo()),
+    HttpStatus.NOT_FOUND);
+
+if (control instanceof ChoiceControl choiceControl
+    && choiceControl.getOptionsSource() instanceof DatasetOptionsSource source) {
+```
+
+## `.orElseThrow()` / `formatted()`
+
+```java
+return repository.findByIdAndAppId(id, appId).orElseThrow(
+    () -> new NotFoundException("资源不存在", new ResourceInfo("MyEntity", id)));
+
+return "jdbc:oracle:thin:@//%s:%d/%s?connectTimeout=%d".formatted(
+    getHost(), getPort(),
+    URLEncoder.encode(getDbName(), StandardCharsets.UTF_8),
+    TIMEOUT_SECONDS * 1000);
+```
+
+## Try-with-resources / Lambda
+
+```java
+try (var inputStream = file.getInputStream();
+    var reader = new InputStreamReader(inputStream, StandardCharsets.UTF_8)) {
+  ...
+}
+
+Function<FieldAssignment, TextValue> valueMapper =
+    assignment -> new TextValue(TemplateEngines.SIMPLE.evaluate(...));
+
+components.forEach(component -> {
+  if (!existingKeys.add(component.getKey())) {
+    throw new InvalidArgumentException("key 必须唯一");
+  }
+});
+```
+
+## 链式调用（MockMvc / Mockito）
+
+```java
+var result = mvc.perform(get("/api/v1/apps")
+        .contentType(MediaType.APPLICATION_JSON))
+    .andExpect(status().isOk())
+    .andReturn();
+
+when(service.publishForm(
+    eq(1L), eq(2L), any(PublishFormRequest.class)))
+    .thenReturn(FormMapper.INSTANCE.mapToDetails(form));
+```
+
+## Text Block（三引号多行字符串）
+
+Java 15+ 的 Text Block 用于嵌入 JSON / SQL / XML / 模板等 DSL。缩进规则依赖 `closing """` 的位置：
+
+```java
+// ✅ opening """ 后直接换行，内容相对 opening 行缩进 4 格
+// ✅ closing """ 决定 stripIndent() 的公共缩进基线
+var json = """
+    {
+      "name": "example",
+      "value": 42,
+      "items": [1, 2, 3]
+    }
+    """;
+
+// ✅ 嵌入 SQL：closing """ 与 SQL 内容的公共缩进最左列对齐
+var sql = """
+    SELECT u.id, u.name, r.role_name
+    FROM users u
+    JOIN user_roles r ON r.user_id = u.id
+    WHERE u.status = 'ACTIVE'
+    ORDER BY u.name
+    """;
+
+// ✅ 配合 formatted() 做变量替换
+var message = """
+    Hello %s,
+    Your order #%d has been confirmed.
+    """.formatted(userName, orderId);
+
+// ✅ 空行可用 \s 占位避免 stripIndent 清空：
+var json = """
+    {
+      "title": "test",
+    \s
+      "description": ""
+    }
+    """;
+```
+
+**规范：**
+- `"""` 必须后跟换行，**禁止在同行放内容**
+- `closing """` 的缩进决定公共缩进基线，放在最后一行内容之下，与之缩进对齐
+- 禁止 text block 与 `+` 拼接混用；需要变量替换统一用 `formatted()`
+- 短字符串（≤ 100 列单行）不使用 text block，直接使用普通字符串
+- `\s` 用于显式保留 text block 中的空行（避免 `stripIndent()` 把空行清空）
+```

package/dist/skills/reef-style-backend/variants/java/examples/contributor-pattern.md

@@ -0,0 +1,97 @@
+# Reference Contributor 模式
+
+当删除资源前需要查询哪些其他资源引用了它时，使用 Contributor 模式。
+
+## 定义接口
+
+在被引用资源所属模块中定义 `@FunctionalInterface`：
+
+```java
+// data/service/DataObjectReferenceContributor.java
+@FunctionalInterface
+public interface DataObjectReferenceContributor {
+  List<ResourceSummary> findReferences(Long dataObjectId);
+}
+```
+
+统一返回值（`base/dto/` 中定义）：
+
+```java
+public record ResourceSummary(String type, Long id, Long name) {}
+public record ListResourceReferencesResponse(List<ResourceSummary> references) {}
+```
+
+## 实现贡献者
+
+引用方模块实现接口为 `@Component`，Spring 自动收集：
+
+```java
+@Component
+@RequiredArgsConstructor
+public class PageDataObjectReferenceContributor
+    implements DataObjectReferenceContributor {
+  private final PageRepository repository;
+
+  @Override
+  public List<ResourceSummary> findReferences(Long dataObjectId) {
+    return repository
+        .findAllByTableComponentDataObjectId(dataObjectId)
+        .stream()
+        .map(page -> new ResourceSummary("Page", page.getId(), page.getName()))
+        .toList();
+  }
+}
+```
+
+多途径查找时用 `Stream.of(...).flatMap(List::stream).distinct()` 去重合并：
+
+```java
+@Override
+public List<ResourceSummary> findReferences(Long datasetId) {
+  var streams = Stream.of(
+      repository.findAllByChartDatasetId(datasetId),
+      repository.findAllByTableComponentDatasetId(datasetId));
+  return streams
+      .flatMap(List::stream)
+      .map(entity -> new ResourceSummary("Type", entity.getId(), entity.getName()))
+      .distinct()
+      .toList();
+}
+```
+
+## Repository 查询
+
+继承层次中的子类型查询使用 `TREAT` 语法：
+
+```java
+@Query(
+    """
+    SELECT DISTINCT p FROM Page p JOIN p.components c
+    WHERE TREAT(c AS TableComponent).customDataConfig.dataObjectId = :dataObjectId
+    """)
+List<Page> findAllByTableComponentDataObjectId(Long dataObjectId);
+```
+
+## 聚合查询（Owner Service）
+
+```java
+private final List<DataObjectReferenceContributor> referenceContributors;
+
+public ListResourceReferencesResponse listDataObjectReferences(Long appId, Long dataObjectId) {
+  getDataObjectEntity(appId, dataObjectId); // 验证存在 + 多租户
+  var references = referenceContributors.stream()
+      .flatMap(contributor -> contributor.findReferences(dataObjectId).stream())
+      .toList();
+  return new ListResourceReferencesResponse(references);
+}
+```
+
+## REST 端点
+
+```java
+@GetMapping("/{objectId}/references")
+public ListResourceReferencesResponse listDataObjectReferences(
+    @PathVariable Long appId, @PathVariable Long objectId) {
+  return service.listDataObjectReferences(appId, objectId);
+}
+```

package/dist/skills/reef-style-backend/variants/java/quick-reference.md

@@ -0,0 +1,117 @@
+# 后端编码快速参考
+
+按需加载。仅当你需要编写对应组件类型时阅读相关章节。
+
+> 已安装子维度的规范，通过该维度的 `{value}.md` 文件阅读。本页只包含语言通用的核心规范。
+>
+> **跨维度规范（适用所有后端代码）：**
+> - [API 规范](api-spec.md) — RESTful 命名、统一响应体、OpenAPI、版本策略
+> - [依赖管理规范](dependency-management.md) — Version Catalog、版本一致性、CVE
+> - [异常处理深度规范](exception-handling.md) — 异常层次、错误码、全局处理
+> - [安全红线](security-redlines.md) — P0/P1 安全规则（必须遵守）
+
+## 速查
+
+| 场景 | 决策 |
+| --- | --- |
+| 字符串格式化 | 用 `formatted()`，不用 `+` 拼接 |
+| 类型分发 | 用多态，不用 `instanceof` 链 |
+| 控件能力查询 | 基类声明 `abstract boolean supportsXxx()`，子类按能力返回 `true/false` |
+| 领域事件 / POJO | `@Getter @AllArgsConstructor`，不手写 getter/constructor |
+| 参数顺序 | `appId` → 父级 ID → 自身 ID → name/描述 |
+| 字段注释 | Model/Entity/Event 加 `/** */`，DTO/Record 不加 |
+| 日志实体 | 继承 `LogEntry`（SINGLE_TABLE），不直接继承基类 |
+| 弃用 API | 编译警告中的 `@Deprecated` API 在同一次 PR 中替换为新 API |
+| 多行字符串 | 用 Text Block `"""..."""` + `formatted()` 嵌入 JSON/SQL/XML，禁止 `+` 拼接；详见 [code-wrapping.md](examples/code-wrapping.md) |
+
+## 代码风格
+
+### 通用约定
+
+- 变量命名有意义，禁止单字母（循环计数器 `i`/`j`/`k` 除外）
+- 局部变量用 `var`
+- 字符串格式化用 `formatted()`，不用 `+` 拼接
+- 多态替代 `instanceof` 链做类型分发
+- 100 列折行，运算符/`.`/`::` 放行首。适用范围如下：
+  - **代码结构**（方法调用、签名、表达式）严格执行 100 列
+  - **Javadoc / 注释文本**以可读性优先，不硬断中文句子；仅单行 `/** ... */` 标记超长时拆成多行
+- **方法调用参数换行**：所有参数能在列宽内一行放完则一行，放不完则每个参数独立一行（不混合分组）；详见 [code-wrapping.md](examples/code-wrapping.md)「方法调用参数换行」
+- 类内字段按用途逻辑分组，组间空行分隔，**禁止使用 `// ======`（或其他重复符号装饰）做视觉分隔线注释**。例如应避免 `// ========== 维度信息 ==========` 这种写法
+- 注释与代码逻辑块之间：相邻的两个 `// 注释 + 代码块` 之间用空行分隔，使每个逻辑块保持独立。
+  ```java
+  // ✅ 正确：逻辑块之间有空行
+  // PROPORTION → 饼图
+  if (queryIntent == QueryIntent.PROPORTION) {
+    return ChartType.PIE_CHART;
+  }
+
+  // GROUP_BY → 柱状图
+  if (queryIntent == QueryIntent.GROUP_BY) {
+    return ChartType.BAR_CHART;
+  }
+  ```
+  ```java
+  // ❌ 错误：缺少分隔空行，两个逻辑块粘连
+  // PROPORTION → 饼图
+  if (queryIntent == QueryIntent.PROPORTION) {
+    return ChartType.PIE_CHART;
+  }
+  // GROUP_BY → 柱状图
+  if (queryIntent == QueryIntent.GROUP_BY) {
+    return ChartType.BAR_CHART;
+  }
+  ```
+
+### 控件能力声明模式（Capability Pattern）
+
+当实体层次（如 `FormControl` → `TextControl` / `NumberControl` / ...）需要按子类暴露能力时，在抽象基类中声明抽象方法，各子类返回 `true` / `false`：
+
+```java
+// FormControl.java — 基类声明
+public abstract boolean supportsImporting();
+
+// TextControl.java — 子类声明能力
+@Override public boolean supportsImporting() { return true; }
+
+// 其他子类按需返回 false 或 true
+@Override public boolean supportsImporting() { return false; }
+```
+
+**适用场景：** 基类有多个子类，且某个操作只在部分子类上有意义。
+**替代方案：** 用 `instanceof` 判断 → ✗ 不推荐，违反开闭原则，每加一个子类就要改判断链。
+**优势：** 开闭原则 — 新增子类只需在自己的类中覆盖方法；新增能力只需在基类加方法 + 各子类实现。
+
+## 字段注释规则
+
+| 文件类型 | 需要 `/** */` 字段注释 |
+|---------|----------------------|
+| Model / Entity / Event | ✓ 是 |
+| DTO / Record | ✗ 否 |
+
+## 领域事件 / POJO
+
+### 规则
+
+- 使用 Lombok `@Getter @AllArgsConstructor`，不手写 getter/constructor
+- `private final` 字段，保持不可变
+- 参数顺序：`appId` → 父级 ID → 自身 ID → name/描述
+- 事件配合 `@EventListener` 实现解耦，Service 层 `publishEvent(event)` 而不是直接调用 Repository
+
+### 示例
+
+```java
+@Getter @AllArgsConstructor
+public class FormDeletedEvent {
+  private final Long appId;
+  private final Long formId;
+  private final String formTitle;
+}
+```
+
+## 常见坑
+
+| 场景 | 问题 | 正确做法 |
+|------|------|---------|
+| `instanceof` 分发 | Service 层用 `instanceof` 链判断所有子类型 | 优先在实体/领域模型中用多态 |
+| 控件能力硬编码 | 用 `if (control instanceof TextControl)` 判断是否支持某能力 | 基类加 `abstract boolean supportsXxx()`，子类按能力覆盖 |
+| 弃用 API | 编译出现 `@Deprecated` 警告但不处理 | 同一次 PR 中替换为新 API |

package/dist/skills/reef-style-backend/variants/python/examples/crud-router.md

@@ -0,0 +1,71 @@
+# 示例：FastAPI CRUD Router
+
+```python
+# app/api/v1/users.py
+from fastapi import APIRouter, Depends, Query, HTTPException
+from app.schemas.users import (
+    CreateUserRequest,
+    UpdateUserRequest,
+    UserResponse,
+    UserListResponse,
+)
+from app.services.users import UserService
+
+router = APIRouter(prefix="/api/v1/users", tags=["users"])
+
+
+@router.get("/", response_model=UserListResponse)
+async def list_users(
+    skip: int = Query(0, ge=0),
+    limit: int = Query(20, ge=1, le=100),
+    user_service: UserService = Depends(),
+):
+    """获取用户列表"""
+    users, total = await user_service.list_users(skip=skip, limit=limit)
+    return UserListResponse(items=users, total=total, skip=skip, limit=limit)
+
+
+@router.get("/{user_id}", response_model=UserResponse)
+async def get_user(
+    user_id: int,
+    user_service: UserService = Depends(),
+):
+    """获取单个用户"""
+    user = await user_service.get_user(user_id)
+    if user is None:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user
+
+
+@router.post("/", response_model=UserResponse, status_code=201)
+async def create_user(
+    request: CreateUserRequest,
+    user_service: UserService = Depends(),
+):
+    """创建用户"""
+    return await user_service.create_user(request)
+
+
+@router.put("/{user_id}", response_model=UserResponse)
+async def update_user(
+    user_id: int,
+    request: UpdateUserRequest,
+    user_service: UserService = Depends(),
+):
+    """更新用户"""
+    user = await user_service.update_user(user_id, request)
+    if user is None:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user
+
+
+@router.delete("/{user_id}", status_code=204)
+async def delete_user(
+    user_id: int,
+    user_service: UserService = Depends(),
+):
+    """删除用户"""
+    deleted = await user_service.delete_user(user_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail="User not found")
+```

package/dist/skills/reef-style-backend/variants/python/examples/pydantic-schema.md

@@ -0,0 +1,45 @@
+# 示例：Pydantic Schema
+
+```python
+# app/schemas/user.py
+from datetime import datetime
+from pydantic import BaseModel, Field, EmailStr
+from typing import Optional
+from app.models.user import UserRole
+
+
+# ── Request Schemas ──
+
+class CreateUserRequest(BaseModel):
+    name: str = Field(..., min_length=1, max_length=100, description="用户名")
+    email: EmailStr = Field(..., description="邮箱")
+    password: str = Field(..., min_length=8, max_length=128, description="密码")
+    role: UserRole = Field(default=UserRole.USER, description="角色")
+
+
+class UpdateUserRequest(BaseModel):
+    name: Optional[str] = Field(None, min_length=1, max_length=100)
+    email: Optional[EmailStr] = None
+    role: Optional[UserRole] = None
+
+
+# ── Response Schemas ──
+
+class UserResponse(BaseModel):
+    id: int
+    name: str
+    email: str
+    role: UserRole
+    is_active: bool
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}  # ORM 模式
+
+
+class UserListResponse(BaseModel):
+    items: list[UserResponse]
+    total: int
+    skip: int
+    limit: int
+```