@deepstorm/cli 0.1.0 → 0.2.0

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

@@ -0,0 +1,224 @@
+# Vue 数据获取层 + 路由配置示例
+
+## 组合式函数（数据获取层）
+
+```typescript
+// composables/useUsers.ts
+import { ref, computed, watch } from 'vue'
+import type { User, PageResponse } from '@/shared/types/user'
+
+interface UseUsersOptions {
+  page?: number
+  size?: number
+  search?: string
+  role?: string
+}
+
+// 使用 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 = {}) {
+  const users = ref<User[]>([])
+  const total = ref(0)
+  const loading = ref(true)
+  const error = ref<Error | null>(null)
+  const refreshKey = ref(0)
+
+  async function fetchUsers() {
+    loading.value = true
+    error.value = null
+
+    try {
+      const res = await fetch(`/api/v1/users${buildQuery(options)}`)
+      if (!res.ok) throw new Error(`HTTP ${res.status}`)
+      const data: PageResponse<User> = await res.json()
+      users.value = data.content
+      total.value = data.totalElements
+    } catch (e) {
+      error.value = e as Error
+    } finally {
+      loading.value = false
+    }
+  }
+
+  watch([() => options.page, () => options.size, () => options.search, () => options.role, refreshKey], () => {
+    fetchUsers()
+  }, { immediate: true })
+
+  function refresh() {
+    refreshKey.value++
+  }
+
+  return { users, total, loading, error, refresh }
+}
+
+// 写操作组合式函数
+export function useCreateUser() {
+  const loading = ref(false)
+
+  async function create(data: CreateUserRequest): Promise<User> {
+    loading.value = true
+    try {
+      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}`)
+      return await res.json()
+    } finally {
+      loading.value = false
+    }
+  }
+
+  return { create, loading }
+}
+```
+
+## Pinia Store 示例
+
+```typescript
+// stores/auth.ts
+import { defineStore } from 'pinia'
+import { ref, computed } from 'vue'
+import type { User } from '@/shared/types/user'
+
+export const useAuthStore = defineStore('auth', () => {
+  // state
+  const user = ref<User | null>(null)
+  const token = ref<string | null>(localStorage.getItem('auth_token'))
+  const loading = ref(false)
+
+  // getters
+  const isAuthenticated = computed(() => !!token.value)
+  const isAdmin = computed(() => user.value?.role === 'ADMIN')
+
+  // actions
+  async function login(username: string, password: string) {
+    loading.value = true
+    try {
+      const res = await fetch('/api/v1/auth/login', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ username, password }),
+      })
+      const data = await res.json()
+      token.value = data.token
+      user.value = data.user
+      localStorage.setItem('auth_token', data.token)
+    } finally {
+      loading.value = false
+    }
+  }
+
+  function logout() {
+    user.value = null
+    token.value = null
+    localStorage.removeItem('auth_token')
+  }
+
+  return { user, token, loading, isAuthenticated, isAdmin, login, logout }
+})
+```
+
+## 路由配置
+
+```typescript
+// router/index.ts
+import { createRouter, createWebHistory } from 'vue-router'
+import { useAuthStore } from '@/stores/auth'
+
+const router = createRouter({
+  history: createWebHistory(import.meta.env.BASE_URL),
+  routes: [
+    {
+      path: '/',
+      name: 'dashboard',
+      component: () => import('@/views/Dashboard.vue'),
+      meta: { requiresAuth: true },
+    },
+    {
+      path: '/users',
+      name: 'users',
+      component: () => import('@/views/UserList.vue'),
+      meta: { requiresAuth: true },
+    },
+    {
+      path: '/users/new',
+      name: 'create-user',
+      component: () => import('@/views/CreateUser.vue'),
+      meta: { requiresAuth: true },
+    },
+    {
+      path: '/users/:id',
+      name: 'user-detail',
+      component: () => import('@/views/UserDetail.vue'),
+      meta: { requiresAuth: true },
+    },
+    {
+      path: '/login',
+      name: 'login',
+      component: () => import('@/views/Login.vue'),
+    },
+    {
+      path: '/:pathMatch(.*)*',
+      name: 'not-found',
+      component: () => import('@/views/NotFound.vue'),
+    },
+  ],
+})
+
+// 导航守卫
+router.beforeEach((to, from) => {
+  const auth = useAuthStore()
+  if (to.meta.requiresAuth && !auth.isAuthenticated) {
+    return { name: 'login', query: { redirect: to.fullPath } }
+  }
+})
+
+export default router
+```
+
+## 主应用入口
+
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import { ConfigProvider } from 'ant-design-vue'
+import zhCN from 'ant-design-vue/es/locale/zh_CN'
+import dayjs from 'dayjs'
+import 'dayjs/locale/zh-cn'
+
+dayjs.locale('zh-cn')
+</script>
+
+<template>
+  <ConfigProvider
+    :locale="zhCN"
+    :theme="{ token: { colorPrimary: '#1677ff', borderRadius: 6 } }"
+  >
+    <RouterView />
+  </ConfigProvider>
+</template>
+```
+
+```typescript
+// main.ts
+import { createApp } from 'vue'
+import { createPinia } from 'pinia'
+import App from './App.vue'
+import router from './router'
+
+const app = createApp(App)
+app.use(createPinia())
+app.use(router)
+app.mount('#app')
+```

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

@@ -0,0 +1,145 @@
+# 前端编码快速参考 (Vue 3)
+
+按需加载。仅当你需要编写对应组件类型时阅读相关章节。
+
+> **完整示例代码见 `examples/` 目录。** 已安装子维度的规范，通过该维度的 `{value}.md` 文件阅读。
+
+## 速查
+
+| 场景 | 决策 |
+| --- | --- |
+| 新建组件 | `<script setup lang="ts">` + `defineProps<Props>()` + 组合式 API |
+| 新建表单 | Ant Design Vue `<a-form>` + `v-model` + `:rules` 校验 |
+| 读数据 | 组合式函数（`useUsers`）封装 fetch/axios |
+| 写数据 | 组合式函数 + `ref()` loading/error/data 三态 |
+| 组合式函数职责 | 只负责业务逻辑和数据获取，不管理 UI 渲染 |
+| 路由 | 动态 `import()` + `createRouter` 懒加载 |
+
+## 新建组件
+
+```vue
+<script setup lang="ts">
+interface UserTableProps {
+  users: User[]
+  loading?: boolean
+  onSelect?: (user: User) => void
+}
+
+const props = defineProps<UserTableProps>()
+const emit = defineEmits<{
+  select: [user: User]
+}>()
+
+function handleClick(user: User) {
+  emit('select', user)
+}
+</script>
+
+<template>
+  <a-table
+    :data-source="props.users"
+    :loading="props.loading"
+    row-key="id"
+    @click="handleClick"
+  />
+</template>
+```
+
+| 规则 | 要求 |
+| --- | --- |
+| `<script setup lang="ts">` | 禁止 Options API，使用组合式 API |
+| `defineProps<Type>()` | 使用泛型语法定义 Props，`type` 定义联合类型 |
+| 状态提升 | 组件间共享状态提升到最近公共父组件，或使用 Pinia |
+| 默认导出 | 页面级组件使用 `export default`（路由组件），通用组件使用具名导出 |
+
+## 组合式 API 规则
+
+- **顶层调用**：`ref()`、`computed()`、`watch()` 等组合式 API 在 `<script setup>` 顶层调用，禁止在条件/循环中
+- **ref 默认首选**：优先使用 `ref()`，`reactive()` 仅用于不需要整体替换的固定结构对象
+- **生命周期**：注册的监听器和定时器必须在 `onUnmounted` 中清理
+- **组合式函数**：以 `use` 开头命名，返回值为对象
+
+```vue
+<script setup lang="ts">
+import { ref, onMounted, onUnmounted } from 'vue'
+
+const users = ref<User[]>([])
+const loading = ref(true)
+const error = ref<Error | null>(null)
+
+onMounted(async () => {
+  try {
+    const res = await fetch('/api/v1/users')
+    users.value = await res.json()
+  } catch (e) {
+    error.value = e as Error
+  } finally {
+    loading.value = false
+  }
+})
+</script>
+```
+
+## Ant Design Vue 组件
+
+- **自动按需导入**：通过 `unplugin-vue-components` 配合 `AntDesignVueResolver` 实现，模板中使用 `a-` 前缀（`<a-button>`、`<a-table>`）
+- **Form**：`<a-form-item>` 的 `name` 必须与数据模型字段一致，使用 `:rules` 定义校验
+- **Table**：必须指定 `row-key`，空数据时设置 `locale.emptyText`
+- **Modal**：关闭时使用 `destroyOnClose` 或 `@afterClose` 重置内部状态
+- **布局**：使用 `<a-row>` / `<a-col>` 栅格系统或 Flex 布局
+- **程序化 API**：`message.success()`、`Modal.confirm()` 等从 `ant-design-vue` 手动导入
+
+## 错误处理
+
+- 错误边界使用 `onErrorCaptured` 生命周期钩子捕获子组件异常
+- API 错误在组合式函数层捕获并暴露错误状态，UI 层通过 Ant Design Vue 组件展示反馈
+- 表单校验使用 Ant Design Vue Form 内置校验规则，非必要不自定义 validator
+- Error Boundary 组件使用 `<script setup>` + `onErrorCaptured` 实现
+
+## 路由
+
+- 所有页面组件使用动态 `import()` 实现懒加载
+- 路由配置集中定义在路由文件中，不在组件内嵌路由
+- 权限通过导航守卫（`beforeEach`）控制
+- 组件内路由操作使用 `useRouter()` / `useRoute()` 组合式函数
+
+```vue
+<script setup lang="ts">
+import { createRouter, createWebHistory } from 'vue-router'
+
+const router = createRouter({
+  history: createWebHistory(import.meta.env.BASE_URL),
+  routes: [
+    {
+      path: '/users',
+      name: 'users',
+      component: () => import('@/views/UserList.vue'),
+    },
+    {
+      path: '/users/:id',
+      name: 'user-detail',
+      component: () => import('@/views/UserDetail.vue'),
+    },
+  ],
+})
+</script>
+```
+
+## 代码风格
+
+- 控制流语句必须使用大括号，禁止无大括号的早期返回
+- 代码折行规则（90 列限制）详见 `examples/code-wrapping.md`
+- 模板属性超过 3 个时换行排列
+- 自闭合标签：无子元素时使用 `<Component />` 而非 `<Component></Component>`
+- 模板表达式保持简洁，复杂逻辑提取到 `<script setup>` 中
+
+## 常见坑
+
+| 场景 | 问题 | 正确做法 |
+|------|------|---------|
+| `reactive` 整体赋值 | 直接 `state = newVal` 破坏响应式 | 使用 `Object.assign()` 或改用 `ref()` |
+| `v-for` 缺少 `:key` | 列表渲染异常/性能下降 | 绑定唯一 `:key="item.id"` |
+| 响应式解构丢失 | `const { name } = reactive(obj)` 解构后 `name` 失去响应性 | 使用 `toRefs()` 或保持 `obj.name` 访问 |
+| 生命周期清理遗漏 | 事件监听/定时器在组件卸载后仍然运行 | `onUnmounted` 中清理 |
+| `watch` 旧值误用 | 以为 `watch` 第一个回调参数是新值 | 签名是 `watch(source, (newVal, oldVal) => ...)` |
+| Ant Design Vue 手动导入遗漏 | `message` / `Modal` 等程序化 API 未导入 | 从 `ant-design-vue` 包手动导入 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepstorm/cli",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "DeepStorm CLI — 一键配置项目开发环境",
   "license": "MIT",
   "author": "billkang",
@@ -12,6 +12,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.mjs && node dist/build-registry.js",
+    "publish": "node scripts/publish.mjs",
     "test": "vitest run --coverage",
     "prepublishOnly": "npm run build",
     "prepack": "npm run build"
@@ -19,6 +20,7 @@
   "dependencies": {
     "@clack/prompts": "^0.9.0",
     "commander": "^12.0.0",
+    "dotenv": "^17.4.2",
     "handlebars": "^4.7.8",
     "js-yaml": "^4.1.0"
   },