mdk-skills 2.2.1 → 2.2.2

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

@@ -0,0 +1,292 @@
+# 滚动触底自动加载方案
+
+## 概述
+
+列表页滚动到底部时自动加载下一页数据，是 B 端中最常见的需求之一。本方案提供一套开箱即用的实现，覆盖主流业务场景。
+
+## 核心思路
+
+采用 **IntersectionObserver** 监听一个不可见的"哨兵元素"，当该元素进入视口时触发加载。
+
+```
+┌──────────────────┐
+│    列表内容       │  ← 已加载的数据
+│    ...            │
+│    ...            │
+│  ┌──────────┐    │
+│  │ loading  │    │  ← 加载状态提示
+│  └──────────┘    │
+│  ▲ sentinel ◄────│── IntersectionObserver 监听此元素
+└──────────────────┘
+```
+
+> 为什么不用 scroll 事件？IntersectionObserver 性能更好、不触发重排、且不依赖滚动容器的具体滚动逻辑。
+
+## 自定义 Hook
+
+```ts
+import { ref, nextTick, onMounted, onUnmounted, type Ref } from 'vue'
+import { useLoading } from '@/hooks/useLoading'
+
+interface UseInfiniteScrollOptions<T> {
+  /** 分页请求函数，返回当前页的数据数组。返回空数组时视为加载完毕 */
+  fetcher: (page: number) => Promise<T[]>
+  /** 滚动容器，不传则默认使用 viewport */
+  root?: Ref<HTMLElement | null>
+  /** 触发加载的提前量，默认 '100px'（提前 100px 触发） */
+  rootMargin?: string
+  /** 阈值，默认 0 */
+  threshold?: number
+  /** 是否立即加载第一页，默认 true */
+  immediate?: boolean
+}
+
+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, withLoading } = useLoading()  // 详见 [use-loading.md](use-loading.md)
+  const error = ref<Error | null>(null)
+  const isFinished = ref(false)
+  const page = ref(0)
+  const sentinelRef = ref<HTMLElement | null>(null)
+
+  let observer: IntersectionObserver | null = null
+  let stopLoading = false  // 防止竞态：卸载或刷新时中断
+
+  /** 加载下一页 */
+  async function loadMore() {
+    if (loading.value || isFinished.value) return
+
+    error.value = null
+    const currentPage = page.value + 1
+
+    try {
+      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
+    }
+  }
+
+  /** 重置并重新加载 */
+  async function refresh() {
+    // 中断当前请求
+    stopLoading = true
+    await nextTick()
+    stopLoading = false
+
+    data.value = []
+    page.value = 0
+    isFinished.value = false
+    error.value = null
+
+    if (immediate) {
+      await loadMore()
+    }
+  }
+
+  /** 手动触发加载（对外暴露） */
+  function triggerLoadMore() {
+    loadMore()
+  }
+
+  function setupObserver() {
+    observer = new IntersectionObserver(
+      (entries) => {
+        if (entries[0]?.isIntersecting) {
+          loadMore()
+        }
+      },
+      {
+        root: root?.value ?? null,
+        rootMargin,
+        threshold,
+      }
+    )
+
+    if (sentinelRef.value) {
+      observer.observe(sentinelRef.value)
+    }
+  }
+
+  onMounted(() => {
+    setupObserver()
+    if (immediate) {
+      loadMore()
+    }
+  })
+
+  onUnmounted(() => {
+    stopLoading = true
+    observer?.disconnect()
+  })
+
+  return {
+    data,
+    loading,
+    error,
+    isFinished,
+    sentinelRef,
+    refresh,
+    loadMore: triggerLoadMore,
+  }
+}
+```
+
+## 组件中使用
+
+```vue
+<script setup lang="ts">
+import { useInfiniteScroll } from '@/composables/useInfiniteScroll'
+
+interface Item {
+  id: number
+  title: string
+}
+
+async function fetchList(page: number): Promise<Item[]> {
+  const res = await fetch(`/api/list?page=${page}&size=20`)
+  const json = await res.json()
+  return json.data  // 假设接口返回 { data: Item[], total: number }
+}
+
+const { data, loading, error, isFinished, sentinelRef, refresh } = useInfiniteScroll<Item>({
+  fetcher: fetchList,
+})
+</script>
+
+<template>
+  <div class="list-page">
+    <div class="list-header">
+      <button @click="refresh">刷新</button>
+    </div>
+
+    <div class="list-items">
+      <div v-for="item in data" :key="item.id" class="list-item">
+        {{ item.title }}
+      </div>
+    </div>
+
+    <!-- 加载状态 -->
+    <div v-if="loading && data.length === 0" class="status">首次加载中...</div>
+    <div v-if="loading && data.length > 0" class="status">加载更多...</div>
+
+    <!-- 错误状态 -->
+    <div v-if="error" class="status error">
+      加载失败：{{ error.message }}
+      <button @click="loadMore">重试</button>
+    </div>
+
+    <!-- 加载完成 -->
+    <div v-if="isFinished && data.length > 0" class="status">没有更多了</div>
+
+    <!-- 空数据 -->
+    <div v-if="!loading && data.length === 0 && isFinished" class="status empty">
+      暂无数据
+    </div>
+
+    <!-- 哨兵元素：当此元素进入视口时触发加载 -->
+    <div v-if="!isFinished" ref="sentinelRef" class="sentinel" />
+  </div>
+</template>
+
+<style scoped>
+.sentinel {
+  height: 1px;
+  pointer-events: none;
+}
+.status {
+  padding: 16px;
+  text-align: center;
+  color: #999;
+}
+.status.error {
+  color: #e74c3c;
+}
+</style>
+```
+
+## 适配不同场景
+
+### 场景 1：指定滚动容器
+
+在弹窗或固定高度的容器内滚动时：
+
+```vue
+<template>
+  <div ref="scrollContainer" class="scroll-container">
+    <div v-for="item in data" :key="item.id">{{ item.title }}</div>
+    <div ref="sentinelRef" />
+  </div>
+</template>
+
+<script setup lang="ts">
+const scrollContainer = ref<HTMLElement | null>(null)
+
+const { data, sentinelRef } = useInfiniteScroll<Item>({
+  fetcher: fetchList,
+  root: scrollContainer,
+  rootMargin: '50px',
+})
+</script>
+```
+
+### 场景 2：带搜索/筛选
+
+```vue
+<script setup lang="ts">
+const keyword = ref('')
+const categoryId = ref('')
+
+// 搜索条件变化时重置列表
+watch([keyword, categoryId], () => {
+  refresh()
+})
+
+const { data, ...rest } = useInfiniteScroll({
+  fetcher: (page) => fetchList({ page, keyword: keyword.value, categoryId: categoryId.value }),
+})
+</script>
+```
+
+### 场景 3：手动触发（适用于"点击加载更多"）
+
+```vue
+<template>
+  <div v-for="item in data" :key="item.id">{{ item.title }}</div>
+  <button v-if="!isFinished" @click="loadMore" :disabled="loading">
+    {{ loading ? '加载中...' : '点击加载更多' }}
+  </button>
+</template>
+```
+
+## 边界情况处理
+
+| 场景 | 处理方式 |
+|------|---------|
+| 快速滚动到低部 | IntersectionObserver 自带节流，无需额外处理 |
+| 组件卸载时请求未完成 | `stopLoading` 标志位丢弃回调结果，避免内存泄漏 |
+| 请求失败 | 捕获异常，显示错误状态，提供重试按钮 |
+| 接口返回空数组 | `isFinished` 置为 true，停止监听 |
+| 搜索条件变化 | `refresh()` 重置全部状态并重新加载 |
+| 上一次请求未完成时触发刷新 | `stopLoading` 中断旧请求 |
+| 列表已有数据时 loading 态 | 区分首次加载（全屏 loading）和加载更多（底部 loading） |
+
+## 注意事项
+
+1. **分页从 1 开始**：绝大多数后端接口分页从 1 开始，按需调整 `page.value + 1` 的写法
+2. **key 绑定**：列表渲染务必绑定 `:key`，避免 Vue 的 diff 问题
+3. **容器 overflow**：如果容器内滚动，需要设置 `overflow-y: auto` 和固定高度
+4. **数据量过大**：列表超过 1000 条建议配合虚拟滚动，不要单纯依赖无限加载

package/.claude/backups/20260510.150310/skills/v3-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/backups/20260510.150310/skills/v3-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` 只是类型标注，不会在运行时做校验，后端返回格式异常仍需前端容错