@deepstorm/cli 0.1.0 → 0.2.0

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

@@ -0,0 +1,124 @@
+# React/JSX 代码折行规则
+
+遵循 90 列限制，以下是 React 专有的折行场景。
+
+## JSX 属性换行
+
+单个属性保持在行内；3 个及以上属性每个占一行：
+
+```tsx
+// ✅ 单属性行内
+<Button type="primary">提交</Button>
+
+// ✅ 2 个属性行内
+<Button type="primary" loading={submitting}>提交</Button>
+
+// ✅ 3+ 属性换行排列
+<Table
+  dataSource={users}
+  columns={columns}
+  rowKey="id"
+  loading={loading}
+  pagination={{ pageSize: 20 }}
+  onChange={handlePageChange}
+/>
+```
+
+## 自闭合标签
+
+无子元素时使用自闭合标签，属性换行规则同上：
+
+```tsx
+// ✅ 无属性
+<Divider />
+
+// ✅ 多属性
+<DatePicker
+  value={date}
+  onChange={setDate}
+  format="YYYY-MM-DD"
+/>
+```
+
+## 条件渲染换行
+
+```tsx
+// ✅ 简单的三元表达式保持行内
+return <div>{loading ? <Spin /> : <UserTable users={users} />}</div>
+
+// ✅ 复杂条件使用 && 或三元换行
+return (
+  <div>
+    {error && (
+      <Alert
+        type="error"
+        message={error.message}
+        closable
+        onClose={clearError}
+      />
+    )}
+    {!loading && !error && <UserTable users={users} />}
+  </div>
+)
+```
+
+## Hook 声明
+
+```tsx
+// ✅ Hook 声明连续排列，按逻辑分组
+const [users, setUsers] = useState<User[]>([])
+const [loading, setLoading] = useState(true)
+const [search, setSearch] = useState('')
+
+// useEffect 依赖较长时换行
+useEffect(() => {
+  fetchUsers(search)
+}, [search]) // 短依赖数组行内
+
+// ✅ 长依赖数组换行
+useEffect(() => {
+  fetchFilteredUsers({ search, role, status, page, size })
+}, [
+  search,
+  role,
+  status,
+  page,
+  size,
+])
+```
+
+## 函数 Props 换行
+
+```tsx
+// ✅ 短函数表达式行内
+<Button onClick={() => setIsOpen(true)}>打开</Button>
+
+// ✅ 多行函数体换行
+<Modal
+  title="确认删除"
+  open={isOpen}
+  onOk={async () => {
+    await deleteUser(id)
+    message.success('删除成功')
+    setIsOpen(false)
+    onDeleted?.()
+  }}
+  onCancel={() => setIsOpen(false)}
+>
+  <p>确定要删除该用户吗？</p>
+</Modal>
+```
+
+## 类型定义换行
+
+```tsx
+// ✅ Props 类型每个属性一行
+interface UserFormProps {
+  user?: User
+  onSubmit: (values: CreateUserRequest) => Promise<void>
+  onCancel: () => void
+}
+
+// ✅ 联合类型换行
+type UserStatus = 'active' | 'inactive' | 'locked' | 'pending'
+```

package/dist/skills/reef-style-frontend/variants/react/examples/component-types-pipes.md

@@ -0,0 +1,195 @@
+# React 组件模式示例
+
+React 中 Pipe 的概念通过自定义 Hook、工具函数或组件组合实现。
+
+## 自定义 Hook 替代 Pipe（数据转换）
+
+Angular Pipe 在 React 中用自定义 Hook 或纯函数替代：
+
+```tsx
+// ✅ 方案1: 纯函数（无状态转换）
+function formatDate(date: string | Date, format: 'short' | 'long' = 'short'): string {
+  const d = typeof date === 'string' ? new Date(date) : date
+  if (format === 'short') {
+    return d.toLocaleDateString('zh-CN')
+  }
+  return d.toLocaleDateString('zh-CN', {
+    year: 'numeric', month: 'long', day: 'numeric',
+    hour: '2-digit', minute: '2-digit',
+  })
+}
+
+function formatCurrency(amount: number, currency = 'CNY'): string {
+  return new Intl.NumberFormat('zh-CN', {
+    style: 'currency',
+    currency,
+  }).format(amount)
+}
+
+// 使用
+const UserList: React.FC = () => {
+  const { users } = useUsers()
+  return (
+    <Table
+      dataSource={users}
+      columns={[
+        { title: '创建时间', dataIndex: 'createdAt', render: (v: string) => formatDate(v, 'short') },
+        { title: '金额', dataIndex: 'amount', render: (v: number) => formatCurrency(v) },
+      ]}
+    />
+  )
+}
+
+// ✅ 方案2: 自定义 Hook（有状态转换 — 如搜索/过滤）
+function useUserFilter(users: User[], search: string): User[] {
+  return useMemo(() => {
+    if (!search.trim()) return users
+    const q = search.toLowerCase()
+    return users.filter(
+      u => u.username.toLowerCase().includes(q) || u.email.toLowerCase().includes(q)
+    )
+  }, [users, search])
+}
+```
+
+## 高阶组件（HOC）— 权限控制
+
+```tsx
+// hoc/withAuth.tsx
+interface WithAuthProps {
+  requiredRole?: UserRole
+}
+
+export function withAuth<P extends object>(
+  Component: React.ComponentType<P>,
+  options?: WithAuthProps
+) {
+  const AuthenticatedComponent: React.FC<P> = (props) => {
+    const { user, loading } = useAuth()
+
+    if (loading) return <Spin />
+    if (!user) return <Navigate to="/login" replace />
+
+    if (options?.requiredRole && user.role !== options.requiredRole) {
+      return <Result status="403" title="无权限访问" />
+    }
+
+    return <Component {...props} />
+  }
+
+  AuthenticatedComponent.displayName = `withAuth(${Component.displayName || Component.name})`
+  return AuthenticatedComponent
+}
+
+// 使用
+const AdminDashboard = withAuth(Dashboard, { requiredRole: UserRole.Admin })
+```
+
+## 组件组合模式
+
+```tsx
+// ✅ 复合组件模式（Compound Component）
+interface CardComposition {
+  Header: React.FC<{ title: string }>
+  Body: React.FC<{ children: React.ReactNode }>
+  Footer: React.FC<{ children: React.ReactNode }>
+}
+
+const Card: React.FC<{ children: React.ReactNode }> & CardComposition = ({ children }) => (
+  <Card className="rounded-lg border shadow-sm">{children}</Card>
+)
+
+Card.Header = ({ title }) => (
+  <div className="border-b px-4 py-3 font-medium">{title}</div>
+)
+Card.Body = ({ children }) => (
+  <div className="px-4 py-3">{children}</div>
+)
+Card.Footer = ({ children }) => (
+  <div className="border-t px-4 py-3 flex justify-end gap-2">{children}</div>
+)
+
+// 使用
+<Card>
+  <Card.Header title="用户信息" />
+  <Card.Body>
+    <p>用户名: {user.username}</p>
+    <p>邮箱: {user.email}</p>
+  </Card.Body>
+  <Card.Footer>
+    <Button onClick={onCancel}>取消</Button>
+    <Button type="primary" onClick={onSave}>保存</Button>
+  </Card.Footer>
+</Card>
+```
+
+## Render Props 模式
+
+```tsx
+// 数据获取 Render Props（复用数据加载逻辑）
+interface DataLoaderProps<T> {
+  fetchFn: () => Promise<T>
+  children: (result: { data: T | null; loading: boolean; error: Error | null }) => React.ReactNode
+}
+
+function DataLoader<T>({ fetchFn, children }: DataLoaderProps<T>) {
+  const [data, setData] = useState<T | null>(null)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<Error | null>(null)
+
+  useEffect(() => {
+    fetchFn()
+      .then(setData)
+      .catch(setError)
+      .finally(() => setLoading(false))
+  }, [])
+
+  return <>{children({ data, loading, error })}</>
+}
+
+// 使用
+<DataLoader fetchFn={() => userService.getById(id)}>
+  {({ data: user, loading, error }) => {
+    if (loading) return <Skeleton active />
+    if (error) return <Alert type="error" message={error.message} />
+    return <UserForm user={user} />
+  }}
+</DataLoader>
+```
+
+## Discriminated Union 组件模式
+
+```tsx
+// 多形态组件 - 根据 type 渲染不同 UI
+type NotificationCardProps =
+  | { type: 'success'; message: string }
+  | { type: 'error'; message: string; errorCode?: string }
+  | { type: 'confirm'; message: string; onConfirm: () => void; onCancel: () => void }
+
+const NotificationCard: React.FC<NotificationCardProps> = (props) => {
+  switch (props.type) {
+    case 'success':
+      return <Alert type="success" message={props.message} showIcon />
+    case 'error':
+      return (
+        <Alert
+          type="error"
+          message={props.message}
+          description={props.errorCode ? `错误码: ${props.errorCode}` : undefined}
+          showIcon
+        />
+      )
+    case 'confirm':
+      return (
+        <Modal
+          open
+          title="确认"
+          onOk={props.onConfirm}
+          onCancel={props.onCancel}
+        >
+          <p>{props.message}</p>
+        </Modal>
+      )
+  }
+}
+```

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

@@ -0,0 +1,127 @@
+# React 实体类型定义示例
+
+## 基础实体层次
+
+```tsx
+// shared/types/entity.ts
+export interface ImmutableEntity {
+  readonly id: string
+  readonly createdAt: string
+  readonly updatedAt: string
+}
+
+export interface Entity extends ImmutableEntity {
+  version: number
+}
+
+export interface Auditable<T> extends Entity {
+  createdBy: T
+  updatedBy: T
+}
+
+export interface ImmutableAuditable<T> extends ImmutableEntity {
+  createdBy: T
+}
+```
+
+## API 响应类型
+
+```tsx
+// shared/types/api.ts
+export interface PageResponse<T> {
+  content: T[]
+  totalElements: number
+  totalPages: number
+  number: number
+  size: number
+  first: boolean
+  last: boolean
+}
+
+export interface ApiError {
+  code: string
+  message: string
+  details?: Record<string, string[]>
+}
+```
+
+## 业务实体示例
+
+```tsx
+// shared/types/user.ts
+export interface User extends Auditable<string> {
+  username: string
+  email: string
+  displayName: string
+  avatar?: string
+  role: UserRole
+  active: boolean
+}
+
+export enum UserRole {
+  Admin = 'ADMIN',
+  Editor = 'EDITOR',
+  Viewer = 'VIEWER',
+}
+
+export interface CreateUserRequest {
+  username: string
+  email: string
+  displayName: string
+  role: UserRole
+}
+
+export interface UpdateUserRequest {
+  email?: string
+  displayName?: string
+  role?: UserRole
+}
+```
+
+## 组件 Props 类型
+
+```tsx
+// 通用组件：具名导出 + interface Props
+export interface UserAvatarProps {
+  user: Pick<User, 'username' | 'avatar'>
+  size?: 'sm' | 'md' | 'lg'
+  onClick?: () => void
+}
+
+export const UserAvatar: React.FC<UserAvatarProps> = ({ user, size = 'md', onClick }) => {
+  return (
+    <Avatar
+      src={user.avatar}
+      alt={user.username}
+      size={size === 'sm' ? 24 : size === 'md' ? 32 : 48}
+      onClick={onClick}
+      style={{ cursor: onClick ? 'pointer' : 'default' }}
+    />
+  )
+}
+
+// 页面组件：默认导出 + Props 从路由参数推断
+export interface UserListPageProps {
+  // 可由 React Router loader 数据注入
+}
+
+const UserListPage: React.FC<UserListPageProps> = () => {
+  const { users, loading } = useUsers()
+  return <UserTable users={users} loading={loading} />
+}
+export default UserListPage
+```
+
+## Discriminated Union 类型
+
+```tsx
+// 用于多状态组件
+export type NotificationType = 'success' | 'error' | 'warning' | 'info'
+
+export interface NotificationConfig {
+  type: NotificationType
+  title: string
+  message: string
+  duration?: number
+}
+```

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

@@ -0,0 +1,251 @@
+# React 表单模式（Ant Design Form）
+
+## 基础表单
+
+```tsx
+interface CreateUserFormValues {
+  username: string
+  email: string
+  displayName: string
+  role: UserRole
+}
+
+const CreateUserForm: React.FC = () => {
+  const [form] = Form.useForm<CreateUserFormValues>()
+  const [loading, setLoading] = useState(false)
+
+  const handleSubmit = async (values: CreateUserFormValues) => {
+    setLoading(true)
+    try {
+      await createUser(values)
+      message.success('用户创建成功')
+      form.resetFields()
+    } catch (err) {
+      // Ant Design Form 会自动捕获校验错误
+      message.error('创建失败，请重试')
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <Form
+      form={form}
+      layout="vertical"
+      onFinish={handleSubmit}
+      autoComplete="off"
+    >
+      <Form.Item
+        name="username"
+        label="用户名"
+        rules={[
+          { required: true, message: '请输入用户名' },
+          { min: 3, max: 32, message: '用户名长度 3-32 个字符' },
+        ]}
+      >
+        <Input placeholder="请输入用户名" />
+      </Form.Item>
+
+      <Form.Item
+        name="email"
+        label="邮箱"
+        rules={[
+          { required: true, message: '请输入邮箱' },
+          { type: 'email', message: '请输入有效的邮箱地址' },
+        ]}
+      >
+        <Input placeholder="请输入邮箱" />
+      </Form.Item>
+
+      <Form.Item
+        name="displayName"
+        label="显示名称"
+        rules={[{ required: true, message: '请输入显示名称' }]}
+      >
+        <Input placeholder="请输入显示名称" />
+      </Form.Item>
+
+      <Form.Item
+        name="role"
+        label="角色"
+        rules={[{ required: true, message: '请选择角色' }]}
+      >
+        <Select placeholder="请选择角色">
+          <Select.Option value="ADMIN">管理员</Select.Option>
+          <Select.Option value="EDITOR">编辑</Select.Option>
+          <Select.Option value="VIEWER">查看者</Select.Option>
+        </Select>
+      </Form.Item>
+
+      <Form.Item>
+        <Button type="primary" htmlType="submit" loading={loading}>
+          创建
+        </Button>
+      </Form.Item>
+    </Form>
+  )
+}
+```
+
+## 编辑表单（初始值）
+
+```tsx
+interface EditUserFormProps {
+  user: User
+  onSuccess: () => void
+}
+
+const EditUserForm: React.FC<EditUserFormProps> = ({ user, onSuccess }) => {
+  const [form] = Form.useForm()
+  const [loading, setLoading] = useState(false)
+
+  // 初始值填充
+  useEffect(() => {
+    form.setFieldsValue({
+      displayName: user.displayName,
+      email: user.email,
+      role: user.role,
+    })
+  }, [user, form])
+
+  const handleSubmit = async (values: Partial<CreateUserRequest>) => {
+    setLoading(true)
+    try {
+      await updateUser(user.id, values)
+      message.success('用户信息已更新')
+      onSuccess()
+    } catch {
+      message.error('更新失败')
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <Form
+      form={form}
+      layout="vertical"
+      onFinish={handleSubmit}
+    >
+      {/* 用户名只读展示 */}
+      <Form.Item label="用户名">
+        <Input value={user.username} disabled />
+      </Form.Item>
+
+      <Form.Item
+        name="email"
+        label="邮箱"
+        rules={[{ type: 'email' }]}
+      >
+        <Input />
+      </Form.Item>
+
+      <Form.Item
+        name="displayName"
+        label="显示名称"
+      >
+        <Input />
+      </Form.Item>
+
+      <Form.Item
+        name="role"
+        label="角色"
+      >
+        <Select>
+          <Select.Option value="ADMIN">管理员</Select.Option>
+          <Select.Option value="EDITOR">编辑</Select.Option>
+          <Select.Option value="VIEWER">查看者</Select.Option>
+        </Select>
+      </Form.Item>
+
+      <Form.Item>
+        <Button type="primary" htmlType="submit" loading={loading}>
+          保存
+        </Button>
+      </Form.Item>
+    </Form>
+  )
+}
+```
+
+## 搜索表单（非受控 + 联动 Table）
+
+```tsx
+const UserListPage: React.FC = () => {
+  const [searchForm] = Form.useForm()
+  const [query, setQuery] = useState<Record<string, string>>({})
+
+  const handleSearch = (values: Record<string, string>) => {
+    // 过滤空值
+    const filtered = Object.fromEntries(
+      Object.entries(values).filter(([, v]) => v !== undefined && v !== '')
+    )
+    setQuery(filtered)
+  }
+
+  const handleReset = () => {
+    searchForm.resetFields()
+    setQuery({})
+  }
+
+  return (
+    <div>
+      <Form
+        form={searchForm}
+        layout="inline"
+        onFinish={handleSearch}
+      >
+        <Form.Item name="keyword">
+          <Input.Search placeholder="搜索用户名/邮箱" onSearch={() => searchForm.submit()} />
+        </Form.Item>
+        <Form.Item name="role">
+          <Select placeholder="角色" allowClear style={{ width: 120 }}>
+            <Select.Option value="ADMIN">管理员</Select.Option>
+            <Select.Option value="EDITOR">编辑</Select.Option>
+          </Select>
+        </Form.Item>
+        <Form.Item name="status">
+          <Select placeholder="状态" allowClear style={{ width: 120 }}>
+            <Select.Option value="active">活跃</Select.Option>
+            <Select.Option value="inactive">停用</Select.Option>
+          </Select>
+        </Form.Item>
+        <Form.Item>
+          <Button type="primary" htmlType="submit">查询</Button>
+          <Button onClick={handleReset} style={{ marginLeft: 8 }}>重置</Button>
+        </Form.Item>
+      </Form>
+
+      <UserTable query={query} />
+    </div>
+  )
+}
+```
+
+## 全局校验信息配置
+
+```tsx
+// 在应用入口统一配置校验信息
+import { ConfigProvider } from 'antd'
+
+const App: React.FC = () => (
+  <ConfigProvider
+    form={{
+      validateMessages: {
+        required: "'${label}' 是必填项",
+        types: {
+          email: "'${label}' 不是有效的邮箱地址",
+          number: "'${label}' 不是有效的数字",
+        },
+        string: {
+          min: "'${label}' 最少 ${min} 个字符",
+          max: "'${label}' 最多 ${max} 个字符",
+          range: "'${label}' 长度在 ${min} 到 ${max} 之间",
+        },
+      },
+    }}
+  >
+    {/* Router 和页面内容 */}
+  </ConfigProvider>
+)
+```