dk-frontend-skills 1.0.2 → 1.0.3

package/.claude/settings.json

@@ -47,6 +47,10 @@
     "security-review": {
       "enabled": true,
       "description": "待变更代码安全审查"
+    },
+    "fe-biz-patterns": {
+      "enabled": true,
+      "description": "前端业务模式库，loading/滚动加载/导入导出/批量操作/表单联动/大列表渲染/Service层封装/Pinia Store模式/分页数据管理等常见业务场景"
     }
   },
   "always_apply_skills": [

package/.claude/skills/fe-biz-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fe-biz-patterns
-description: 前端业务模式库，收录 XiaoMa 在实际业务中沉淀的前端方案和最佳实践。当用户要求实现包含以下特征的功能时使用：滚动加载/无限滚动/触底加载、数据导入导出、批量操作、表单联动、权限控制、大列表渲染、文件上传、实时搜索、拖拽排序等常见前端业务场景。
+description: 前端业务模式库，收录 XiaoMa 在实际业务中沉淀的前端方案和最佳实践。当用户要求实现包含以下特征的功能时使用：loading/加载/加载态、滚动加载/无限滚动/触底加载、数据导入导出、批量操作、表单联动、权限控制、大列表渲染、文件上传、实时搜索、拖拽排序、Service层封装/请求层/axios封装、Pinia Store模式/状态管理/分页数据管理等常见前端业务场景。
 ---
 
 # 前端业务模式库
@@ -13,9 +13,12 @@ XiaoMa 实战沉淀的前端业务方案集合，覆盖日常开发中高频出
 
 | 方案 | 适用场景 | 参考文档 |
 |------|---------|---------|
+| 通用 loading 管理 | 表单提交、数据加载、异步操作的 loading 状态控制 | [use-loading.md](references/use-loading.md) |
 | 滚动触底自动加载 | 列表滚动加载更多、无限滚动、分页拉取 | [infinite-scroll.md](references/infinite-scroll.md) |
+| Service 层封装 | axios 实例封装、API 模块组织、拦截器管理、多 API 源隔离 | [service-layer.md](references/service-layer.md) |
+| Pinia Store 模式 | Setup Store 格局、分页数据管理、storeToRefs 解构规范 | [pinia-store.md](references/pinia-store.md) |
 
-> **使用方式**：根据用户需求匹配上方方案，点击对应链接阅读完整实现文档，按文档中的模式生成代码。
+> **使用方式**：根据用户需求匹配上方方案，点击对应链接阅读完整实现文档，按文档中的模式生成代码。选择方案后**必须向用户确认**再执行。
 
 ## 扩展指南
 

package/.claude/skills/fe-biz-patterns/references/infinite-scroll.md

@@ -25,7 +25,8 @@
 ## 自定义 Hook
 
 ```ts
-import { ref, onMounted, onUnmounted, type Ref } from 'vue'
+import { ref, nextTick, onMounted, onUnmounted, type Ref } from 'vue'
+import { useLoading } from '@/composables/useLoading'
 
 interface UseInfiniteScrollOptions<T> {
   /** 分页请求函数，返回当前页的数据数组。返回空数组时视为加载完毕 */
@@ -44,7 +45,7 @@ export function useInfiniteScroll<T>(options: UseInfiniteScrollOptions<T>) {
   const { fetcher, root, rootMargin = '100px', threshold = 0, immediate = true } = options
 
   const data = ref<T[]>([]) as Ref<T[]>
-  const loading = ref(false)
+  const { loading, withLoading } = useLoading()  // 详见 [use-loading.md](use-loading.md)
   const error = ref<Error | null>(null)
   const isFinished = ref(false)
   const page = ref(0)
@@ -57,28 +58,25 @@ export function useInfiniteScroll<T>(options: UseInfiniteScrollOptions<T>) {
   async function loadMore() {
     if (loading.value || isFinished.value) return
 
-    loading.value = true
     error.value = null
     const currentPage = page.value + 1
 
     try {
-      const res = await fetcher(currentPage)
-      // 卸载后丢弃结果
-      if (stopLoading) return
-
-      if (res.length === 0) {
-        isFinished.value = true
-      } else {
-        data.value.push(...res)
-        page.value = currentPage
-      }
+      await withLoading(async () => {
+        const res = await fetcher(currentPage)
+        // 卸载后丢弃结果
+        if (stopLoading) return
+
+        if (res.length === 0) {
+          isFinished.value = true
+        } else {
+          data.value.push(...res)
+          page.value = currentPage
+        }
+      })
     } catch (e) {
       if (stopLoading) return
       error.value = e as Error
-    } finally {
-      if (!stopLoading) {
-        loading.value = false
-      }
     }
   }
 
@@ -93,7 +91,6 @@ export function useInfiniteScroll<T>(options: UseInfiniteScrollOptions<T>) {
     page.value = 0
     isFinished.value = false
     error.value = null
-    loading.value = false
 
     if (immediate) {
       await loadMore()

package/.claude/skills/fe-biz-patterns/references/pinia-store.md

@@ -0,0 +1,174 @@
+# Pinia Store 封装方案
+
+## 概述
+
+基于 Pinia Setup Store（Composition API 风格）的状态管理方案。
+
+核心模式：
+1. **Setup Store 格局** — `defineStore` + Composition API，天然支持响应式
+2. **异步 action + loading 分离** — store 只管理数据，loading 状态交给 view 层的 `useLoading`
+3. **分页数据管理** — 首屏替换 / 翻页追加的通用模式
+
+## 目录结构
+
+```
+src/stores/
+  home.ts    -- 首页 store
+  city.ts    -- 城市 store
+```
+
+每个文件对应一个业务域，与 service/modules 一一对应。
+
+## Setup Store 格局
+
+```ts
+export const useHomeStore = defineStore('home', () => {
+  // --- 状态 ---
+  const xxx = ref<T>(...)
+
+  // --- 计算属性（可选） ---
+  const xxxName = computed(() => ...)
+
+  // --- 异步操作 ---
+  const fetchXxx = async () => {
+    const res = await getXxx()
+    xxx.value = res.data || []
+  }
+
+  // --- 同步操作 ---
+  const setXxx = (val: T) => { xxx.value = val }
+
+  return { xxx, xxxName, fetchXxx, setXxx }
+})
+```
+
+### 命名规范
+
+| 项目 | 规范 |
+|------|------|
+| Store 变量 | `use[Name]Store` |
+| Store ID | 小写英文，与文件名一致 |
+| 导出方式 | `export const`（统一使用命名导出） |
+| 状态 | `ref()` 定义原始数据 |
+| 派生 | `computed()` 定义计算属性 |
+| 异步操作 | `fetch` / `load` 前缀 |
+| 同步操作 | `set` / `select` 前缀，动词主导 |
+
+## 异步 Action 模式
+
+### 原则：Store 只管数据，不管 UI 状态
+
+store 中的异步函数只负责获取数据、更新状态，不管理 loading/error：
+
+```ts
+const fetchHotSuggests = async () => {
+  const res = await getHotSuggests()
+  hotSuggests.value = res.data || []
+}
+```
+
+View 层通过 `useLoading` 组合多个 action：
+
+```ts
+// Home.vue
+const { loading: initLoading, withLoading } = useLoading()
+
+onMounted(() => {
+  withLoading(async () => {
+    await fetchHotSuggests()
+    await fetchCategories()
+    await fetchHouseList()
+  })
+})
+```
+
+这样 store 保持纯数据逻辑，view 控制 UI 状态粒度（可以多个 action 共享一个 loading，也可以各自独立）。
+
+## 分页数据管理
+
+### 核心状态
+
+```ts
+const list = ref<T[]>([])      // 列表数据
+const currentPage = ref(1)      // 当前页码
+const hasMore = ref(true)       // 是否还有更多
+```
+
+### 加载函数
+
+```ts
+const fetchList = async (page: number = 1) => {
+  const res = await getList(page)
+  // 假设后端返回 { errcode: 0, data: [...] }
+  if (res.errcode === 0) {
+    if (page === 1) {
+      list.value = res.data || []          // 首页：替换
+    } else {
+      list.value.push(...(res.data || [])) // 翻页：追加
+    }
+    currentPage.value = page
+    hasMore.value = (res.data || []).length > 0
+  }
+}
+```
+
+### View 层使用
+
+```vue
+<script setup>
+const { list, currentPage, hasMore } = storeToRefs(store)
+const { fetchList } = store
+
+// 首次加载
+onMounted(() => fetchList())
+
+// 加载更多
+function onLoadMore() {
+  if (!hasMore.value) return
+  fetchList(currentPage.value + 1)
+}
+</script>
+
+<template>
+  <div v-for="item in list" :key="item.id">{{ item.name }}</div>
+  <div v-if="hasMore" @click="onLoadMore">加载更多</div>
+</template>
+```
+
+### 边界处理
+
+| 场景 | 处理 |
+|------|------|
+| 空数据 | `res.data || []` 保底，避免 `.push(undefined)` |
+| 已加载完毕 | `hasMore` 为 false 时拦截加载请求 |
+| 搜索条件变化 | 重置 page = 1，重新 fetchList |
+| 后端页码不从 1 开始 | 调整 `page === 1` 的判断逻辑 |
+
+## View 层消费 Store 的方式
+
+### 推荐：解构响应式状态 + 保留 action
+
+```ts
+import { useHomeStore } from '@/stores/home'
+import { storeToRefs } from 'pinia'
+
+const store = useHomeStore()
+// 响应式状态：必须用 storeToRefs 包裹，否则会丢失响应性
+const { hotSuggests, houseList, hasMore } = storeToRefs(store)
+// 非响应式方法/action：直接从 store 实例解构
+const { fetchHotSuggests, fetchHouseList } = store
+```
+
+### storeToRefs 规则
+
+| 类型 | 解构方式 | 原因 |
+|------|---------|------|
+| `ref` / `computed` | `storeToRefs(store)` | 保持响应性 |
+| 函数（action） | `store.xxx` 或解构 | 本身就是普通函数，无响应式问题 |
+| 普通值 | `store.xxx` | 非响应式属性 |
+
+## 注意事项
+
+1. **不要在 store 外直接修改 `storeToRefs` 的值**：`storeToRefs` 返回的是 ref，改 `xxx.value = ...` 会直接修改 store 状态。如果只是想取值不改值，用 `toRef(store, 'xxx')` 只读
+2. **避免 store 循环依赖**：Store A 调用 Store B 的 action 时，在 action 内部 `useXxxStore()`，不要在模块顶层调用
+3. **SSR 兼容**：`useStore()` 调用要在组件的 `setup` 或 `pinia` 实例已挂载后执行

package/.claude/skills/fe-biz-patterns/references/service-layer.md

@@ -0,0 +1,198 @@
+# Service 层封装方案
+
+## 概述
+
+基于 axios 的请求层封装，核心模式：
+
+1. **Request 类 + 单例** — 封装 axios 实例，统一配置和拦截器
+2. **按业务域拆分模块** — `modules/[domain].ts`，类型与函数共置
+3. **config 集中管理** — baseURL、超时、状态码映射统一维护
+
+## 目录结构
+
+```
+src/service/
+  index.ts           -- 统一导出
+  request/
+    config.ts        -- 配置集中管理
+    index.ts         -- Request 类（axios 封装）
+  modules/
+    home.ts          -- 首页 API
+    city.ts          -- 城市 API
+```
+
+## Request 类封装
+
+```ts
+class Request {
+  private instance: AxiosInstance
+
+  constructor() {
+    this.instance = axios.create({
+      baseURL: config.baseURL,
+      timeout: config.timeout,
+      headers: config.headers,
+    })
+  }
+
+  public get<T>(url, params?, options?): Promise<T>
+  public post<T>(url, data?, options?): Promise<T>
+  public put<T>(url, data?, options?): Promise<T>
+  public delete<T>(url, params?, options?): Promise<T>
+}
+
+export const request = new Request()
+```
+
+关键设计点：
+
+- **单例模式**：整个应用共享一个 Request 实例，避免重复创建
+- **泛型方法**：`get<T>` 返回 `Promise<T>`，调用方通过类型参数控制返回值类型
+- **RequestOptions**：扩展 `AxiosRequestConfig`，预留 `showLoading`、`showError` 等业务字段
+
+## 拦截器（可选启用）
+
+拦截器默认不激活，需要时显式调用 `request.enableInterceptors()`：
+
+```ts
+class Request {
+  /** 启用拦截器：token 注入 + 统一错误处理 */
+  enableInterceptors() {
+    // 请求拦截器：自动注入 token
+    this.instance.interceptors.request.use((config) => {
+      const token = localStorage.getItem('token')
+      if (token) {
+        config.headers.Authorization = `Bearer ${token}`
+      }
+      return config
+    })
+
+    // 响应拦截器：解包数据 + 统一错误提示
+    this.instance.interceptors.response.use(
+      (response) => {
+        const { code, message, data } = response.data
+        if (code === 0) return data  // 成功：直接返回业务数据
+        console.error('请求失败:', message)
+        return Promise.reject(new Error(message))
+      },
+      (error) => {
+        if (error.response) {
+          console.error(statusCodeMap[error.response.status] || '网络请求失败')
+        } else {
+          console.error('网络连接失败')
+        }
+        return Promise.reject(error)
+      },
+    )
+  }
+}
+```
+
+启用后，API 函数的写法会简化——不再需要手动解 `res.data`，因为响应拦截器已经解了一层。
+
+## Config 集中管理
+
+```ts
+// src/service/request/config.ts
+export interface RequestConfig {
+  baseURL: string
+  timeout: number
+  headers?: Record<string, string>
+}
+
+export const config: RequestConfig = {
+  baseURL: 'http://xxx/api',
+  timeout: 10000,
+  headers: { 'Content-Type': 'application/json' },
+}
+
+export const statusCodeMap: Record<number, string> = {
+  400: '请求参数错误',
+  401: '未授权，请登录',
+  403: '拒绝访问',
+  404: '请求地址不存在',
+  500: '服务器内部错误',
+}
+```
+
+多 API 源时，在 config 中添加对应配置对象，Request 类中用单独 instance 隔离：
+
+```ts
+export const mapConfig = {
+  baseURL: '/api/map',
+  key: 'xxx',
+}
+
+// request/index.ts
+class Request {
+  private mapInstance: AxiosInstance | null = null
+
+  public mapGet<T>(url, params?): Promise<T> {
+    if (!this.mapInstance) {
+      this.mapInstance = axios.create({ baseURL: mapConfig.baseURL, timeout: config.timeout })
+    }
+    return this.mapInstance.get(url, { params })
+  }
+}
+```
+
+## API 模块组织
+
+### 按业务域拆分
+
+```ts
+// src/service/modules/home.ts
+import { request } from '../request'
+
+// 类型定义与 API 函数共置
+export interface HouseListItem { /* ... */ }
+
+export const getHotSuggests = async () => {
+  const res = await request.get('/home/hotSuggests')
+  return res.data
+}
+
+export const getHouseList = async (page = 1) => {
+  const res = await request.get('/home/houselist', { page })
+  return res.data
+}
+```
+
+### 规则
+
+| 原则 | 说明 |
+|------|------|
+| 一域一文件 | 每个业务模块一个文件，命名与后端资源对应 |
+| 类型共置 | 接口响应类型定义在 API 函数同一文件，就近维护 |
+| 函数即接口 | 每个 API 导出一个 async 函数，参数即业务参数 |
+| 统一导出 | `service/index.ts` 只导出 request 实例和核心类型，modules 由消费方按需 import |
+
+## View 层消费方式
+
+```ts
+import { getHotSuggests } from '@/service/modules/home'
+
+onMounted(async () => {
+  const res = await getHotSuggests()
+  hotSuggests.value = res.data || []
+})
+```
+
+或通过 store 间接调用：
+
+```ts
+// store 中调用 service
+const fetchHotSuggests = async () => {
+  const res = await getHotSuggests()
+  hotSuggests.value = res.data || []
+}
+
+// view 中调用 store action
+onMounted(() => store.fetchHotSuggests())
+```
+
+## 注意事项
+
+1. **拦截器启用时机**：`enableInterceptors()` 应在应用初始化时（如 `main.ts`）调用一次，避免重复注册
+2. **响应拦截器副作用**：启用后 API 函数返回的是解包后的业务数据，而非完整 AxiosResponse，与之配套的 store 逻辑需要同步调整
+3. **泛型参数**：`request.get<T>` 的 `T` 只是类型标注，不会在运行时做校验，后端返回格式异常仍需前端容错

package/.claude/skills/fe-biz-patterns/references/use-loading.md

@@ -0,0 +1,114 @@
+# 通用 Loading 管理方案
+
+## 概述
+
+异步操作的 loading 状态管理是前端最基础的需求之一。`useLoading` 是一个极简的通用 loading 包装器，用最小的代码量解决 loading 状态控制问题。
+
+## 源码
+
+```ts
+// src/composables/useLoading.ts
+import { ref } from 'vue'
+
+export function useLoading(initial = false) {
+  const loading = ref(initial)
+
+  async function withLoading<T>(fn: () => Promise<T>): Promise<T> {
+    loading.value = true
+    try {
+      return await fn()
+    } finally {
+      loading.value = false
+    }
+  }
+
+  return { loading, withLoading }
+}
+```
+
+核心逻辑只有一行：执行前设 `true`，finally 中设回 `false`，保证无论成功还是失败 loading 都能复位。
+
+## 使用示例
+
+### 表单提交
+
+```vue
+<script setup lang="ts">
+const { loading, withLoading } = useLoading()
+
+const onSubmit = async () => {
+  await withLoading(() => updateUser(form.value))
+}
+</script>
+
+<template>
+  <van-button :loading="loading" @click="onSubmit">提交</van-button>
+</template>
+```
+
+### 初始数据加载
+
+```vue
+<script setup lang="ts">
+const { loading, withLoading } = useLoading(true)  // 初始就为 true
+
+onMounted(() => {
+  withLoading(async () => {
+    await fetchUserInfo()
+    await fetchPermissions()
+  })
+})
+</script>
+
+<template>
+  <BaseLoading :loading="loading" type="spinner" text="正在加载..." vertical />
+  <template v-if="!loading">
+    <!-- 主体内容 -->
+  </template>
+</template>
+```
+
+### 多个独立 loading（初始加载 + 加载更多）
+
+```vue
+<script setup lang="ts">
+// 首次加载
+const { loading: initLoading, withLoading: withInitLoading } = useLoading()
+// 加载更多
+const { loading: moreLoading, withLoading: withMoreLoading } = useLoading()
+
+const onLoadMore = () => {
+  withMoreLoading(() => fetchHouseList(page + 1))
+}
+
+onMounted(() => {
+  withInitLoading(async () => {
+    await fetchHotSuggests()
+    await fetchCategories()
+    await fetchHouseList()
+  })
+})
+</script>
+
+<template>
+  <!-- 首次加载用全屏 loading -->
+  <BaseLoading :loading="initLoading" type="spinner" vertical />
+  <!-- 加载更多只影响底部 -->
+  <div v-if="moreLoading">加载更多...</div>
+</template>
+```
+
+## 常见问题
+
+| 场景 | 处理方式 |
+|------|---------|
+| 重复点击提交 | `loading` 为 true 时按钮置灰 / `:loading` 属性，无需额外逻辑 |
+| 多个请求并行 | 需要分别管理 loading 时创建多个 `useLoading` 实例 |
+| 组件卸载 | 不影响，`withLoading` 的 finally 中赋值不会有问题（Vue 会处理） |
+| 需要 loading 之外的状态 | 搭配 `error`、`data` 等额外 ref 使用，`useLoading` 只负责 loading |
+
+## 注意事项
+
+1. **不要滥用**：简单的 Boolean 控制直接写模板里就行，不需要每个异步操作都抽成一个 composable
+2. **区分 loading 粒度**：页面级 loading 用一个实例，列表加载更多用另一个实例，互不干扰
+3. **`withLoading` 的返回值**：它返回的是 `fn()` 的 Promise 结果，可以用它链式处理后续逻辑

package/CLAUDE.md

@@ -1,6 +1,6 @@
 ---
 name: dk-engineer
-description: 幽默的沉稳靠谱秘书，专注于高质量代码输出和清晰的任务执行。
+description: 幽默的沉稳靠谱助手，专注于高质量代码输出和清晰的任务执行。
 ---
 
 # 开发助手配置说明

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dk-frontend-skills",
-  "version": "1.0.2",
-  "description": "dk-engineer - 幽默沉稳靠谱的 Claude Skills 配置包，一键注入 .claude/ 技能目录和 CLAUDE.md 人设配置",
+  "version": "1.0.3",
+  "description": "dk-engineer - 幽默沉稳靠谱的前端开发助手 Claude Skills 配置包，一键注入 .claude/ 技能目录和 CLAUDE.md 人设配置",
   "author": "XiaoMa",
   "license": "MIT",
   "private": false,