@deepstorm/cli 0.1.0 → 0.2.0

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

@@ -0,0 +1,226 @@
+# React 数据获取层 + 路由配置示例
+
+## 自定义 Hook（数据获取层）
+
+```tsx
+// hooks/useUsers.ts
+import { useState, useEffect, useCallback } from 'react'
+import type { User, PageResponse } from '../shared/types/user'
+
+interface UseUsersOptions {
+  page?: number
+  size?: number
+  search?: string
+  role?: string
+}
+
+interface UseUsersResult {
+  users: User[]
+  total: number
+  loading: boolean
+  error: Error | null
+  refresh: () => void
+}
+
+// 使用 URLSearchParams 构建查询参数
+function buildQuery(params: UseUsersOptions): string {
+  const searchParams = new URLSearchParams()
+  if (params.page !== undefined) searchParams.set('page', String(params.page))
+  if (params.size !== undefined) searchParams.set('size', String(params.size))
+  if (params.search) searchParams.set('search', params.search)
+  if (params.role) searchParams.set('role', params.role)
+  const qs = searchParams.toString()
+  return qs ? `?${qs}` : ''
+}
+
+export function useUsers(options: UseUsersOptions = {}): UseUsersResult {
+  const [users, setUsers] = useState<User[]>([])
+  const [total, setTotal] = useState(0)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<Error | null>(null)
+  const [refreshKey, setRefreshKey] = useState(0)
+
+  const refresh = useCallback(() => setRefreshKey(k => k + 1), [])
+
+  useEffect(() => {
+    let cancelled = false
+    setLoading(true)
+    setError(null)
+
+    fetch(`/api/v1/users${buildQuery(options)}`)
+      .then(res => {
+        if (!res.ok) throw new Error(`HTTP ${res.status}`)
+        return res.json() as Promise<PageResponse<User>>
+      })
+      .then(data => {
+        if (!cancelled) {
+          setUsers(data.content)
+          setTotal(data.totalElements)
+          setLoading(false)
+        }
+      })
+      .catch(err => {
+        if (!cancelled) {
+          setError(err)
+          setLoading(false)
+        }
+      })
+
+    return () => { cancelled = true }
+  }, [options.page, options.size, options.search, options.role, refreshKey])
+
+  return { users, total, loading, error, refresh }
+}
+
+// 写操作 Hook
+export function useCreateUser() {
+  const [loading, setLoading] = useState(false)
+
+  const create = async (data: CreateUserRequest): Promise<User> => {
+    setLoading(true)
+    const res = await fetch('/api/v1/users', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    })
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    const user = await res.json()
+    setLoading(false)
+    return user
+  }
+
+  return { create, loading }
+}
+```
+
+## Service 层抽取（可选 — 复杂项目使用）
+
+```tsx
+// services/userService.ts
+// 将 API 调用统一到 Service 层，Hook 只负责状态管理
+import type { User, CreateUserRequest, UpdateUserRequest, PageResponse } from '../shared/types/user'
+
+const BASE_URL = '/api/v1/users'
+
+async function handleResponse<T>(res: Response): Promise<T> {
+  if (!res.ok) {
+    const error = await res.json().catch(() => ({ message: `HTTP ${res.status}` }))
+    throw new Error(error.message)
+  }
+  return res.json()
+}
+
+export const userService = {
+  list(params?: Record<string, string | number>): Promise<PageResponse<User>> {
+    const qs = params ? '?' + new URLSearchParams(
+      Object.entries(params).map(([k, v]) => [k, String(v)])
+    ).toString() : ''
+    return fetch(`${BASE_URL}${qs}`).then(handleResponse)
+  },
+
+  getById(id: string): Promise<User> {
+    return fetch(`${BASE_URL}/${id}`).then(handleResponse)
+  },
+
+  create(data: CreateUserRequest): Promise<User> {
+    return fetch(BASE_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    }).then(handleResponse)
+  },
+
+  update(id: string, data: UpdateUserRequest): Promise<User> {
+    return fetch(`${BASE_URL}/${id}`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    }).then(handleResponse)
+  },
+
+  delete(id: string): Promise<void> {
+    return fetch(`${BASE_URL}/${id}`, { method: 'DELETE' }).then(handleResponse)
+  },
+}
+```
+
+## 路由配置
+
+```tsx
+// routes/index.tsx
+import { createBrowserRouter, Navigate } from 'react-router-dom'
+import { lazy, Suspense } from 'react'
+import { Spin } from 'antd'
+
+// 懒加载页面组件
+const Dashboard = lazy(() => import('../pages/Dashboard'))
+const UserList = lazy(() => import('../pages/UserList'))
+const UserDetail = lazy(() => import('../pages/UserDetail'))
+const CreateUser = lazy(() => import('../pages/CreateUser'))
+const Settings = lazy(() => import('../pages/Settings'))
+const NotFound = lazy(() => import('../pages/NotFound'))
+
+// 通用懒加载包装
+const LazyLoad: React.FC<{ children: React.ReactNode }> = ({ children }) => (
+  <Suspense fallback={<Spin style={{ display: 'flex', justifyContent: 'center', marginTop: 120 }} />}>
+    {children}
+  </Suspense>
+)
+
+export const router = createBrowserRouter([
+  {
+    path: '/',
+    element: <LazyLoad><Dashboard /></LazyLoad>,
+  },
+  {
+    path: '/users',
+    element: <LazyLoad><UserList /></LazyLoad>,
+  },
+  {
+    path: '/users/new',
+    element: <LazyLoad><CreateUser /></LazyLoad>,
+  },
+  {
+    path: '/users/:id',
+    element: <LazyLoad><UserDetail /></LazyLoad>,
+  },
+  {
+    path: '/settings',
+    element: <LazyLoad><Settings /></LazyLoad>,
+  },
+  {
+    path: '/404',
+    element: <LazyLoad><NotFound /></LazyLoad>,
+  },
+  {
+    path: '*',
+    element: <Navigate to="/404" replace />,
+  },
+])
+```
+
+## 主应用入口
+
+```tsx
+// App.tsx
+import { RouterProvider } from 'react-router-dom'
+import { ConfigProvider } from 'antd'
+import { router } from './routes'
+
+const App: React.FC = () => {
+  return (
+    <ConfigProvider
+      theme={{
+        token: {
+          colorPrimary: '#1677ff',
+          borderRadius: 6,
+        },
+      }}
+    >
+      <RouterProvider router={router} />
+    </ConfigProvider>
+  )
+}
+
+export default App
+```

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

@@ -0,0 +1,118 @@
+# 前端编码快速参考 (React)
+
+按需加载。仅当你需要编写对应组件类型时阅读相关章节。
+
+> **完整示例代码见 `examples/` 目录。** 已安装子维度的规范，通过该维度的 `{value}.md` 文件阅读。
+
+## 速查
+
+| 场景 | 决策 |
+| --- | --- |
+| 新建组件 | 函数组件 + TypeScript + `interface` Props |
+| 新建表单 | Ant Design `Form` + `useState` / `useReducer` |
+| 读数据 | 自定义 Hook（`useUsers`）封装 fetch/axios |
+| 写数据 | 自定义 Hook + `useState` loading/error 三态 |
+| Hook 职责 | 只负责业务逻辑和数据获取，不管理 UI 渲染 |
+| 路由 | `React.lazy()` + `Suspense` 懒加载 |
+
+## 新建组件
+
+```tsx
+interface UserTableProps {
+  users: User[]
+  loading?: boolean
+  onSelect?: (user: User) => void
+}
+
+const UserTable: React.FC<UserTableProps> = ({ users, loading, onSelect }) => {
+  return (
+    <Table
+      dataSource={users}
+      loading={loading}
+      rowKey="id"
+      columns={columns}
+      onRow={(record) => ({
+        onClick: () => onSelect?.(record),
+      })}
+    />
+  )
+}
+```
+
+| 规则 | 要求 |
+| --- | --- |
+| 函数组件 | 禁止 Class 组件，使用 `React.FC` 或显式 Props 类型 |
+| `interface` Props | 使用 `interface` 定义 Props，使用 `type` 定义联合类型 |
+| 状态提升 | 组件间共享状态提升到最近公共父组件 |
+| 默认导出 | 页面级组件使用 `export default`，通用组件使用具名导出 |
+
+## Hooks 规则
+
+- **顶层调用**：禁止在条件、循环、嵌套函数中调用 Hooks
+- **依赖数组**：`useEffect` / `useCallback` / `useMemo` 的依赖数组必须穷举闭包内所有响应值
+- **自定义 Hook**：以 `use` 开头命名，返回值为对象或元组
+
+```tsx
+// ✅ 正确：自定义 Hook 分离数据获取逻辑
+function useUsers() {
+  const [users, setUsers] = useState<User[]>([])
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<Error | null>(null)
+
+  useEffect(() => {
+    fetch('/api/v1/users')
+      .then(res => res.json())
+      .then(data => { setUsers(data); setLoading(false) })
+      .catch(err => { setError(err); setLoading(false) })
+  }, [])
+
+  return { users, loading, error }
+}
+```
+
+## Ant Design 组件
+
+- **按需导入**：`import { Button, Table } from 'antd'`（Ant Design 5.x 支持 Tree Shaking，无需额外配置）
+- **Form**：`Form.Item` 的 `name` 必须与数据模型字段一致
+- **Table**：列定义使用 `columns` 数组，`dataSource` 需要唯一 `rowKey`
+- **Modal**：关闭时通过 `afterClose` 或 `destroyOnClose` 重置内部状态
+- **布局**：使用 `Row` / `Col` 栅格系统或 Flex 布局
+
+## 错误处理
+
+- 全局错误边界（Error Boundary）捕获组件渲染异常
+- API 错误在 Hook 层捕获并暴露错误状态，UI 层通过 Ant Design 组件展示反馈
+- 表单校验使用 Ant Design Form 内置校验规则，非必要不自定义 `validator`
+
+## 路由
+
+- 所有页面组件使用 `React.lazy()` + `Suspense` 懒加载
+- 路由配置集中定义在路由文件中，不在组件内嵌路由
+- 权限通过 Route 组件的 wrapper 或 middleware 模式控制
+
+```tsx
+const UserList = React.lazy(() => import('./pages/UserList'))
+const UserDetail = React.lazy(() => import('./pages/UserDetail'))
+
+const routes = [
+  { path: '/users', element: <UserList /> },
+  { path: '/users/:id', element: <UserDetail /> },
+]
+```
+
+## 代码风格
+
+- 控制流语句必须使用大括号，禁止无大括号的早期返回
+- 代码折行规则（90 列限制）详见 `examples/code-wrapping.md`
+- JSX 属性超过 3 个时换行排列
+- 自闭合标签：无子元素时使用 `<Component />` 而非 `<Component></Component>`
+
+## 常见坑
+
+| 场景 | 问题 | 正确做法 |
+|------|------|---------|
+| `useEffect` 依赖遗漏 | 闭包内使用了 state 或 props 但未加入依赖数组 | 穷举所有依赖，或使用 `useCallback` 稳定引用 |
+| 列表 `key` | 使用 index 作为 key 导致渲染异常 | 使用唯一 ID（`rowKey` / 数据 id） |
+| 表单受控/非受控混淆 | 组件同时接收 `value` 和 `defaultValue` | 受控组件用 `value` + `onChange`，非受控用 `defaultValue` |
+| 状态更新异步 | 连续 `setState` 导致只生效最后一次 | 使用函数形式 `setCount(prev => prev + 1)` |
+| `useCallback` 滥用 | 对所有函数都用 `useCallback` | 仅对传给子组件或 `useEffect` 依赖的函数使用 |

package/dist/skills/reef-style-frontend/variants/vue/examples/code-wrapping.md

@@ -0,0 +1,162 @@
+# Vue 模板/脚本代码折行规则
+
+遵循 90 列限制，以下是 Vue 专有的折行场景。
+
+## 模板属性换行
+
+单个属性保持在行内；3 个及以上属性每个占一行：
+
+```vue
+<template>
+  <!-- ✅ 单属性行内 -->
+  <a-button type="primary">提交</a-button>
+
+  <!-- ✅ 2 个属性行内 -->
+  <a-button type="primary" :loading="submitting">提交</a-button>
+
+  <!-- ✅ 3+ 属性换行排列 -->
+  <a-table
+    :data-source="users"
+    :columns="columns"
+    row-key="id"
+    :loading="loading"
+    :pagination="{ pageSize: 20 }"
+    @change="handlePageChange"
+  />
+</template>
+```
+
+## 指令换行
+
+```vue
+<template>
+  <!-- ✅ 短指令行内 -->
+  <div v-if="loading">加载中...</div>
+
+  <!-- ✅ 多指令或长表达式适当换行 -->
+  <a-form-item
+    v-if="!isReadonly"
+    label="邮箱"
+    name="email"
+    :rules="[
+      { required: true, message: '请输入邮箱', trigger: 'blur' },
+      { type: 'email', message: '无效的邮箱格式', trigger: 'blur' },
+    ]"
+  >
+    <a-input v-model:value="formState.email" />
+  </a-form-item>
+</template>
+```
+
+## 自闭合标签
+
+无子元素时使用自闭合标签，属性换行规则同上：
+
+```vue
+<template>
+  <!-- ✅ 无属性 -->
+  <a-divider />
+
+  <!-- ✅ 多属性 -->
+  <a-date-picker
+    v-model:value="date"
+    format="YYYY-MM-DD"
+  />
+</template>
+```
+
+## 条件渲染换行
+
+```vue
+<template>
+  <!-- ✅ 简单的 v-if/v-else 保持紧凑 -->
+  <div>{{ loading ? '加载中...' : users.length + ' 条记录' }}</div>
+
+  <!-- ✅ 复杂条件使用多个 v-if 换行 -->
+  <a-alert
+    v-if="error"
+    type="error"
+    :message="error.message"
+    closable
+    @close="clearError"
+  />
+  <a-table v-else-if="!loading" :data-source="users" />
+</template>
+```
+
+## Script setup 声明
+
+```vue
+<script setup lang="ts">
+// ✅ ref/computed 连续排列，按逻辑分组
+const users = ref<User[]>([])
+const loading = ref(true)
+const search = ref('')
+
+const filteredUsers = computed(() =>
+  users.value.filter(u => u.username.includes(search.value))
+)
+
+// ✅ watch 短依赖行内
+watch(search, () => {
+  fetchUsers(search.value)
+})
+
+// ✅ 多源 watch 换行
+watch(
+  [search, role, status],
+  ([newSearch, newRole, newStatus]) => {
+    fetchFilteredUsers({ search: newSearch, role: newRole, status: newStatus })
+  }
+)
+</script>
+```
+
+## 事件处理函数换行
+
+```vue
+<template>
+  <!-- ✅ 短表达式行内 -->
+  <a-button @click="isOpen = true">打开</a-button>
+
+  <!-- ✅ 多行函数体：提取到 script setup 中 -->
+  <a-modal
+    title="确认删除"
+    :open="isOpen"
+    @ok="handleDelete"
+    @cancel="isOpen = false"
+  >
+    <p>确定要删除该用户吗？</p>
+  </a-modal>
+</template>
+
+<script setup lang="ts">
+async function handleDelete() {
+  await deleteUser(id)
+  message.success('删除成功')
+  isOpen.value = false
+  onDeleted?.()
+}
+</script>
+```
+
+## Props / Emits 类型定义换行
+
+```typescript
+// ✅ 每个属性一行
+interface UserFormProps {
+  user?: User
+  onSubmit: (values: CreateUserRequest) => Promise<void>
+  onCancel: () => void
+}
+
+// ✅ emits 命名元组每个事件一行
+const emit = defineEmits<{
+  success: [userId: string]
+  close: []
+  error: [message: string]
+}>()
+
+// ✅ 联合类型换行
+type UserStatus = 'active' | 'inactive' | 'locked' | 'pending'
+```