@deepstorm/cli 0.3.1 → 0.3.2

package/dist/cli.js

@@ -7285,6 +7285,14 @@ function copyFragmentsForSkill(skillId, srcDir, config, registry2, targetDir) {
         );
       }
     }
+    const allFiles = fs10.readdirSync(srcPath);
+    for (const file of allFiles) {
+      if (file === ".DS_Store") continue;
+      if (file === "quick-reference.md") continue;
+      if (file === "examples") continue;
+      if (!file.endsWith(".md")) continue;
+      fs10.cpSync(path6.join(srcPath, file), path6.join(targetDir, file), { force: true });
+    }
   }
 }
 function copyReferencesForSkill(srcDir, targetDir) {

package/dist/skills/reef-style-backend/SKILL.md.tmpl

@@ -122,6 +122,7 @@ deepstorm:
 | `quick-reference.md` | **编码规范速查**。包含核心规则和约定 |
 | `{value}.md` | **维度规范**（如 `spring-boot.md`、`hibernate.md`）。按上方链接加载 |
 | `api-spec.md` | **API 规范**。RESTful 命名、统一响应体、版本策略、OpenAPI |
+| `jackson-polymorphism.md` | **DTO 多态序列化规范**。Jackson `@JsonTypeInfo` + TS Discriminated Union |
 | `dependency-management.md` | **依赖管理规范**。Version Catalog、版本一致性、CVE |
 | `exception-handling.md` | **异常处理深度规范**。异常层次、错误码、全局处理 |
 | `security-redlines.md` | **安全红线**。P0/P1 安全规则及代码示例 |

package/dist/skills/reef-style-backend/fragments/java/api-spec/jackson-polymorphism.md

@@ -0,0 +1,205 @@
+# Jackson 多态序列化与 TypeScript 联合类型
+
+> 适用于后端枚举驱动的图表类型分发 → Jackson `@JsonTypeInfo` 多态 + 前端 discriminated union 的模式。
+> 目标：删除后端 `enum` + `chartType` 字段，改用抽象基类 + `@JsonProperty("type")` 实现自动分发。
+
+```mermaid
+flowchart LR
+    A["后端 Java<br/>@JsonTypeInfo(property = &quot;type&quot;)<br/>@JsonSubTypes"] -->|"JSON 携带<br/>type 判别值"| B["前端 TypeScript<br/>Discriminated Union"]
+    B --> C["@switch(answer.chartView.type)<br/>类型自动窄化"]
+```
+
+---
+
+## 一、问题场景
+
+后端接口返回 JSON 中包含一个"类型"字段，前端根据该类型渲染不同的组件：
+
+```java
+// ❌ 旧模式：枚举 + switch
+public record MetricAnswer(ChartType chartType, ...) {}
+public enum ChartType { METRIC_CARD, LINE_CHART, BAR_CHART, PIE_CHART }
+
+// 前端每次新增类型都需要：
+// 1. 加 enum 值
+// 2. 改 switch
+// 3. 不在同一个地方维护
+```
+
+## 二、推荐模式：Jackson 多态序列化
+
+### 2.1 后端
+
+**步骤 1：定义抽象基类**
+
+```java
+@JsonTypeInfo(use = JsonTypeInfo.Id.SIMPLE_NAME, property = "type")
+@JsonSubTypes({
+    @JsonSubTypes.Type(value = MetricCardView.class, name = "MetricCardView"),
+    @JsonSubTypes.Type(value = LineChartView.class, name = "LineChartView"),
+    @JsonSubTypes.Type(value = BarChartView.class, name = "BarChartView"),
+    @JsonSubTypes.Type(value = PieChartView.class, name = "PieChartView"),
+})
+public abstract class ChartView {}
+```
+
+- `property = "type"` — 序列化时自动在 JSON 中写入 `"type": "MetricCardView"` 等 discriminator
+- `name = "..."` — discriminator 的值，应与 TypeScript 端 literal type 保持一致
+- 新增类型只需：新建子类 + 注册到 `@JsonSubTypes`
+
+**步骤 2：定义子类**
+
+```java
+@JsonInclude(Include.NON_NULL)
+public class MetricCardView extends ChartView {
+    private final String title;
+    private final Object value;
+    private final String unit;
+
+    public MetricCardView(String title, Object value, String unit) {
+        this.title = title;
+        this.value = value;
+        this.unit = unit;
+    }
+    // getters ...
+}
+```
+
+```java
+public class LineChartView extends ChartView {
+    private final String title;
+    @JsonProperty("xAxisName") private final String categoryAxisLabel;
+    @JsonProperty("yAxisName") private final String valueAxisLabel;
+    private final String seriesName;
+    private final List<ChartDataPoint> dataPoints;
+    // constructor + getters ...
+}
+```
+
+> **💡 Import 说明：**
+> - `@JsonTypeInfo`、`@JsonSubTypes`、`@JsonInclude` 来自 `com.fasterxml.jackson.annotation.*`
+> - `@JsonInclude(Include.NON_NULL)` 需导入 `com.fasterxml.jackson.annotation.JsonInclude.Include`
+> - 或在注解中写全路径 `@JsonInclude(JsonInclude.Include.NON_NULL)`，无需额外 import
+
+**步骤 3：替换枚举字段**
+
+```java
+// ❌ 旧
+public record MetricAnswer(ChartType chartType, ...) {}
+
+// ✅ 新
+public record MetricAnswer(ChartView chartView, ...) {}
+```
+
+- 业务逻辑构建时直接 `return new PieChartView(...)` 而非 `return ChartType.PIE_CHART`
+- 删除 `ChartType` 枚举文件
+
+### 2.2 前端（TypeScript）
+
+**步骤 1：定义 Discriminated Union**
+
+```typescript
+interface BaseChartView {
+  type: string;
+}
+
+export interface MetricCardView extends BaseChartView {
+  type: 'MetricCardView';
+  title: string;
+  value: unknown;
+  unit: string | null;
+}
+
+export interface LineChartView extends BaseChartView {
+  type: 'LineChartView';
+  title: string;
+  xAxisName: string;
+  yAxisName: string;
+  seriesName: string;
+  dataPoints: ChartDataPoint[];
+}
+
+export type ChartView = MetricCardView | LineChartView | BarChartView | PieChartView;
+```
+
+**步骤 2：MetricAnswer 中使用联合类型**
+
+```typescript
+export interface MetricAnswer {
+  // ...
+  chartView: ChartView | null;  // ✅ 联合类型自动窄化
+}
+```
+
+**步骤 3：模板中使用 @switch**
+
+```html
+@if (answer.chartView) {
+  @switch (answer.chartView.type) {
+    @case ('MetricCardView') {
+      <app-metric-card [answer]="answer" />
+    }
+    @case ('LineChartView') {
+      <app-line-chart [chartData]="answer.chartData" />
+    }
+  }
+}
+```
+
+## 三、最佳实践
+
+| 要点 | 说明 |
+|------|------|
+| `property = "type"` | discriminator 字段名使用 `"type"`（简短、通用），而非 `"chartType"` |
+| 前后端 value 一致 | `@JsonSubTypes.Type(name = "MetricCardView")` 与 TS `type: 'MetricCardView'` 的值必须一致 |
+| Checkstyle 兼容 | Jackson 字段名与 getter 名可以不同：`@JsonProperty("xAxisName") private String categoryAxisLabel` |
+| 共享 DTO | 子类共享的嵌套类型（如 `ChartDataPoint`）定义为独立 `record` 或类 |
+| 判空安全 | 模板中 `@if (answer.chartView)` 保护空值（如错误响应时 chartView 为 null） |
+| 不删除旧 DTO 层 | `ChartData`、`gridResults`、`singleResults` 等依然存在，chartView 是新增的视图抽象，并非替代所有响应字段 |
+| 删除前确认引用 | 删除旧枚举前 MUST 搜索全项目 Java + TypeScript 引用，确认 0 引用后方可删除 |
+
+## 四、效果对比
+
+| 维度 | 旧模式（Enum） | 新模式（Polymorphism） |
+|------|---------------|----------------------|
+| 新增图表类型 | 枚举 + switch + 前端分支 | 新建子类 + 注册 `@JsonSubTypes` + TS 类型 |
+| JSON 结构 | `{"chartType": "METRIC_CARD", ...}` | `{"chartView": {"type": "MetricCardView", ...}}` |
+| TS 类型安全 | 手动维护 | 自动通过 discriminated union 窄化 |
+| 后端字段数 | chartType + 具体数据各自校验 | chartView 自包含 |
+
+## 五、设计决策说明
+
+### 5.1 `property` 选择 `"type"` 而非 `"chartType"`
+
+| 候选 | 理由 | 结论 |
+|------|------|------|
+| `"type"` | 简短通用，多态基类职责就是描述"是什么类型"，与低代码项目 (`DatasetDto`) 一致 | ✅ |
+| `"chartType"` | 业务含义明确，但限制了基类的可复用性。未来其他多态场景（如 `DataSourceConnector`）需要不同字段名 | ❌ |
+| `"kind"` | Jackson 社区惯例使用 `"type"`，不应引入不必要的差异 | ❌ |
+
+### 5.2 discriminator 策略使用 `SIMPLE_NAME`
+
+| 候选 | 理由 | 结论 |
+|------|------|------|
+| `SIMPLE_NAME` | 子类简名自描述，无需额外常量文件 | ✅ |
+| `CLASS_NAME` | 全限定名过长，JSON 中不可读且暴露包结构 | ❌ |
+| `CUSTOM` | 需要 `@JsonTypeIdResolver`，增加复杂度 | ❌ |
+
+### 5.3 使用 `@JsonSubTypes` 而非自定义序列化器
+
+`@JsonSubTypes` 是 Jackson 原生支持，注解式声明最直观。`@JsonTypeIdResolver` 或自定义 `JsonSerializer` 提供更灵活的控制但需要大量模板代码，适用于更复杂的动态注册场景而非当前已知类型场景。
+
+### 5.4 前端 Discriminated Union 而非 Enum
+
+TypeScript union type + `type` literal 可直接利用 `@switch` 的类型窄化能力，无需手动编写类型守卫函数。这与后端 enum 模式的维护成本形成鲜明对比。
+
+### 5.5 Checkstyle 冲突：`@JsonProperty` 解耦而非禁用规则
+
+| 候选 | 理由 | 结论 |
+|------|------|------|
+| `@JsonProperty("xAxisName") private String categoryAxisLabel` | 字段名合规，getter 合规，JSON 输出保留 `xAxisName` | ✅ |
+| 禁用 Checkstyle `ParameterNameCheck` | 全局禁用降低代码规范性 | ❌ |
+
+### 5.6 Decoder 对象保持 record
+
+如 `MetricAnswer` 是 Java record，不能继承。改造方案为直接替换字段类型（`ChartType chartType` → `ChartView chartView`），record 紧凑语法不受影响。构建逻辑从 `determineChartType()` 改为 `buildChartView()` 并返回具体子类。

package/dist/skills/reef-style-backend/fragments/java/api-spec/quick-reference.md

@@ -146,3 +146,11 @@ MODULE: 2-4 个大写字母标识模块
 - `_100`-`_199`：资源状态错误（不存在、已存在、冲突）
 - `_200`-`_299`：权限错误
 - `_300`-`_399`：系统内部错误
+
+## DTO 多态序列化
+
+当接口中的 DTO 需要根据类型字段分发到不同子类时（如多种图表类型、多种数据源类型），参考 [DTO 多态序列化规范](jackson-polymorphism.md)：
+
+- 后端使用 Jackson `@JsonTypeInfo` + `@JsonSubTypes` 实现多态序列化
+- 前端使用 TypeScript Discriminated Union 对应消费
+- discriminator value 前后端严格一致

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

@@ -62,6 +62,20 @@
   }
   ```
 
+### Lombok 使用规范
+
+| 组件类型 | 必用注解 | 说明 |
+|---------|---------|------|
+| 领域事件 / POJO | `@Getter @AllArgsConstructor` | `private final` 不可变，不手写 getter/constructor（见下方示例） |
+| JPA Entity | `@Getter @NoArgsConstructor(access = PROTECTED)` + `@SuperBuilder`（按需） | 详见 [Hibernate 规范](hibernate.md) |
+| Service / Controller | `@AllArgsConstructor` / `@RequiredArgsConstructor` | 构造函数注入，不用 `@Autowired` 字段注入 |
+| 只读 DTO / Record 替代 | `@Value` | 不可变对象，自动生成 equals/hashCode/toString。Record 更简洁时优先用 record |
+
+**禁止事项：**
+- `@Data` — 自动生成 `@Setter` 破坏不可变性，且 `@EqualsAndHashCode` 在有 JPA 代理时行为不可预期
+- `@Setter` on Entity — 破坏封装，业务状态变更应通过行为方法表达
+- `@Autowired` 字段注入 — 必须用构造函数注入
+
 ### 控件能力声明模式（Capability Pattern）
 
 当实体层次（如 `FormControl` → `TextControl` / `NumberControl` / ...）需要按子类暴露能力时，在抽象基类中声明抽象方法，各子类返回 `true` / `false`：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepstorm/cli",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "DeepStorm CLI — 一键配置项目开发环境",
   "license": "MIT",
   "author": "billkang",