@qilitt-mickey/vue3-temp-skill 1.0.8

package/references/mobile-h5.md

@@ -0,0 +1,271 @@
+---
+skill: mobile-h5
+description: 规范移动端 H5 页面开发、Vant 组件使用、微信 JS-SDK 集成和移动端路由配置。开发移动端页面或微信相关功能时调用。
+scope: project
+tags: [vue3, mobile, h5, vant, wechat, miniprogram, responsive, touch]
+---
+
+# 移动端 H5 与微信开发规范
+
+## 移动端页面结构
+
+### 页面目录
+
+移动端页面放在 `src/views/mobile/` 下，与 PC 端页面隔离：
+
+```
+src/views/mobile/
+├── index/
+│   └── index.vue       # 移动端首页
+├── customer/
+│   └── index.vue       # 客户列表
+├── order/
+    └── index.vue       # 订单列表
+└── profile/
+    └── index.vue       # 个人中心
+```
+
+### 移动端路由
+
+移动端路由独立配置在 `src/router/mobile.ts`：
+
+```typescript
+export default {
+  path: "/m",
+  component: MobileLayout,
+  children: [
+    {
+      path: "/m/index",
+      name: "MobileIndex",
+      component: () => import("@/views/mobile/index/index.vue"),
+      meta: { title: "首页" },
+    },
+    {
+      path: "/m/customer",
+      name: "MobileCustomer",
+      component: () => import("@/views/mobile/customer/index.vue"),
+      meta: { title: "客户" },
+    },
+  ],
+} satisfies RouteConfigsTable;
+```
+
+### 移动端布局
+
+```vue
+<!-- src/layout/mobile.vue -->
+<template>
+  <div class="mobile-layout">
+    <router-view />
+    <van-tabbar v-model="active" route>
+      <van-tabbar-item to="/m/index" icon="home-o">首页</van-tabbar-item>
+      <van-tabbar-item to="/m/customer" icon="friends-o">客户</van-tabbar-item>
+      <van-tabbar-item to="/m/profile" icon="user-o">我的</van-tabbar-item>
+    </van-tabbar>
+  </div>
+</template>
+```
+
+## Vant 组件使用规范
+
+### 列表页（触底加载）
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { getCustomerListApi } from "@/api/customer";
+
+defineOptions({ name: "MobileCustomer" });
+
+const list = ref<CustomerItem[]>([]);
+const loading = ref(false);
+const finished = ref(false);
+const page = ref(1);
+const pageSize = 10;
+
+async function onLoad() {
+  loading.value = true;
+  try {
+    const { data } = await getCustomerListApi({ page: page.value, pageSize });
+    if (data.list.length < pageSize) {
+      finished.value = true;
+    }
+    list.value.push(...data.list);
+    page.value++;
+  } finally {
+    loading.value = false;
+  }
+}
+
+function onRefresh() {
+  list.value = [];
+  page.value = 1;
+  finished.value = false;
+  onLoad();
+}
+</script>
+
+<template>
+  <div class="re-mobile-customer">
+    <van-pull-refresh v-model="loading" @refresh="onRefresh">
+      <van-list
+        v-model:loading="loading"
+        :finished="finished"
+        finished-text="没有更多了"
+        @load="onLoad"
+      >
+        <div
+          v-for="item in list"
+          :key="item.id"
+          class="card-base mb-3 p-3"
+          @click="goDetail(item.id)"
+        >
+          <div class="flex-between mb-2">
+            <span class="font-bold">{{ item.name }}</span>
+            <van-tag :type="item.status ? 'success' : 'danger'">
+              {{ item.status ? "活跃" : "沉默" }}
+            </van-tag>
+          </div>
+          <div class="text-sm text-gray-500">{{ item.phone }}</div>
+        </div>
+      </van-list>
+    </van-pull-refresh>
+  </div>
+</template>
+```
+
+### 表单页
+
+```vue
+<template>
+  <div class="re-mobile-form">
+    <van-form
+      ref="formRef"
+      :model="formData"
+      :rules="formRules"
+      label-width="5em"
+    >
+      <van-field
+        v-model="formData.name"
+        label="姓名"
+        placeholder="请输入姓名"
+        :rules="[{ required: true, message: '请输入姓名' }]"
+      />
+      <van-field
+        v-model="formData.phone"
+        label="手机号"
+        type="tel"
+        placeholder="请输入手机号"
+        :rules="[{ required: true, message: '请输入手机号' }]"
+      />
+      <van-field
+        v-model="formData.remark"
+        label="备注"
+        type="textarea"
+        rows="3"
+        placeholder="请输入备注"
+      />
+    </van-form>
+
+    <div class="p-4">
+      <van-button type="primary" block :loading="loading" @click="handleSubmit">
+        保存
+      </van-button>
+    </div>
+  </div>
+</template>
+```
+
+### 选择器
+
+```vue
+<!-- 移动端下拉选择：使用 van-popup + van-picker -->
+<van-field
+  v-model="selectedLabel"
+  is-link
+  readonly
+  label="类型"
+  placeholder="请选择"
+  @click="showPicker = true"
+/>
+<van-popup v-model:show="showPicker" position="bottom">
+  <van-picker
+    :columns="options"
+    @confirm="onPickerConfirm"
+    @cancel="showPicker = false"
+  />
+</van-popup>
+```
+
+### Vant 组件约定
+
+1. 移动端列表使用 `van-list` + 触底加载，不使用分页组件。
+2. 下拉刷新使用 `van-pull-refresh` 包裹列表。
+3. 选择器使用 `van-popup` + `van-picker` 弹出，不使用内联选择。
+4. 表单使用 `van-form` + `van-field`，校验规则与 PC 端保持一致。
+5. 弹窗确认使用 `showConfirmDialog`，提示使用 `showToast`。
+6. 导航使用底部 `van-tabbar`，不使用侧边栏。
+
+## 微信 JS-SDK 集成
+
+### useWechat Hook
+
+```typescript
+import { useWechat } from "@/hooks/modules/useWechat";
+
+const {
+  initWechat,       // 初始化微信配置
+  shareToWechat,    // 设置分享
+  chooseImage,      // 选择图片
+  uploadImage,      // 上传图片
+  getLocation,      // 获取位置
+  scanQRCode,       // 扫码
+  wx,               // wx 对象
+  isWechatBrowser,  // 是否微信浏览器
+} = useWechat();
+
+onMounted(async () => {
+  if (isWechatBrowser) {
+    await initWechat({
+      jsApiList: ["chooseImage", "uploadImage", "getLocation", "scanQRCode"],
+    });
+  }
+});
+```
+
+### 微信分享配置
+
+```typescript
+async function setupShare() {
+  await shareToWechat({
+    title: "页面标题",
+    desc: "页面描述",
+    link: window.location.href,
+    imgUrl: "https://example.com/share.png",
+  });
+}
+```
+
+### 微信约定
+
+1. 微信相关逻辑统一封装在 `useWechat` Hook 中。
+2. 先判断 `isWechatBrowser` 再调用微信 API。
+3. 微信 JS-SDK 配置通过后端接口获取签名。
+4. 分享配置在每个页面 `onMounted` 中设置。
+
+## 移动端通用约定
+
+1. 移动端页面放在 `src/views/mobile/` 下，路由前缀 `/m`。
+2. 使用 `useApp().isMobile` 判断设备类型，不要用 `window.innerWidth` 手动判断。
+3. 样式使用 `rem` 或 UnoCSS 原子类，不要使用固定 `px` 宽度。
+4. 触摸交互使用 Vant 内置手势，不要自己实现 touch 事件。
+5. 图片使用 `van-image` 组件，支持懒加载和占位图。
+6. 移动端不显示侧边栏菜单，使用底部 TabBar 导航。
+
+## 常见反例
+
+- 移动端使用 `el-table` 展示数据（应使用 `van-list` + 卡片）。
+- 移动端使用 `el-select` 做下拉选择（应使用 `van-popup` + `van-picker`）。
+- 不使用 `van-list` 触底加载而是一次性加载全部数据。
+- 在微信浏览器中直接调用微信 API 而不先 `wx.config`。
+- 移动端页面放在 `src/views/` 根目录与 PC 端混在一起。

package/references/permission-auth.md

@@ -0,0 +1,235 @@
+---
+skill: permission-auth
+description: 规范页面权限、按钮权限、自定义指令和 Hooks 的使用。在开发涉及权限控制、自定义指令或编写组合式函数时调用。
+scope: project
+tags: [vue3, permission, auth, directive, hooks, v-auth, role, access-control]
+---
+
+# 权限控制与自定义指令
+
+## 权限体系概览
+
+项目权限分为三个层级：
+
+| 层级 | 控制方式 | 说明 |
+|------|---------|------|
+| 页面级 | 路由 `meta.roles` | 控制菜单可见性和路由访问 |
+| 按钮级 | `v-auth` 指令 / `ReAuth` 组件 | 控制页面内按钮的显示/隐藏 |
+| 接口级 | 后端校验 | 前端只做展示控制，后端做安全校验 |
+
+## 页面级权限
+
+### 路由 meta.roles 配置
+
+```typescript
+// src/router/modules/system.ts
+export default {
+  path: "/system",
+  meta: { title: "系统管理" },
+  children: [
+    {
+      path: "/system/user",
+      name: "SystemUser",
+      component: () => import("@/views/system/user/index.vue"),
+      meta: {
+        title: "用户管理",
+        roles: ["admin", "editor"],  // 只有这些角色可以访问
+      },
+    },
+    {
+      path: "/system/config",
+      name: "SystemConfig",
+      component: () => import("@/views/system/config/index.vue"),
+      meta: {
+        title: "系统配置",
+        roles: ["admin"],  // 仅管理员可访问
+      },
+    },
+  ],
+} satisfies RouteConfigsTable;
+```
+
+### 路由守卫校验
+
+路由守卫在 `src/router/utils.ts` 中统一处理：
+
+1. 白名单路由（登录页、404 等）直接放行。
+2. 有 Token 但没有菜单数据时，调用接口获取菜单并 `addRoute` 动态注册。
+3. 每次路由跳转检查 `meta.roles`，无权限则跳转 403 页面。
+
+## 按钮级权限
+
+### v-auth 指令
+
+```vue
+<template>
+  <!-- 只有 admin 角色能看到这个按钮 -->
+  <el-button v-auth="['admin']" type="danger" @click="handleDelete">
+    删除
+  </el-button>
+
+  <!-- 多个角色任一匹配即可 -->
+  <el-button v-auth="['admin', 'editor']" @click="handleEdit">
+    编辑
+  </el-button>
+</template>
+```
+
+### ReAuth 组件
+
+当需要控制一整块区域时，使用 `ReAuth` 组件包裹：
+
+```vue
+<template>
+  <ReAuth :value="['admin']">
+    <div class="admin-only-section">
+      <!-- 仅管理员可见的内容 -->
+    </div>
+  </ReAuth>
+</template>
+```
+
+### 权限判断 Hook
+
+在 JS 逻辑中判断权限：
+
+```typescript
+import { useAuth } from "@/hooks/useAuth";
+
+const { hasAuth } = useAuth();
+
+function handleDelete() {
+  if (!hasAuth(["admin"])) {
+    ElMessage.warning("无权限操作");
+    return;
+  }
+  // 执行删除
+}
+```
+
+### 权限约定
+
+1. 按钮权限使用 `v-auth` 指令，不要手动 `v-if` 判断角色。
+2. 区域权限使用 `ReAuth` 组件包裹。
+3. JS 逻辑中的权限判断使用 `hasAuth()` 方法。
+4. 前端权限只做 UI 展示控制，后端接口必须同步校验权限。
+5. 权限数据来源：登录后获取用户角色列表，存储在 `usePermissionStore` 中。
+
+## 自定义指令
+
+### 指令文件结构
+
+```
+src/directives/
+├── index.ts        # 统一注册入口
+├── auth/
+│   └── index.ts    # v-auth 权限指令
+├── copy/
+│   └── index.ts    # v-copy 复制指令
+├── compare/
+│   └── index.ts    # v-compare 数据变更对比（见 data-compare 模块）
+└── autoFont/
+    └── index.ts    # v-auto-font 字体自适应指令
+```
+
+### v-auth 实现原理
+
+```typescript
+// src/directives/auth/index.ts
+import { usePermissionStoreHook } from "@/store/modules/permission";
+
+export const auth = {
+  mounted(el: HTMLElement, binding: DirectiveBinding<string[]>) {
+    const { value } = binding;
+    const userRoles = usePermissionStoreHook().roles;
+
+    if (value && value.length && !value.some(role => userRoles.includes(role))) {
+      el.parentNode?.removeChild(el);
+    }
+  },
+};
+```
+
+### v-copy / v-auto-font / v-compare
+
+- 复制与字体：见 **directives-advanced**
+- 数据变更对比：见 **data-compare**（不是数值条件显示指令）
+
+### 指令约定
+
+1. 自定义指令放在 `src/directives/` 下，每个指令一个目录。
+2. 指令在 `src/directives/index.ts` 中统一注册到 Vue 实例。
+3. 指令命名使用短横线格式：`v-auth`、`v-copy`、`v-auto-font`。
+4. 指令的逻辑尽量简洁，复杂逻辑抽取到工具函数中。
+
+## 组合式函数 (Hooks)
+
+### Hooks 文件结构
+
+```
+src/hooks/
+├── useApp.ts           # 应用级 Hook（isMobile、theme 等）
+├── useTableSearch.ts   # 查询列表页 Hook
+├── useAuth.ts          # 权限判断 Hook
+├── useDetail.ts        # 详情页 Hook
+└── modules/
+    └── useWechat.ts    # 微信相关 Hook
+```
+
+### useApp
+
+```typescript
+import { useApp } from "@/hooks/useApp";
+
+const {
+  isMobile,      // 是否移动端
+  theme,         // 当前主题（light/dark）
+  locale,        // 当前语言
+  toggleDark,    // 切换暗色模式
+} = useApp();
+```
+
+### useTableSearch
+
+```typescript
+import { useTableSearch } from "@/hooks/useTableSearch";
+
+const {
+  content,           // 表格数据
+  pagination,        // 分页信息
+  loading,           // 加载状态
+  handleSearch,      // 查询
+  handleReset,       // 重置
+  handlePageChange,  // 翻页
+  handleSizeChange,  // 切换每页条数
+} = useTableSearch(formQuery, apiFn, options);
+```
+
+### useDetail
+
+```typescript
+import { useDetail } from "@/hooks/useDetail";
+
+const {
+  detail,      // 详情数据
+  loading,     // 加载状态
+  loadDetail,  // 加载详情
+  isEdit,      // 是否编辑模式
+} = useDetail(detailApi, { idKey: "id" });
+```
+
+### Hooks 约定
+
+1. Hook 文件名使用 `use[Name].ts` 命名。
+2. Hook 必须返回类型明确的对象或方法。
+3. Hook 内部处理 loading、error 状态，组件只需消费结果。
+4. 不要在 Hook 中直接操作 DOM。
+5. 通用 Hook 放在 `src/hooks/`，模块专属 Hook 放在 `src/hooks/modules/`。
+
+## 常见反例
+
+- 使用 `v-if="roles.includes('admin')"` 手动判断权限而不使用 `v-auth`。
+- 在组件中直接调用权限 store 而不通过 `useAuth` Hook。
+- 自定义指令没有统一注册，散落在各组件中。
+- Hook 返回 `any` 类型或不声明返回类型。
+- 在 Hook 中操作 DOM（应使用 ref + 生命周期）。