@deepstorm/cli 0.1.0

package/dist/skills/reef-style-frontend/variants/angular/examples/entity-types.md

@@ -0,0 +1,100 @@
+# 前端实体/类型示例
+
+## 1. 实体接口层次
+
+实体接口镜像后端实体层次，定义在 `shared/base.ts`：
+
+```typescript
+export interface ImmutableEntity { id: number; createdAt: LocalDateTime; }
+export interface Entity extends ImmutableEntity { lastModifiedAt: LocalDateTime; }
+export interface ImmutableAuditable<T> extends ImmutableEntity { createdBy: T; }
+export interface Auditable<T> extends Entity { createdBy: T; lastModifiedBy: T; }
+
+// UserSummary（审计字段常用类型）
+export interface UserSummary { id: number; username: string; fullName: string; }
+```
+
+> `LocalDateTime` 来自 `@js-joda/core`，配合 `iso8601Interceptor` 自动从 JSON 反序列化。
+
+## 2. 实体定义示例
+
+```typescript
+// 可变实体（extends Entity）
+export interface FormSummary extends Entity {
+  title: string;
+  approvalEnabled: boolean;
+  printConfig: PrintConfig | null;
+  actions: FormAction[];
+}
+
+// 可审计可变实体（extends Auditable<UserSummary>）
+export interface FormResponse extends Auditable<UserSummary> {
+  answers: Partial<Record<string, Answer>>;
+  approvalState: ApprovalState | null;
+  status: 'NOT_STARTED' | 'RUNNING' | 'DONE' | 'FAILED';
+  formRevisionId: number;
+}
+```
+
+## 3. 分页响应
+
+```typescript
+export interface PageRequest { page: number; size: number; sort: string; }
+export interface PagedResponse<T extends ImmutableEntity> {
+  items: T[];
+  totalItems: number;
+}
+
+// 将 PrimeNG p-table (lazy) 的 TableLazyLoadEvent 转换为后端分页参数
+export function toPageRequest(event: TableLazyLoadEvent): PageRequest {
+  const { first, rows, sortField, sortOrder } = event;
+  return {
+    page: first! / rows!,
+    size: rows!,
+    sort: `${Array.isArray(sortField) ? sortField.join(',') : sortField},${sortOrder === -1 ? 'desc' : 'asc'}`,
+  };
+}
+
+// Service 中使用
+@Injectable({ providedIn: 'root' })
+export class DataObjectInstanceService {
+  private readonly http = inject(HttpClient);
+
+  list(objectId: signal<number | undefined>) {
+    return httpResource<PagedResponse<DataObjectInstance>>(() => {
+      const id = objectId();
+      return id !== undefined
+        ? `/api/v1/apps/${this.appService.appId()}/objects/${id}/instances`
+        : undefined;
+    });
+  }
+}
+```
+
+## 4. Discriminated Union 模式
+
+```typescript
+// 用户类型（字符串字面量 discrimination）
+interface BaseUser extends Entity {
+  type: string; username: string; fullName: string; role: Role; disabled: boolean;
+}
+export interface InternalUser extends BaseUser { type: 'InternalUser'; }
+export interface CdyxUser extends BaseUser { type: 'CdyxUser'; }
+export type User = InternalUser | CdyxUser;
+
+// 字段值类型（按 type 字段分发）
+export type FieldValue = TextValue | NumberValue | BooleanValue;
+export interface TextValue { type: 'text'; value: string | null; }
+export interface NumberValue { type: 'number'; value: number | null; }
+```
+
+## 5. 关键规则
+
+| 规则 | 说明 |
+|------|------|
+| **interface，不是 class** | 实体全是 `interface`，没有 `class` |
+| **类型参数 `T`** | 审计字段的 `T` 通常是 `UserSummary` |
+| **必要字段** | 字段不设可选（`?`），后端保证返回 |
+| **枚举用 union** | 状态字段用 literal union，不用 TypeScript `enum` |
+| **字段注释** | Entity/接口字段加 `/** */` 注释；简单的 DTO 不加 |
+| **参数顺序** | `appId` → 父级 ID → 自身 ID → name/描述 |

package/dist/skills/reef-style-frontend/variants/angular/examples/forms-layer.md

@@ -0,0 +1,119 @@
+# 前端 Signal Forms 示例
+
+---
+
+## 1. 标准 Signal Forms 组件（Dialog CRUD）
+
+```typescript
+import { form, FormField, FormRoot, required } from '@angular/forms/signals';
+
+@Component({
+  selector: 'app-crud-dialog',
+  imports: [Button, Dialog, FormField, FormRoot, InputText],
+  template: `
+    <p-button label="创建" (onClick)="onCreate()" />
+    <p-dialog
+      [(visible)]="visible"
+      [header]="isEditing() ? '编辑' : '创建'"
+      modal
+      (onHide)="onHide()"
+    >
+      <form [formRoot]="form" (submit)="submitted.set(true)">
+        <input
+          pInputText
+          [formField]="form.name"
+          [pInvalid]="submitted() && form.name().invalid()"
+        />
+        @if (submitted() && form.name().invalid()) {
+          <app-error-messages [errors]="form.name().errors()" />
+        }
+        <p-button type="submit" label="保存" />
+      </form>
+    </p-dialog>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class CrudDialogComponent {
+  private readonly messageService = inject(MessageService);
+
+  readonly visible = signal(false);
+  readonly isEditing = signal(false);
+  readonly submitted = signal(false);
+
+  readonly form = form(signal({ name: '' }), (path) => {
+    required(path.name, { message: '名称不能为空' });
+  }, {
+    submission: { action: async () => {
+      await lastValueFrom(this.service.create(this.form().value()));
+      this.messageService.add({ severity: 'success', summary: '创建成功' });
+      this.visible.set(false);
+    }},
+  });
+
+  onCreate() {
+    this.isEditing.set(false);
+    this.form().reset({ name: '' });
+    this.visible.set(true);
+  }
+
+  onEdit(item: Item) {
+    this.isEditing.set(true);
+    this.form().reset({ name: item.name });
+    this.visible.set(true);
+  }
+
+  onHide() {
+    this.submitted.set(false);
+    this.visible.set(false);
+  }
+}
+```
+
+---
+
+## 2. 复合表单模型（条件隐藏/禁用）
+
+```typescript
+interface FormModel {
+  type: 'mysql' | 'postgres' | 'http';
+  name: string;
+  db: { host: string; port: number | null };
+  http: { baseUrl: string };
+}
+
+readonly mode = signal<'create' | 'edit'>('create');
+
+readonly form = form(signal(domainModelToFormModel(null)), (path) => {
+  required(path.name, { message: '名称不能为空' });
+  disabled(path.type, () => this.mode() === 'edit');
+  hidden(path.db, ({ valueOf }) => valueOf(path.type) === 'http');
+  hidden(path.http, ({ valueOf }) => valueOf(path.type) !== 'http');
+  required(path.http.baseUrl, { message: '基础 URL 不能为空' });
+});
+```
+
+---
+
+## 3. Signal Forms 异步提交（带 loading）
+
+```typescript
+readonly form = form(signal(EMPTY_USER), (path) => {
+  required(path.username, { message: '用户名不能为空' });
+}, {
+  submission: {
+    action: async () => {
+      this.loading.set(true);
+      try {
+        const user = await lastValueFrom(
+          this.authService.createUser(this.form().value())
+        );
+        this.messageService.add({ severity: 'success', summary: '创建成功' });
+        this.visible.set(false);
+        this.users.update(users => [...users, user]);
+      } finally {
+        this.loading.set(false);
+      }
+    },
+  },
+});
+```

package/dist/skills/reef-style-frontend/variants/angular/examples/service-routing.md

@@ -0,0 +1,95 @@
+# 前端 Service 层与路由示例
+
+## 1. httpResource 服务层封装
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class ItemService {
+  private readonly http = inject(HttpClient);
+
+  private readonly itemsResource = httpResource<ListResponse>(() => '/api/v1/items');
+
+  // 只读暴露给组件
+  readonly items = computed<Item[]>(() => this.itemsResource.value()?.items ?? []);
+  readonly loading = this.itemsResource.isLoading;
+
+  /** 写操作：HttpClient + finalize reload */
+  create(request: { name: string }) {
+    return this.http.post<Item>('/api/v1/items', request).pipe(
+      finalize(() => this.itemsResource.reload()),
+    );
+  }
+
+  delete(id: number) {
+    return this.http.delete(`/api/v1/items/${id}`).pipe(
+      finalize(() => this.itemsResource.reload()),
+    );
+  }
+}
+```
+
+## 2. 模板控制流
+
+```angular2html
+@for (item of items(); track item.id) {
+  @switch (item.type) {
+    @case ('TextControl') {
+      @let label = item.label || '未命名';
+      <app-text-control [label]="label" />
+    }
+    @case ('ChoiceControl') {
+      <app-select [options]="item.options" />
+    }
+    @default {
+      <div>未知控件: {{ item.type }}</div>
+    }
+  }
+}
+```
+
+## 3. 路由配置模式
+
+```typescript
+export const routes: Routes = [
+  {
+    path: '',
+    component: DefaultLayoutComponent,
+    canActivate: [authGuard],
+    children: [
+      {
+        path: 'dashboard',
+        title: '仪表盘',
+        loadComponent: () => import('./dashboard/dashboard.component').then(m => m.DashboardComponent),
+      },
+    ],
+  },
+  {
+    path: 'admin',
+    component: DefaultLayoutComponent,
+    canActivate: [authGuard],
+    data: { requiredAuthority: 'ADMIN' },
+    children: [
+      {
+        path: 'users',
+        title: '用户管理',
+        loadComponent: () => import('./admin/user-list/user-list.component').then(m => m.UserListComponent),
+      },
+      {
+        path: 'role-mappings',
+        canActivate: [authGuard],
+        data: { requiredAuthority: 'ADMIN', requireRootTenant: true },
+        loadComponent: () => import('./admin/role-mappings/role-mappings.component').then(m => m.RoleMappingsComponent),
+      },
+    ],
+  },
+  {
+    path: 'login',
+    loadComponent: () => import('./login/login.component').then(m => m.LoginComponent),
+    canActivate: [authGuard],
+  },
+  {
+    path: '**',
+    loadComponent: () => import('./page-not-found/page-not-found.component').then(m => m.PageNotFoundComponent),
+  },
+];
+```

package/dist/skills/reef-style-frontend/variants/angular/quick-reference.md

@@ -0,0 +1,100 @@
+# 前端编码快速参考
+
+按需加载。仅当你需要编写对应组件类型时阅读相关章节。
+
+> **完整示例代码见 `examples/` 目录。** 已安装子维度的规范，通过该维度的 `{value}.md` 文件阅读。
+
+## 速查
+
+| 场景 | 决策 |
+| --- | --- |
+| 新建组件 | Standalone + OnPush + inline template + inject() |
+| 新建表单 | Signal Forms（`form()`），非 Reactive Forms |
+| 读数据 | `httpResource()` |
+| 写数据 | `HttpClient` + `finalize(() => resource.reload())` |
+| Service 职责 | 只负责网络请求，不管理 UI 状态 |
+| 路由 | `loadComponent` 懒加载 |
+
+## 新建组件
+
+```typescript
+@Component({
+  selector: 'app-example',
+  imports: [/* 显式导入 */],
+  template: `...`,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  host: { class: 'flex flex-col gap-2 p-4' },
+})
+export class ExampleComponent {
+  private readonly router = inject(Router);
+  submitted = output<number>();
+}
+```
+
+| 规则 | 要求 |
+| --- | --- |
+| Standalone | 禁止 NgModule，`imports: []` 显式导入 |
+| `OnPush` | 模板中所有输入 immutable |
+| `inject()` | 禁止构造函数注入 |
+| `output()` | 禁止 `@Output()` + `EventEmitter` |
+| `host` | 容器样式用 `host: { class: '...' }`，不包裹 `<div>` |
+
+## Signal 状态
+
+响应式状态用 `signal()` / `computed()` / `linkedSignal()`；私有 signal 对外暴露用 `asReadonly()`；模板中必须调用 signal（写 `signal()`，不要写 `signal`）。
+
+### Signal Forms（新表单首选）
+
+使用 `@angular/forms/signals` 的 `form()`，不再新增 `FormGroup`/`FormBuilder`：
+
+```typescript
+readonly form = form(signal({ name: '', email: '' }), (path) => {
+  required(path.name);
+  email(path.email);
+}, {
+  submission: { action: async () => {
+    await lastValueFrom(this.service.create(this.form().value()));
+  }},
+});
+```
+
+## HTTP / Service
+
+- **读请求**：`httpResource()` — URL 函数返回 `undefined` 时跳过请求
+- **写请求**：`HttpClient` + `finalize(() => resource.reload())`
+- **Service 职责**：只做网络请求，不管理 UI 状态
+- **Blob 下载错误处理**：`responseType: 'blob'` 时后端 JSON 错误被包装为 Blob，需在 error handler 中解析
+- **API 路径**：基础前缀 `/api/v1/`；自定义方法用 AIP-136 冒号语法
+
+## 错误处理
+
+- `errorHandlingInterceptor` 已全局注册，统一显示 toast；组件层不额外 `catchError`
+- `iso8601Interceptor`：自动将 ISO 8601 字符串转换为 `@js-joda/core` 类型
+- 401 由 auth guard 处理，拦截器跳过
+- 表单验证错误用 `<app-error-messages>` 组件渲染
+
+## 路由
+
+- 所有功能组件用 `loadComponent` 懒加载
+- 权限通过路由 `data.requiredAuthority` / `data.requireRootTenant` 控制
+- `authGuard` 在每个受保护路由独立注册，不在根路由全局注册
+
+## 代码风格
+
+- 控制流语句必须使用大括号，禁止无大括号的早期返回
+- 代码折行规则（90 列限制）详见 `examples/code-wrapping.md`
+
+## 前端实体类型
+
+实体接口镜像后端实体层次，定义在 `shared/base.ts`：`ImmutableEntity` → `Entity` → `Auditable<T>` / `ImmutableAuditable<T>`。完整定义、分页响应、Discriminated Union 模式见 `examples/entity-types.md`。
+
+## 常见坑
+
+| 场景 | 问题 | 正确做法 |
+|------|------|---------|
+| Blob 下载 | 后端返回 JSON 时 err.error 被包装为 Blob | `err.error.text().then(text => JSON.parse(text))` |
+| httpResource 初始化 | URL 返回 undefined 时 res.value() 为 undefined | `computed(() => res.value()?.items ?? [])` |
+| `form().reset()` | 只传部分字段，缺失字段不被重置 | `form().reset({ name: '' })` 补全所有字段 |
+| Service 状态泄漏 | 在 Service 中放 signal 管理 UI 状态 | Service 只做网络请求，状态放在 Component 中 |
+| `model()` vs `output()` | 需双向绑定时用了 output() | 用 `model()`，父组件 `[(visible)]="xxx"` |
+| submit handler | 未阻止默认提交行为 | 用 `FormRoot` 指令，或 `(submit)="check()"` + 检查 valid |

package/dist/skills/reef-testcase/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: reef-testcase
+description: 基于 Jira Issue 生成结构化测试用例清单。从 Jira 功能描述和 PRD 上下文中提取测试场景，覆盖正常流程、边界条件、异常场景、验收标准四维。输出格式兼容 superpowers，可辅助生成更完备的单元测试。
+allowed-tools: Read, Write, Edit, WebFetch, Agent
+deepstorm:
+  tool: reef
+---
+
+# Test Case Generation
+
+## 功能概述
+
+根据 Jira Issue 描述和可选的 PRD 上下文，生成结构化测试用例清单。
+
+**核心理念：** 测试用例不是最终产出，而是开发过程的"脚手架"——帮助开发者和 AI 想清楚边界条件、异常场景、验收标准，从而产出更高质量的代码和单元测试。
+
+### 工作流
+
+```mermaid
+flowchart LR
+    INPUT["Jira Issue 描述"] --> PARSE["解析功能范围"]
+    PRD["PRD 上下文（可选）"] --> PARSE
+    PARSE --> ANALYZE["四维覆盖分析"]
+    ANALYZE --> OUTPUT["结构化测试用例清单"]
+    OUTPUT --> SUPER["→ superpowers 生成单元测试"]
+```
+
+---
+
+## 使用方式
+
+| 方式 | 说明 | 示例 |
+|------|------|------|
+| **提供功能描述**（推荐） | 直接描述功能，自动解析生成 | "帮我生成注册功能的测试用例：邮箱+密码+验证码注册" |
+| **Jira + PRD** | 附上 PRD 链接获取更全面覆盖 | "Jira LC-1234：用户注册。PRD 说支持国际手机号，验证码 5 分钟有效" |
+| **Jira ID 参考** | 仅提 ID，引导补充描述 | "为 LC-1234 生成测试用例"（需用户补充描述） |
+
+---
+
+## 工作流
+
+### 步骤 1：输入收集
+
+#### 1.1 获取 Jira Issue 描述
+
+从用户输入中提取功能描述。完整描述直接解析使用；Issue ID 引导补充；简短描述按原文处理。提取**功能范围**、**用户故事**、**验收标准**。
+
+#### 1.2 获取 PRD 上下文（可选）
+
+从 PRD 提取需求背景、业务规则、约束条件、非功能需求，与 Jira 描述合并形成完整输入。无 PRD 时仅基于 Jira 描述生成，输出标注"上下文受限"。
+
+#### 1.3 需求澄清
+
+针对模糊点向用户提问：核心用户？边界条件/限制？已知异常场景？
+
+---
+
+### 步骤 2：四维覆盖分析
+
+基于收集到的输入，按以下四个维度分析测试覆盖：
+
+| 维度 | 分析目标 | 来源 |
+|------|---------|------|
+| **正常流程** | 用户按预期操作的完整成功路径 | Jira 功能描述中的主要用户场景 |
+| **边界条件** | 输入值、状态或数据的极限条件 | 规格中的限制、约束、最大/最小值 |
+| **异常场景** | 出错的路径、故障、非预期操作 | 错误处理、网络超时、权限不足、数据不存在 |
+| **验收标准验证** | 逐条验证定义的验收条件 | PRD/Jira 中的 AC 列表 |
+
+**覆盖度要求：** 至少覆盖三个维度（必须包含"正常流程"和"验收标准"）。
+
+---
+
+### 步骤 3：结构化测试用例生成
+
+#### 3.1 格式规范
+
+每个测试用例包含以下字段：
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `ID` | 是 | 唯一标识，格式 `TC-{feature}-{seq}` |
+| `类型` | 是 | 正常流程 / 边界条件 / 异常场景 / 验收标准 |
+| `前置条件` | 是 | 测试所需的前置状态或数据 |
+| `测试步骤` | 是 | 清晰的操作步骤描述 |
+| `预期结果` | 是 | 期望的行为或输出 |
+| `关联验收标准` | 否 | 对应 PRD 或 Jira 中的验收标准编号 |
+
+#### 3.2 输出结构
+
+```markdown
+## 测试用例清单
+
+**功能：** {feature name}
+**来源：** {Jira Issue ID}
+**PRD 上下文：** {PRD link / "无"}
+
+---
+
+### 正常流程
+
+{正常流程测试用例列表}
+
+### 边界条件
+
+{边界条件测试用例列表}
+
+### 异常场景
+
+{异常场景测试用例列表}
+
+### 验收标准验证
+
+{验收标准测试用例列表}
+
+---
+
+> **superpowers 提示：** 以上测试用例清单可作为 superpowers 的输入，辅助生成更完备的单元测试。建议将本段内容复制到开发提示中作为上下文。
+```
+
+#### 3.3 特殊处理
+
+无 PRD → 标注"上下文受限，覆盖仅限于 Jira Issue 描述"；无验收标准 → 跳过该维度并标注；单维度用例 ≤ 10 条。
+
+---
+
+## 关键原则
+
+- **按需生成**：开发过程中调用，非批量输出
+- **人工 Review**：AI 产出框架，人工审核补充
+- **开发侧内聚**：测试用例是开发脚手架，辅助 superpowers 生成更完备的单元测试
+
+## 字段模板
+
+测试用例字段模板详见 `references/test-case-template.md`。
+
+## 覆盖维度指引
+
+四维覆盖的详细指引和检查清单详见 `references/coverage-dimensions.md`。

package/dist/skills/reef-testcase/references/coverage-dimensions.md

@@ -0,0 +1,99 @@
+# 测试覆盖四维指引
+
+## 概述
+
+生成测试用例时，需从以下四个维度覆盖被测功能。至少覆盖三个维度（包含"正常流程"和"验收标准"为最低要求）。
+
+---
+
+## 维度一：正常流程
+
+覆盖功能的预期使用路径，即 "Happy Path"。
+
+**关键问题：**
+- 用户按预期操作时会发生什么？
+- 最常见的成功路径是什么？
+- 输入有效数据时系统如何响应？
+
+**示例：**
+```
+ID: TC-login-001 | 类型: 正常流程
+前置条件: 用户已注册且账号正常
+测试步骤: 1. 输入正确用户名和密码 → 2. 点击登录
+预期结果: 成功登录，跳转到首页
+```
+
+---
+
+## 维度二：边界条件
+
+覆盖输入值、状态或数据在极限条件下的行为。
+
+**关键问题：**
+- 输入允许的最大值/最小值？
+- 字符串为空或达到最大长度？
+- 列表为空的边界？
+- 数值为 0 或负数？
+- 时间边界（过去/未来/并发）？
+
+**示例：**
+```
+ID: TC-login-002 | 类型: 边界条件
+前置条件: 用户已注册
+测试步骤: 1. 输入空密码 → 2. 点击登录
+预期结果: 提示"密码不能为空"，禁止提交
+```
+
+---
+
+## 维度三：异常场景
+
+覆盖可能出错的路径、系统故障或非预期操作。
+
+**关键问题：**
+- 网络中断或超时？
+- 数据不存在或已被删除？
+- 权限不足？
+- 并发操作冲突？
+- 输入格式错误或非法字符？
+- 第三方服务不可用？
+
+**示例：**
+```
+ID: TC-login-003 | 类型: 异常场景
+前置条件: 用户已注册但账号被锁定
+测试步骤: 1. 输入正确的用户名和密码 → 2. 点击登录
+预期结果: 提示"账号已被锁定，请联系管理员"
+```
+
+---
+
+## 维度四：验收标准验证
+
+逐条验证 PRD 或 Jira 中定义的验收标准（Acceptance Criteria）是否满足。
+
+**关键问题：**
+- Jira Issue 中列出了哪些 AC？
+- PRD 中有哪些功能验收点？
+- 每条 AC 是否有对应的测试用例验证？
+
+**示例：**
+```
+ID: TC-login-004 | 类型: 验收标准
+前置条件: 用户已注册
+测试步骤: 1. 输入正确凭据 → 2. 勾选"记住我" → 3. 点击登录 → 4. 关闭浏览器 → 5. 重新打开登录页
+预期结果: 用户仍处于登录状态，无需重新输入密码（验证 AC-3: 记住登录状态）
+关联验收标准: AC-3
+```
+
+---
+
+## 覆盖检查清单
+
+生成后，检查以下问题：
+
+- [ ] **正常流程**：是否覆盖了至少一个完整成功路径？
+- [ ] **边界条件**：是否检查了输入/状态的关键边界？
+- [ ] **异常场景**：是否覆盖了至少一个出错路径？
+- [ ] **验收标准**：是否每条 AC 都有对应测试用例？
+- [ ] **至少三个维度**：覆盖度是否 ≥ 3/4？