@deepstorm/cli 0.1.0 → 0.2.0

package/dist/skills/reef-style-frontend/fragments/ui-lib/antd/examples/ui-components.md

@@ -0,0 +1,257 @@
+# Ant Design 组件代码示例
+
+## 完整数据表格（搜索 + 分页 + 操作列）
+
+```tsx
+import { useState, useEffect } from 'react'
+import { Table, Button, Space, Input, Tag, Modal, message } from 'antd'
+import { SearchOutlined, PlusOutlined, EditOutlined, DeleteOutlined } from '@ant-design/icons'
+import type { ColumnsType, TablePaginationConfig } from 'antd/es/table'
+import type { User, PageResponse } from '../types/user'
+import { userService } from '../services/userService'
+
+const UserManagement: React.FC = () => {
+  const [users, setUsers] = useState<User[]>([])
+  const [loading, setLoading] = useState(false)
+  const [pagination, setPagination] = useState({ current: 1, pageSize: 20, total: 0 })
+  const [search, setSearch] = useState('')
+
+  const fetchUsers = async (page: number, size: number, keyword?: string) => {
+    setLoading(true)
+    try {
+      const data: PageResponse<User> = await userService.list({ page, size, search: keyword })
+      setUsers(data.content)
+      setPagination(prev => ({ ...prev, current: data.number, total: data.totalElements }))
+    } catch {
+      message.error('加载用户列表失败')
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  useEffect(() => {
+    fetchUsers(pagination.current, pagination.pageSize, search)
+  }, [pagination.current, pagination.pageSize])
+
+  const handleSearch = (value: string) => {
+    setSearch(value)
+    setPagination(prev => ({ ...prev, current: 1 }))
+  }
+
+  const handleDelete = (id: string) => {
+    Modal.confirm({
+      title: '确认删除',
+      content: '删除后不可恢复，确定继续？',
+      okText: '删除',
+      okType: 'danger',
+      onOk: async () => {
+        await userService.delete(id)
+        message.success('删除成功')
+        fetchUsers(pagination.current, pagination.pageSize, search)
+      },
+    })
+  }
+
+  const columns: ColumnsType<User> = [
+    { title: '用户名', dataIndex: 'username', key: 'username' },
+    { title: '邮箱', dataIndex: 'email', key: 'email' },
+    {
+      title: '角色',
+      dataIndex: 'role',
+      key: 'role',
+      render: (role: string) => {
+        const color = role === 'ADMIN' ? 'red' : role === 'EDITOR' ? 'blue' : 'default'
+        return <Tag color={color}>{role}</Tag>
+      },
+    },
+    {
+      title: '状态',
+      dataIndex: 'active',
+      key: 'active',
+      render: (active: boolean) => (
+        <Tag color={active ? 'green' : 'default'}>{active ? '活跃' : '停用'}</Tag>
+      ),
+    },
+    {
+      title: '操作',
+      key: 'action',
+      render: (_, record) => (
+        <Space>
+          <Button type="link" icon={<EditOutlined />} onClick={() => handleEdit(record)}>编辑</Button>
+          <Button type="link" danger icon={<DeleteOutlined />} onClick={() => handleDelete(record.id)}>删除</Button>
+        </Space>
+      ),
+    },
+  ]
+
+  return (
+    <div>
+      <div style={{ marginBottom: 16, display: 'flex', justifyContent: 'space-between' }}>
+        <Input.Search
+          placeholder="搜索用户名/邮箱"
+          allowClear
+          onSearch={handleSearch}
+          style={{ width: 300 }}
+        />
+        <Button type="primary" icon={<PlusOutlined />} onClick={handleCreate}>
+          新增用户
+        </Button>
+      </div>
+
+      <Table
+        columns={columns}
+        dataSource={users}
+        rowKey="id"
+        loading={loading}
+        pagination={{
+          ...pagination,
+          showSizeChanger: true,
+          showTotal: (total) => `共 ${total} 条`,
+        }}
+        onChange={(pag: TablePaginationConfig) => {
+          setPagination(prev => ({
+            ...prev,
+            current: pag.current ?? 1,
+            pageSize: pag.pageSize ?? 20,
+          }))
+        }}
+      />
+    </div>
+  )
+}
+```
+
+## 表单弹窗（创建/编辑）
+
+```tsx
+interface UserFormModalProps {
+  open: boolean
+  editingUser?: User | null
+  onClose: () => void
+  onSuccess: () => void
+}
+
+const UserFormModal: React.FC<UserFormModalProps> = ({ open, editingUser, onClose, onSuccess }) => {
+  const [form] = Form.useForm()
+  const [saving, setSaving] = useState(false)
+  const isEditing = !!editingUser
+
+  useEffect(() => {
+    if (open) {
+      if (editingUser) {
+        form.setFieldsValue({
+          displayName: editingUser.displayName,
+          email: editingUser.email,
+          role: editingUser.role,
+        })
+      } else {
+        form.resetFields()
+      }
+    }
+  }, [open, editingUser, form])
+
+  const handleSubmit = async () => {
+    try {
+      const values = await form.validateFields()
+      setSaving(true)
+      if (isEditing) {
+        await userService.update(editingUser!.id, values)
+        message.success('用户信息已更新')
+      } else {
+        await userService.create(values)
+        message.success('用户创建成功')
+      }
+      onSuccess()
+      onClose()
+    } catch (err) {
+      // Form validateFields 校验失败会自动聚焦到错误字段，不需要额外处理
+      if (err instanceof Error) {
+        message.error(err.message)
+      }
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  return (
+    <Modal
+      title={isEditing ? '编辑用户' : '新增用户'}
+      open={open}
+      onOk={handleSubmit}
+      onCancel={onClose}
+      confirmLoading={saving}
+      destroyOnClose
+      okText={isEditing ? '保存' : '创建'}
+    >
+      <Form
+        form={form}
+        layout="vertical"
+        autoComplete="off"
+      >
+        <Form.Item
+          name="displayName"
+          label="显示名称"
+          rules={[{ required: true, message: '请输入显示名称' }]}
+        >
+          <Input placeholder="请输入显示名称" />
+        </Form.Item>
+
+        <Form.Item
+          name="email"
+          label="邮箱"
+          rules={[
+            { required: true, message: '请输入邮箱' },
+            { type: 'email', 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>
+    </Modal>
+  )
+}
+```
+
+## 响应式布局
+
+```tsx
+import { Row, Col, Card, Statistic } from 'antd'
+import { UserOutlined, FileTextOutlined, AuditOutlined } from '@ant-design/icons'
+
+const Dashboard: React.FC = () => {
+  return (
+    <div>
+      {/* 统计卡片 - 响应式栅格 */}
+      <Row gutter={[16, 16]}>
+        <Col xs={24} sm={12} lg={6}>
+          <Card>
+            <Statistic title="用户总数" value={1280} prefix={<UserOutlined />} />
+          </Card>
+        </Col>
+        <Col xs={24} sm={12} lg={6}>
+          <Card>
+            <Statistic title="文档数" value={356} prefix={<FileTextOutlined />} />
+          </Card>
+        </Col>
+        <Col xs={24} sm={12} lg={6}>
+          <Card>
+            <Statistic title="待审核" value={23} prefix={<AuditOutlined />} />
+          </Card>
+        </Col>
+      </Row>
+    </div>
+  )
+}
+```

package/dist/skills/reef-style-frontend/fragments/ui-lib/antd/quick-reference.md

@@ -0,0 +1,166 @@
+# Ant Design 5.x 组件使用规范
+
+## 通用原则
+
+- Ant Design 5.x 使用 CSS-in-JS（`@ant-design/cssinjs`），无需额外引入 CSS 文件
+- 组件使用 Tree Shaking 按需导入，`import { Button, Table } from 'antd'` 即可
+- 主题定制通过 `ConfigProvider` 的 `theme` 属性配置，禁止直接覆盖 Ant Design 的 CSS 类名
+- 图标使用 `@ant-design/icons` 的具名导入：`import { UserOutlined } from '@ant-design/icons'`
+
+## 常用组件规范
+
+### Button（按钮）
+- 主要操作使用 `type="primary"`，次要操作默认
+- 危险操作使用 `danger` 属性
+- 异步操作必须设置 `loading` 状态防重复提交
+- 纯图标按钮必须有 `aria-label` 提供无障碍说明
+
+```tsx
+<Button type="primary" loading={submitting} onClick={handleSubmit}>
+  提交
+</Button>
+<Button danger onClick={handleDelete}>删除</Button>
+<Button icon={<SearchOutlined />} aria-label="搜索" />
+```
+
+### Table（表格）
+- 始终指定 `rowKey` 为唯一标识字段（如 `id`）
+- 列表格使用 `pagination` 属性控制分页
+- 长列表开启 `virtual` 虚拟滚动（>= 1000 行）
+- 空数据使用 `locale.emptyText` 自定义空状态提示
+- 后端分页使用 `onChange` 回调 + `pagination.current/pageSize` 受控
+
+```tsx
+<Table
+  dataSource={users}
+  columns={columns}
+  rowKey="id"
+  loading={loading}
+  pagination={{
+    current: page,
+    pageSize: 20,
+    total,
+    showSizeChanger: true,
+    showTotal: (total) => `共 ${total} 条`,
+  }}
+  onChange={(pagination) => {
+    setPage(pagination.current)
+    setPageSize(pagination.pageSize)
+  }}
+  locale={{ emptyText: <Empty description="暂无数据" /> }}
+/>
+```
+
+### Form（表单）
+- 使用 `layout="vertical"` 默认垂直布局
+- 所有校验规则集中在 `rules` 中定义，避免使用自定义 `validator`（除非复杂业务）
+- `Form.Item` 的 `name` 必须与提交数据结构的字段名一致
+- 编辑表单用 `form.setFieldsValue()` 填充初始值，不要用 `initialValues`
+- 全局校验信息通过 `ConfigProvider` 的 `form.validateMessages` 统一配置
+
+```tsx
+<Form
+  form={form}
+  layout="vertical"
+  onFinish={handleSubmit}
+  autoComplete="off"
+>
+  <Form.Item
+    name="email"
+    label="邮箱"
+    rules={[
+      { required: true, message: '请输入邮箱' },
+      { type: 'email', message: '邮箱格式不正确' },
+    ]}
+  >
+    <Input placeholder="请输入邮箱" />
+  </Form.Item>
+</Form>
+```
+
+### Modal（弹窗）
+- 表单弹窗用 `destroyOnClose` 确保关闭后重置状态
+- `afterClose` 用于关闭后的清理回调
+- 确认弹窗用 `Modal.confirm()` 快捷方法
+
+```tsx
+<Modal
+  title="编辑用户"
+  open={isOpen}
+  onOk={handleSave}
+  onCancel={handleCancel}
+  confirmLoading={saving}
+  destroyOnClose
+  afterClose={() => form.resetFields()}
+>
+  <UserForm form={form} user={editingUser} />
+</Modal>
+
+// 确认弹窗
+Modal.confirm({
+  title: '确认删除',
+  content: '确定要删除该用户吗？此操作不可恢复。',
+  okText: '确认删除',
+  okType: 'danger',
+  onOk: () => deleteUser(id),
+})
+```
+
+### Select（选择器）
+- 选项少时直接写 `<Select.Option>`；选项多时使用 `options` 数组属性
+- 远程搜索使用 `showSearch` + `onSearch` + `filterOption` 自定义
+- 多选用 `mode="multiple"`
+
+### DatePicker（日期选择器）
+- 使用 `format` 指定显示格式
+- 表单中配合 `Form.Item` 使用，值类型为 `dayjs` 对象
+- 范围选择用 `DatePicker.RangePicker`
+
+### Space（间距）
+- 组件间间距优先使用 `<Space>` 包裹，避免手动 `margin`
+- 默认间距为 `size="small"`（8px），可根据上下文调整
+
+### message / notification（消息提示）
+- 操作反馈使用 `message.success()` / `message.error()` 轻量提示
+- 重要通知使用 `notification.open()` / `notification.info()`
+- 不要在组件中手动创建 message 实例 — 使用静态方法即可
+
+### Spin（加载中）
+- 页面级加载使用 `Spin` 包裹内容区域
+- 组件级加载使用 Spin 组件的 `spinning` 属性
+- 全局加载状态使用 `Spin` + Suspense（React.lazy 场景）
+
+## 主题定制
+
+```tsx
+<ConfigProvider
+  theme={{
+    token: {
+      colorPrimary: '#1677ff',
+      borderRadius: 6,
+      colorBgContainer: '#ffffff',
+    },
+    components: {
+      Table: {
+        headerBg: '#fafafa',
+        rowHoverBg: '#f5f5f5',
+      },
+    },
+  }}
+>
+  <App />
+</ConfigProvider>
+```
+
+## Ant Design + Tailwind CSS 共存
+
+- Ant Design 负责组件内部样式，Tailwind 负责页面/组件外部的布局和间距
+- 避免在 Ant Design 组件上直接用 Tailwind 覆盖内联样式（Ant Design 的 CSS-in-JS 优先级高）
+- 布局使用 Tailwind 的 `flex`/`grid` 类 + Ant Design 的 `Row`/`Col` 搭配
+- 使用 Tailwind 的 `dark:` 变体时，需同时配置 Ant Design ConfigProvider 的 `theme.algorithm`（`darkAlgorithm`）
+
+## 性能注意
+
+- 大列表（>500 行）使用 Table 的 `virtual` 属性开启虚拟滚动
+- 大数据集的选择器使用 `virtual` 属性（Select + options 数量多时）
+- 避免频繁调用 `message`/`notification` — 使用 `message.destroy()` 或防抖