@deepstorm/cli 0.1.0 → 0.2.0

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

@@ -0,0 +1,353 @@
+# Ant Design Vue 实战示例
+
+## 完整数据表格（搜索 + 分页 + 操作列）
+
+```vue
+<!-- components/UserTable.vue -->
+<script setup lang="ts">
+import { ref, reactive, watch } from 'vue'
+import { message } from 'ant-design-vue'
+import type { User } from '@/shared/types/user'
+
+interface Filters {
+  search: string
+  role: string | undefined
+}
+
+const props = defineProps<{
+  users: User[]
+  total: number
+  loading: boolean
+}>()
+
+const emit = defineEmits<{
+  search: [filters: Filters]
+  pageChange: [page: number, pageSize: number]
+  edit: [user: User]
+  delete: [userId: string]
+}>()
+
+const filters = reactive<Filters>({
+  search: '',
+  role: undefined,
+})
+
+const pagination = reactive({
+  current: 1,
+  pageSize: 20,
+})
+
+// 列定义
+const columns = [
+  { title: '用户名', dataIndex: 'username', key: 'username' },
+  { title: '邮箱', dataIndex: 'email', key: 'email' },
+  { title: '角色', dataIndex: 'role', key: 'role' },
+  { title: '创建时间', dataIndex: 'createdAt', key: 'createdAt' },
+  {
+    title: '操作',
+    key: 'action',
+    customRender: ({ record }: { record: User }) => (
+      <span>
+        <a onClick={() => emit('edit', record)}>编辑</a>
+        <a-divider type="vertical" />
+        <a-popconfirm title="确定删除？" onConfirm={() => emit('delete', record.id)}>
+          <a>删除</a>
+        </a-popconfirm>
+      </span>
+    ),
+  },
+]
+
+// 搜索
+let searchTimer: ReturnType<typeof setTimeout>
+function handleSearch(value: string) {
+  clearTimeout(searchTimer)
+  searchTimer = setTimeout(() => {
+    filters.search = value
+    pagination.current = 1
+    emit('search', { ...filters })
+  }, 300)
+}
+
+// 分页变化
+function handleTableChange(pag: { current: number; pageSize: number }) {
+  pagination.current = pag.current
+  pagination.pageSize = pag.pageSize
+  emit('pageChange', pag.current, pag.pageSize)
+}
+
+// 批量删除
+const selectedRowKeys = ref<string[]>([])
+
+function handleBatchDelete() {
+  if (selectedRowKeys.value.length === 0) {
+    message.warning('请先选择要删除的用户')
+    return
+  }
+  Modal.confirm({
+    title: '批量删除',
+    content: `确定要删除选中的 ${selectedRowKeys.value.length} 名用户吗？`,
+    onOk: async () => {
+      // 批量删除逻辑
+      message.success(`已删除 ${selectedRowKeys.value.length} 名用户`)
+      selectedRowKeys.value = []
+    },
+  })
+}
+</script>
+
+<template>
+  <div class="space-y-4">
+    <!-- 搜索栏 -->
+    <div class="flex justify-between items-center">
+      <a-input-search
+        placeholder="搜索用户名/邮箱"
+        style="width: 300px"
+        @search="handleSearch"
+      />
+      <div class="flex gap-2">
+        <a-button
+          danger
+          :disabled="selectedRowKeys.length === 0"
+          @click="handleBatchDelete"
+        >
+          批量删除
+        </a-button>
+        <a-button type="primary">新增用户</a-button>
+      </div>
+    </div>
+
+    <!-- 表格 -->
+    <a-table
+      :data-source="users"
+      :columns="columns"
+      :loading="loading"
+      :pagination="{
+        ...pagination,
+        total,
+        showSizeChanger: true,
+        showTotal: (total: number) => `共 ${total} 条`,
+      }"
+      :row-selection="{
+        selectedRowKeys,
+        onChange: (keys: string[]) => { selectedRowKeys = keys },
+      }"
+      row-key="id"
+      :locale="{ emptyText: '暂无用户数据' }"
+      @change="handleTableChange"
+    />
+  </div>
+</template>
+```
+
+## 表单模态框（创建/编辑）
+
+```vue
+<!-- components/UserFormModal.vue -->
+<script setup lang="ts">
+import { reactive, ref, watch } from 'vue'
+import { message, Modal } from 'ant-design-vue'
+import type { User } from '@/shared/types/user'
+
+interface FormData {
+  username: string
+  email: string
+  displayName: string
+  role: string
+  active: boolean
+}
+
+const props = defineProps<{
+  visible: boolean
+  user: User | null  // null 表示创建模式
+}>()
+
+const emit = defineEmits<{
+  close: []
+  saved: []
+}>()
+
+const formRef = ref()
+const loading = ref(false)
+const isEdit = ref(false)
+
+const formData = reactive<FormData>({
+  username: '',
+  email: '',
+  displayName: '',
+  role: 'EDITOR',
+  active: true,
+})
+
+// 编辑模式填充数据
+watch(() => props.user, (user) => {
+  isEdit.value = !!user
+  if (user) {
+    formData.username = user.username
+    formData.email = user.email
+    formData.displayName = user.displayName
+    formData.role = user.role
+    formData.active = user.active
+  } else {
+    formData.username = ''
+    formData.email = ''
+    formData.displayName = ''
+    formData.role = 'EDITOR'
+    formData.active = true
+  }
+}, { immediate: true })
+
+const rules = {
+  username: [
+    { required: true, message: '请输入用户名', trigger: 'blur' },
+    { min: 3, max: 20, message: '用户名长度 3-20 个字符', trigger: 'blur' },
+  ],
+  email: [
+    { required: true, message: '请输入邮箱', trigger: 'blur' },
+    { type: 'email', message: '请输理有效的邮箱地址', trigger: 'blur' },
+  ],
+  displayName: [
+    { required: true, message: '请输入显示名称', trigger: 'blur' },
+  ],
+  role: [
+    { required: true, message: '请选择角色', trigger: 'change' },
+  ],
+}
+
+async function handleOk() {
+  try {
+    await formRef.value?.validate()
+    loading.value = true
+
+    const url = isEdit.value ? `/api/v1/users/${props.user!.id}` : '/api/v1/users'
+    const method = isEdit.value ? 'PUT' : 'POST'
+
+    const res = await fetch(url, {
+      method,
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(formData),
+    })
+
+    if (!res.ok) throw new Error(isEdit.value ? '更新失败' : '创建失败')
+
+    message.success(isEdit.value ? '更新成功' : '创建成功')
+    emit('saved')
+  } catch (e) {
+    if (e instanceof Error) {
+      message.error(e.message)
+    }
+  } finally {
+    loading.value = false
+  }
+}
+
+function handleCancel() {
+  emit('close')
+}
+</script>
+
+<template>
+  <a-modal
+    :visible="visible"
+    :title="isEdit ? '编辑用户' : '新建用户'"
+    :confirm-loading="loading"
+    destroy-on-close
+    @ok="handleOk"
+    @cancel="handleCancel"
+  >
+    <a-form
+      ref="formRef"
+      :model="formData"
+      :rules="rules"
+      :label-col="{ span: 6 }"
+      :wrapper-col="{ span: 16 }"
+    >
+      <a-form-item label="用户名" name="username">
+        <a-input
+          v-model:value="formData.username"
+          :disabled="isEdit"
+          placeholder="请输入用户名"
+        />
+      </a-form-item>
+
+      <a-form-item label="邮箱" name="email">
+        <a-input v-model:value="formData.email" placeholder="请输入邮箱" />
+      </a-form-item>
+
+      <a-form-item label="显示名称" name="displayName">
+        <a-input v-model:value="formData.displayName" placeholder="请输入显示名称" />
+      </a-form-item>
+
+      <a-form-item label="角色" name="role">
+        <a-select v-model:value="formData.role">
+          <a-select-option value="ADMIN">管理员</a-select-option>
+          <a-select-option value="EDITOR">编辑</a-select-option>
+          <a-select-option value="VIEWER">查看者</a-select-option>
+        </a-select>
+      </a-form-item>
+
+      <a-form-item label="状态" name="active">
+        <a-switch v-model:checked="formData.active" />
+      </a-form-item>
+    </a-form>
+  </a-modal>
+</template>
+```
+
+## 响应式布局仪表板
+
+```vue
+<!-- views/Dashboard.vue -->
+<script setup lang="ts">
+import { ref, onMounted } from 'vue'
+
+const stats = ref([
+  { title: '用户总数', value: 1284, icon: 'users' },
+  { title: '今日活跃', value: 356, icon: 'activity' },
+  { title: '待处理工单', value: 23, icon: 'clock' },
+  { title: '系统消息', value: 7, icon: 'message' },
+])
+</script>
+
+<template>
+  <div class="p-6 space-y-6">
+    <!-- 统计卡片 -->
+    <a-row :gutter="[16, 16]">
+      <a-col :xs="24" :sm="12" :lg="6" v-for="stat in stats" :key="stat.title">
+        <a-card hoverable>
+          <div class="flex items-center justify-between">
+            <div>
+              <p class="text-gray-500 text-sm">{{ stat.title }}</p>
+              <p class="text-2xl font-bold mt-1">{{ stat.value }}</p>
+            </div>
+            <div class="text-3xl text-blue-500">
+              <!-- 根据 stat.icon 渲染对应图标 -->
+            </div>
+          </div>
+        </a-card>
+      </a-col>
+    </a-row>
+
+    <!-- 图表区域 -->
+    <a-row :gutter="[16, 16]">
+      <a-col :xs="24" :lg="16">
+        <a-card title="访问趋势">
+          <div style="height: 300px">
+            <!-- 图表组件 -->
+          </div>
+        </a-card>
+      </a-col>
+      <a-col :xs="24" :lg="8">
+        <a-card title="最近操作">
+          <a-timeline>
+            <a-timeline-item color="green">新建用户 alice</a-timeline-item>
+            <a-timeline-item color="blue">更新配置</a-timeline-item>
+            <a-timeline-item color="red">删除过期数据</a-timeline-item>
+            <a-timeline-item>系统备份完成</a-timeline-item>
+          </a-timeline>
+        </a-card>
+      </a-col>
+    </a-row>
+  </div>
+</template>
+```

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

@@ -0,0 +1,267 @@
+# Ant Design Vue 4.x 组件使用规范
+
+## 通用原则
+
+- Ant Design Vue 4.x 兼容 Vue 3，组件需通过 `unplugin-vue-components` 配合 `AntDesignVueResolver` 实现自动按需导入
+- 模板中使用 `a-` 前缀组件：`<a-button>`、`<a-table>`、`<a-form>`
+- 程序化 API（`message`、`Modal`、`notification`）需从 `ant-design-vue` 包手动导入
+- 主题定制通过 `<a-config-provider>` 的 `:theme` 属性配置
+- 本地化通过 `<a-config-provider>` 的 `:locale` 属性设置，导入 `ant-design-vue/es/locale/zh_CN`
+
+### Vite 自动导入配置
+
+```typescript
+// vite.config.ts
+import Components from 'unplugin-vue-components/vite'
+import { AntDesignVueResolver } from 'unplugin-vue-components/resolvers'
+
+export default {
+  plugins: [
+    Components({
+      resolvers: [AntDesignVueResolver()],
+    }),
+  ],
+}
+```
+
+## 常用组件规范
+
+### Button（按钮）
+- 主要操作使用 `type="primary"`，次要操作默认
+- 危险操作使用 `danger` 属性
+- 异步操作必须设置 `:loading` 状态防重复提交
+- 纯图标按钮必须有 `aria-label` 提供无障碍说明
+
+```vue
+<a-button type="primary" :loading="submitting" @click="handleSubmit">
+  提交
+</a-button>
+<a-button danger @click="handleDelete">删除</a-button>
+<a-button aria-label="搜索">
+  <template #icon><SearchOutlined /></template>
+</a-button>
+```
+
+### Table（表格）
+- 始终指定 `row-key` 为唯一标识字段（如 `id`）
+- 列表格使用 `:pagination` 属性控制分页
+- 空数据使用 `:locale` 自定义空状态提示：`{ emptyText: '暂无数据' }`
+- 后端分页使用 `@change` 事件 + `:pagination.current/pageSize` 受控
+
+```vue
+<a-table
+  :data-source="users"
+  :columns="columns"
+  row-key="id"
+  :loading="loading"
+  :pagination="{
+    current: page,
+    pageSize: 20,
+    total,
+    showSizeChanger: true,
+    showTotal: (total: number) => `共 ${total} 条`,
+  }"
+  @change="(pagination: any) => {
+    page = pagination.current
+    pageSize = pagination.pageSize
+  }"
+  :locale="{ emptyText: '暂无数据' }"
+/>
+```
+
+### Form（表单）
+- 使用 `layout="vertical"` 默认垂直布局
+- 所有校验规则集中在 `:rules` 中定义，避免使用自定义 validator（除非复杂业务）
+- `<a-form-item>` 的 `name` 必须与提交数据结构的字段名一致
+- 编辑表单用 `ref.value?.setFieldsValue()` 填充初始值
+- 表单数据通过 `v-model:value` 双向绑定
+- 获取表单引用：`const formRef = ref()`
+
+```vue
+<script setup lang="ts">
+import { reactive, ref } from 'vue'
+
+const formState = reactive({
+  email: '',
+  name: '',
+})
+const formRef = ref()
+
+const rules = {
+  email: [
+    { required: true, message: '请输入邮箱', trigger: 'blur' },
+    { type: 'email', message: '邮箱格式不正确', trigger: 'blur' },
+  ],
+  name: [
+    { required: true, message: '请输入姓名', trigger: 'blur' },
+  ],
+}
+
+async function handleSubmit() {
+  try {
+    await formRef.value?.validate()
+    // 提交逻辑
+  } catch (e) {
+    // 校验失败
+  }
+}
+</script>
+
+<template>
+  <a-form
+    ref="formRef"
+    :model="formState"
+    :rules="rules"
+    layout="vertical"
+    @finish="handleSubmit"
+  >
+    <a-form-item name="email" label="邮箱">
+      <a-input v-model:value="formState.email" placeholder="请输入邮箱" />
+    </a-form-item>
+  </a-form>
+</template>
+```
+
+### Modal（弹窗）
+- 表单弹窗用 `destroy-on-close` 确保关闭后重置状态
+- `@cancel` 用于关闭回调
+- 确认弹窗用 `Modal.confirm()` 快捷方法
+
+```vue
+<a-modal
+  title="编辑用户"
+  :visible="isOpen"
+  @ok="handleSave"
+  @cancel="handleCancel"
+  :confirm-loading="saving"
+  destroy-on-close
+>
+  <UserForm :user="editingUser" />
+</a-modal>
+
+<!-- 程序化确认弹窗 -->
+<script setup lang="ts">
+import { Modal } from 'ant-design-vue'
+
+Modal.confirm({
+  title: '确认删除',
+  content: '确定要删除该用户吗？此操作不可恢复。',
+  okText: '确认删除',
+  okType: 'danger',
+  onOk: () => deleteUser(id),
+})
+</script>
+```
+
+### Select（选择器）
+- 选项少时直接写 `<a-select-option>`；选项多时使用 `:options` 数组属性
+- 远程搜索使用 `show-search` + `@search` + `:filter-option` 自定义
+- 多选用 `mode="multiple"`
+- 使用 `v-model:value` 双向绑定
+
+```vue
+<a-select v-model:value="formState.role" placeholder="请选择角色">
+  <a-select-option value="ADMIN">管理员</a-select-option>
+  <a-select-option value="EDITOR">编辑</a-select-option>
+</a-select>
+
+<!-- 远程搜索 -->
+<a-select
+  v-model:value="selectedUser"
+  show-search
+  :filter-option="false"
+  @search="handleSearch"
+>
+  <a-select-option v-for="u in users" :key="u.id" :value="u.id">
+    {{ u.username }}
+  </a-select-option>
+</a-select>
+```
+
+### DatePicker（日期选择器）
+- 使用 `format` 指定显示格式
+- 表单中配合 `<a-form-item>` 使用，值类型为 `dayjs` 对象
+- 使用 `v-model:value` 双向绑定
+- 范围选择用 `<a-range-picker>`
+
+```vue
+<a-date-picker v-model:value="date" format="YYYY-MM-DD" />
+<a-range-picker v-model:value="dateRange" format="YYYY-MM-DD" />
+```
+
+### Space（间距）
+- 组件间间距优先使用 `<a-space>` 包裹，避免手动 `margin`
+- 默认间距为 `size="small"`（8px），可根据上下文调整
+
+### message / notification（消息提示）
+- 需从 `ant-design-vue` 包手动导入
+- 操作反馈使用 `message.success()` / `message.error()` 轻量提示
+- 重要通知使用 `notification.open()` / `notification.info()`
+
+```vue
+<script setup lang="ts">
+import { message } from 'ant-design-vue'
+
+function handleSuccess() {
+  message.success('操作成功')
+}
+
+function handleError() {
+  message.error('操作失败')
+}
+</script>
+```
+
+### Spin（加载中）
+- 页面级加载使用 `<a-spin>` 包裹内容区域
+- 组件级加载使用 Spin 组件的 `:spinning` 属性
+
+```vue
+<a-spin :spinning="loading">
+  <div>内容区域</div>
+</a-spin>
+```
+
+## 主题定制
+
+```vue
+<template>
+  <a-config-provider
+    :locale="zhCN"
+    :theme="{
+      token: {
+        colorPrimary: '#1677ff',
+        borderRadius: 6,
+      },
+      components: {
+        Table: {
+          headerBg: '#fafafa',
+          rowHoverBg: '#f5f5f5',
+        },
+      },
+    }"
+  >
+    <RouterView />
+  </a-config-provider>
+</template>
+
+<script setup lang="ts">
+import zhCN from 'ant-design-vue/es/locale/zh_CN'
+import dayjs from 'dayjs'
+import 'dayjs/locale/zh-cn'
+
+dayjs.locale('zh-cn')
+</script>
+```
+
+## Ant Design Vue + Tailwind CSS 共存
+
+- Ant Design Vue 负责组件内部样式，Tailwind 负责页面/组件外部的布局和间距
+- 避免在 Ant Design Vue 组件上直接用 Tailwind 覆盖内联样式
+- 布局使用 Tailwind 的 `flex`/`grid` 类 + `<a-row>` / `<a-col>` 搭配
+- 使用 Tailwind 的 `dark:` 变体时，需同时配置 `a-config-provider` 的暗色主题
+
+## 性能注意
+
+- 大列表（>500 行）考虑分页或虚拟滚动
+- 避免频繁调用 `message` / `notification`