@qilitt-mickey/vue3-temp-skill 1.0.8

package/references/ui-components.md

@@ -0,0 +1,161 @@
+---
+skill: ui-components
+description: 规范 Re* 前缀自定义组件的目录结构、导出方式、类型定义和开发流程。在创建或修改公共组件时调用。
+scope: project
+tags: [vue3, component, re-component, library, typescript]
+---
+
+# Re* 自定义组件开发规范
+
+## 组件目录结构
+
+每个 Re 组件必须遵循以下目录结构：
+
+```
+src/components/RePagination/
+├── src/
+│   └── pagination.vue    # 组件实现文件
+├── index.ts              # 统一导出入口
+└── type.ts               # 类型定义（Props / Emits / Slots）
+```
+
+### 规则说明
+
+1. 组件目录使用大驼峰命名：`Re[ComponentName]`。
+2. 组件实现文件放在 `src/` 子目录下，使用短横线命名：`pagination.vue`。
+3. `index.ts` 是组件的唯一导出入口，外部通过 `import { RePagination } from "@/components/RePagination"` 引入。
+4. `type.ts` 集中定义 Props、Emits、Slots 类型。
+
+## 导出模式
+
+### index.ts 标准写法
+
+```typescript
+// src/components/RePagination/index.ts
+import pagination from "./src/pagination.vue";
+
+export const RePagination = pagination;
+export default RePagination;
+```
+
+### 多组件导出
+
+如果一个目录下有多个组件：
+
+```typescript
+// src/components/ReDialog/index.ts
+import dialog from "./src/dialog.vue";
+import dialogHeader from "./src/dialog-header.vue";
+
+export const ReDialog = dialog;
+export const ReDialogHeader = dialogHeader;
+export default ReDialog;
+```
+
+## 类型定义
+
+### type.ts 标准写法
+
+```typescript
+// src/components/RePagination/type.ts
+import type { ComponentPublicInstance } from "vue";
+
+export interface RePaginationProps {
+  /** 当前页码 */
+  currentPage: number;
+  /** 每页条数 */
+  pageSize: number;
+  /** 总条数 */
+  total: number;
+  /** 每页条数选项 */
+  pageSizes?: number[];
+  /** 是否显示总数 */
+  showTotal?: boolean;
+}
+
+export interface RePaginationEmits {
+  (e: "update:currentPage", page: number): void;
+  (e: "update:pageSize", size: number): void;
+  (e: "change", page: number, size: number): void;
+}
+
+export type RePaginationInstance = ComponentPublicInstance<RePaginationProps>;
+```
+
+### 类型约定
+
+1. Props 类型命名：`Re[ComponentName]Props`。
+2. Emits 类型命名：`Re[ComponentName]Emits`，使用函数签名格式。
+3. 如需在组件外部引用实例类型，导出 `Re[ComponentName]Instance`。
+4. 每个 Props 字段必须写 JSDoc 注释说明用途。
+
+## 组件实现模板
+
+```vue
+<script setup lang="ts">
+import type { ReComponentNameProps, ReComponentNameEmits } from "../../type";
+
+defineOptions({
+  name: "ReComponentName",
+});
+
+const props = withDefaults(defineProps<ReComponentNameProps>(), {
+  pageSizes: () => [10, 20, 50, 100],
+  showTotal: true,
+});
+
+const emit = defineEmits<ReComponentNameEmits>();
+
+function handleChange(page: number, size: number) {
+  emit("update:currentPage", page);
+  emit("update:pageSize", size);
+  emit("change", page, size);
+}
+</script>
+
+<template>
+  <div class="re-component-name">
+    <!-- 组件内容 -->
+  </div>
+</template>
+
+<style lang="scss" scoped>
+.re-component-name {
+  /* 样式 */
+}
+</style>
+```
+
+## 现有 Re 组件清单
+
+| 组件名 | 用途 | 关键特性 |
+|--------|------|----------|
+| ReDialog | 弹窗 | 拖拽、全屏、表单嵌套 |
+| RePagination | 分页 | 配合 useTableSearch |
+| ReTableBar | 表格工具栏 | 列配置、密度、全屏 |
+| ReGrid | 数据表格 | 基于 el-table 封装 |
+| ReTableOperate | 操作列 | 按钮组、权限控制 |
+| ReSelectQuery | 查询选择器 | 下拉+搜索+分页 |
+| ReCascader | 级联选择 | 支持异步加载 |
+| ReRichText | 富文本编辑器 | 基于 wangEditor |
+| ReQrcode | 二维码 | 支持 Logo 嵌入 |
+| ReBarcode | 条形码 | 多种编码格式 |
+| ReVerify | 验证码 | 图形/滑块/拖拽验证 |
+| ReSeamlessScroll | 无缝滚动 | 支持多方向 |
+| ReNoticeBar | 通知栏 | 滚动/关闭 |
+| ReIconPicker | 图标选择器 | 支持多图标库 |
+| ReSegmented | 分段控制器 | 自定义选项 |
+| ReCheckCard | 多选卡片 | 卡片式选择 |
+| ReTreeLine | 树形连线 | 树结构可视化 |
+| ReFlicker | 闪烁效果 | 数据大屏常用 |
+| ReTypeit | 打字效果 | 逐字显示动画 |
+| ReAuth | 权限组件 | 按钮级权限控制 |
+
+## 常见反例
+
+- 组件没有 `index.ts` 导出文件，外部直接引用 `.vue` 文件。
+- Props 类型内联在组件中，没有抽取到 `type.ts`。
+- 组件 `name` 没有使用 `defineOptions` 显式声明。
+- 样式没有使用 `scoped`，导致全局污染。
+- 组件 class 名没有使用 `re-` 前缀。
+- Props 字段没有 JSDoc 注释。

package/references/verify-captcha.md

@@ -0,0 +1,96 @@
+# 验证码与校验组件
+
+规范滑块拼图、拖拽验证、图片验证码、短信倒计时等校验组件的使用。在登录、敏感操作、防刷场景时参照。
+
+## 组件选型
+
+| 场景         | 组件            | 说明                     |
+| ------------ | --------------- | ------------------------ |
+| 滑块拼图弹窗 | `ReVerify`      | 基于 `vue3-puzzle-vcode` |
+| 拖拽滑块     | `ReDragVerify`  | 自定义拖拽验证条         |
+| 图片验证码   | `ReImageVerify` | canvas 随机字符          |
+| 短信验证码   | `ReSmsCode`     | 发送按钮 + 倒计时        |
+
+## ReVerify 滑块拼图
+
+```vue
+<script setup lang="ts">
+import ReVerify from "@/components/ReVerify";
+
+const verifyShow = ref(true);
+
+function onVerifyPass(success: boolean) {
+  console.log("验证通过", success);
+}
+</script>
+
+<template>
+  <ReVerify v-model:verify-show="verifyShow" @verify-pass="onVerifyPass" />
+</template>
+```
+
+## ReDragVerify 拖拽验证
+
+```vue
+<ReDragVerify
+  v-model:value="isPass"
+  width="100%"
+  :height="40"
+  :text="$t('请拖动滑块完成验证')"
+  :success-text="$t('验证成功')"
+  @success="onSuccess"
+/>
+```
+
+### Events
+
+- `success({ isPassing, time })`：验证通过，返回耗时（秒）。
+- `update:value`：同步验证状态。
+- `start` / `move` / `end`：拖拽生命周期。
+
+### Expose
+
+- `resume()`：重置验证条状态。
+
+## ReImageVerify 图片验证码
+
+```vue
+<script setup lang="ts">
+import ReImageVerify from "@/components/ReImageVerify";
+
+const code = ref("");
+const imgVerifyRef = ref();
+
+function refresh() {
+  imgVerifyRef.value?.getImgCode();
+}
+</script>
+
+<template>
+  <ReImageVerify ref="imgVerifyRef" v-model:code="code" @click="refresh" />
+</template>
+```
+
+## ReSmsCode 短信倒计时
+
+```vue
+<script setup lang="ts">
+import ReSmsCode from "@/components/ReSmsCode";
+
+const phone = ref("13800138000");
+</script>
+
+<template>
+  <ReSmsCode :phone="phone" :seconds="120" />
+</template>
+```
+
+- 内置手机号正则校验。
+- 发送成功后自动倒计时，按钮禁用期间不可重复点击。
+
+## 关键约定
+
+1. 滑块验证通过后通过 `update:verifyShow` 关闭弹窗，不要直接修改 prop。
+2. 图片验证码支持 `getImgCode()` 主动刷新。
+3. 短信验证码 `seconds` 默认 120 秒，按需调整。
+4. 校验组件仅做前端防刷，关键业务必须配合后端二次校验。

package/references/vue-core.md

@@ -0,0 +1,209 @@
+---
+skill: vue-core
+description: Vue 3 项目核心规范，涵盖技术栈、目录结构、组件开发标准、路由系统、状态管理和国际化。开发任何新功能或组件前必须参考此技能。
+scope: project
+tags: [vue3, typescript, vite, component, router, pinia, i18n, conventions]
+---
+
+# Vue 3 项目核心规范
+
+## 技术栈
+
+```typescript
+const techStack = {
+  vue: "3.5.x",
+  typescript: "6.x",
+  vite: "8.x",
+  elementPlus: "2.14.x",   // PC 端 UI
+  vant: "4.10.x",          // 移动端 UI
+  pinia: "3.x",
+  vueRouter: "5.x",
+  unocss: "66.x",
+  axios: "1.18.x",
+  vueI18n: "11.x",
+};
+```
+
+## 目录结构
+
+```
+src/
+├── api/          # API 接口（按业务模块分文件）
+├── components/   # 可复用组件（Re* 前缀）
+├── hooks/        # 组合式函数
+├── store/        # Pinia 状态管理（模块化）
+├── router/       # 路由配置（PC + 移动端）
+├── utils/        # 工具函数
+├── styles/       # 全局样式（SCSS + UnoCSS）
+├── views/        # 页面组件
+├── directives/   # 自定义指令
+├── layout/       # 布局系统
+└── locales/      # 国际化文件
+```
+
+## 组件开发规范
+
+### 命名规则
+
+- 全局自定义组件：`Re[ComponentName]`，如 `RePagination`、`ReDialog`。
+- 页面组件：放在 `views/[module]/index.vue`，`name` 使用大驼峰，如 `BaseTable`、`LoginPage`。
+- 组件 class 名：`re-[component-name]`，如 `.re-pagination`。
+
+### 标准模板
+
+```vue
+<script setup lang="ts">
+import type { ComponentNameProps, ComponentNameEmits } from "./type";
+
+defineOptions({
+  name: "ReComponentName",
+});
+
+const props = withDefaults(defineProps<ComponentNameProps>(), {
+  // 默认值
+});
+
+const emit = defineEmits<ComponentNameEmits>();
+
+// 组件逻辑
+</script>
+
+<template>
+  <div class="re-component-name">
+    <!-- 内容 -->
+  </div>
+</template>
+
+<style lang="scss" scoped>
+.re-component-name {
+  /* 组件样式 */
+}
+</style>
+```
+
+### 必须遵守
+
+1. 始终使用 `<script setup lang="ts">` + Composition API，禁止 Options API。
+2. `script` 标签第一行引入类型：`import type { ... } from "./type"`。
+3. 使用 `defineOptions` 显式声明组件 `name`。
+4. `props` 与 `emits` 的类型定义必须抽取到同目录 `type.ts` 文件。
+5. 样式使用 `lang="scss" scoped`；UnoCSS 原子类可直接写在 template 中。
+6. 系统常规组件（Element Plus / Vant）已自动引入，无需手动 `import`。
+7. 自定义 Re 组件需显式引入：`import { RePagination } from "@/components/RePagination"`。
+
+### 常见反例
+
+- 使用 Options API（`export default { data(), methods }`）。
+- `defineProps` 内直接写内联类型而不抽取到 `type.ts`。
+- 在组件中硬编码中文文案（应使用 `$t()` 国际化）。
+- 忘记写 `defineOptions({ name })` 导致 keep-alive 失效。
+
+## 路由系统
+
+### 静态路由模块格式
+
+```typescript
+export default {
+  path: "/system",
+  redirect: "/system/user",
+  meta: {
+    title: "系统管理",
+    icon: "ep:tools",
+    rank: 1,
+  },
+  children: [
+    {
+      path: "/system/user",
+      name: "SystemUser",
+      component: () => import("@/views/system/user/index.vue"),
+      meta: { title: "用户管理", roles: ["admin"] },
+    },
+  ],
+} satisfies RouteConfigsTable;
+```
+
+### 路由约定
+
+- 路由文件放在 `src/router/modules/` 下，按业务模块拆分。
+- `meta.rank` 控制菜单排序，数值越小越靠前。
+- `meta.roles` 控制页面级权限，不设置则表示无权限限制。
+- 动态路由通过后端接口返回，前端使用 `addRoute()` 动态注册。
+- 移动端路由放在 `src/router/mobile.ts`，与 PC 端隔离。
+
+## Pinia 状态管理
+
+### Store 模块格式
+
+```typescript
+import { defineStore } from "pinia";
+
+export const useUserStore = defineStore("user", {
+  state: () => ({
+    token: "",
+    userInfo: null as UserInfo | null,
+  }),
+
+  actions: {
+    setToken(token: string) {
+      this.token = token;
+    },
+    async login(params: LoginParams) {
+      const { data } = await http.request<Result<LoginResult>>(
+        "post", "/api/login", { data: params }
+      );
+      this.token = data.token;
+      this.userInfo = data.userInfo;
+    },
+    logout() {
+      this.$reset();
+    },
+  },
+
+  persist: {
+    key: "user-store",
+    storage: localStorage,
+    paths: ["token"],
+  },
+});
+
+// 组件外部使用的 Hook（保证在 setup 外也能获取 store 实例）
+export const useUserStoreHook = () => {
+  return useUserStore();
+};
+```
+
+### Store 约定
+
+- 文件名使用 `useXxxStore` 命名，如 `useUserStore.ts`。
+- 必须导出 `useXxxStoreHook()` 函数，供组件外部（如工具函数、路由守卫）调用。
+- 需要持久化的字段在 `persist.paths` 中声明。
+- 不要在 store 中直接操作 DOM 或调用路由方法。
+
+## 国际化 (i18n)
+
+### 使用方式
+
+```vue
+<template>
+  <el-button>{{ $t("buttons.submit") }}</el-button>
+</template>
+
+<script setup lang="ts">
+import { useI18n } from "vue-i18n";
+const { t } = useI18n();
+const label = t("system.title");
+</script>
+```
+
+### 约定
+
+- 所有用户可见文案必须通过 `$t()` 或 `t()` 引用。
+- 语言包文件放在 `src/locales/` 下，按模块拆分。
+- 开发阶段可先用中文 key 占位，后续替换为正式文案。
+- 避免使用 `more`、`view details` 等无业务语义的占位文案。
+
+## 通用原则
+
+- 仅在系统边界（用户输入、外部 API）做校验，不添加无意义的防御代码。
+- 新功能需同时考虑 PC 端与移动端兼容性。
+- 用户可见文案优先通过 i18n 或后端配置化提供。

package/references/websocket-realtime.md

@@ -0,0 +1,176 @@
+# WebSocket 实时通信
+
+## 架构
+
+项目封装了多实例 WebSocket 管理系统：
+
+```
+src/utils/websocket/
+├── index.ts    # 全局实例管理（init/close/get 函数）
+├── core.ts     # WebSocketManager 类（连接、重连、事件派发）
+└── types.ts    # 类型定义
+```
+
+业务层通过 `useWebSocket` Hook 接入。
+
+## useWebSocket Hook
+
+```typescript
+// src/hooks/useWebSocket.ts
+import { getWebSocketInstance } from '@/utils/websocket'
+
+export function useWebSocket(instanceName: string = 'default') {
+  const wsInstance = getWebSocketInstance(instanceName)
+  const isConnected = ref(wsInstance?.isConnected || false)
+
+  // 监听连接状态
+  const onStatusChange = (status: unknown) => {
+    isConnected.value = status as boolean
+  }
+  wsInstance?.emitter.on('connection-status', onStatusChange)
+
+  // 记录监听器，组件卸载时自动清理
+  const listeners: { type: string, handler: any }[] = []
+
+  // 订阅消息
+  const subscribe = <T = any>(type: string, handler: (data: T) => void) => {
+    wsInstance?.emitter.on(type, handler as any)
+    listeners.push({ type, handler })
+  }
+
+  // 手动取消订阅
+  const unsubscribe = (type: string, handler: any) => {
+    wsInstance?.emitter.off(type, handler)
+    const index = listeners.findIndex(l => l.type === type && l.handler === handler)
+    if (index !== -1) listeners.splice(index, 1)
+  }
+
+  // 标准格式发送 { type, data }
+  const send = (type: string, data?: any) => {
+    return wsInstance?.send({ type, data }) ?? false
+  }
+
+  // 原生格式发送（不做包装）
+  const sendRaw = (data: any) => {
+    return wsInstance?.send(data) ?? false
+  }
+
+  // 核心：组件卸载时自动清理所有监听器
+  onUnmounted(() => {
+    if (!wsInstance) return
+    wsInstance.emitter.off('connection-status', onStatusChange)
+    listeners.forEach(({ type, handler }) => {
+      wsInstance.emitter.off(type, handler)
+    })
+  })
+
+  return { isConnected, subscribe, unsubscribe, send, sendRaw, instance: wsInstance }
+}
+```
+
+## 初始化与关闭
+
+```typescript
+import { initWebSocket, closeWebSocket } from '@/utils/websocket'
+
+// 全局初始化（main.ts 或 app 启动时）
+initWebSocket('wss://example.com/ws')           // 默认实例 'default'
+initWebSocket('wss://example.com/ws', 'chat')   // 命名实例
+
+// 关闭
+closeWebSocket()          // 关闭默认实例
+closeWebSocket('chat')    // 关闭指定实例
+```
+
+## 页面使用示例
+
+```vue
+<script setup lang="ts">
+import { useWebSocket } from '@/hooks/useWebSocket'
+import { closeWebSocket, initWebSocket } from '@/utils/websocket'
+
+defineOptions({ name: 'WebSocketDemo' })
+
+const wsUrl = ref(import.meta.env.VITE_WS_URL || '')
+const INSTANCE_NAME = 'demo-ws'
+const messageList = ref<{ time: string, text: string, type: 'send' | 'receive' }[]>([])
+const inputVal = ref('')
+const isConnected = ref(false)
+const isInit = ref(false)
+let subscribe: any = null
+let sendRaw: any = null
+
+const handleConnect = () => {
+  if (!wsUrl.value) return
+  // 1. 按需初始化
+  initWebSocket(wsUrl.value, INSTANCE_NAME)
+  isInit.value = true
+
+  // 2. 获取 Hook
+  const wsHook = useWebSocket(INSTANCE_NAME)
+  isConnected.value = wsHook.isConnected.value
+  wsHook.subscribe('connection-status', (status: any) => {
+    isConnected.value = !!status
+  })
+
+  subscribe = wsHook.subscribe
+  sendRaw = wsHook.sendRaw
+
+  // 3. 订阅消息（非标准格式派发到 'message' 事件）
+  subscribe('message', (data: any) => {
+    messageList.value.push({
+      time: new Date().toLocaleTimeString(),
+      text: typeof data === 'string' ? data : JSON.stringify(data),
+      type: 'receive',
+    })
+  })
+}
+
+const handleDisconnect = () => {
+  closeWebSocket(INSTANCE_NAME)
+  isInit.value = false
+  isConnected.value = false
+}
+
+const handleSend = () => {
+  if (!inputVal.value || !isConnected.value) return
+  sendRaw(inputVal.value)
+  messageList.value.push({
+    time: new Date().toLocaleTimeString(),
+    text: inputVal.value,
+    type: 'send',
+  })
+  inputVal.value = ''
+}
+
+onUnmounted(() => {
+  closeWebSocket(INSTANCE_NAME)
+})
+</script>
+```
+
+## 环境变量
+
+```env
+# .env.development
+VITE_WS_URL=wss://dev.example.com/ws
+
+# .env.production
+VITE_WS_URL=wss://api.example.com/ws
+```
+
+## 关键约定
+
+1. **多实例管理**：每个 WebSocket 连接是独立实例，互不干扰。全局 `default` 实例用于通用推送，页面级实例用于特定业务。
+2. **自动清理**：`useWebSocket` 在 `onUnmounted` 中自动移除当前组件注册的所有监听器，防止内存泄漏和重复消费。
+3. **事件派发**：标准格式 `{ type, data }` 按 `type` 派发；非标准格式统一派发到 `'message'` 事件。
+4. **连接状态**：`connection-status` 事件通知连接/断开状态，UI 可直接绑定显示在线/离线标识。
+5. **页面销毁**：页面级 WebSocket 在 `onUnmounted` 中调用 `closeWebSocket(INSTANCE_NAME)` 关闭连接。
+6. **重连机制**：底层 `WebSocketManager` 内置自动重连，业务层无需处理。
+
+## 关联文件
+
+- [src/hooks/useWebSocket.ts](file:///e:/work/vue3-web-temp/src/hooks/useWebSocket.ts)
+- [src/utils/websocket/index.ts](file:///e:/work/vue3-web-temp/src/utils/websocket/index.ts)
+- [src/utils/websocket/core.ts](file:///e:/work/vue3-web-temp/src/utils/websocket/core.ts)
+- [src/views/websocket/index.vue](file:///e:/work/vue3-web-temp/src/views/websocket/index.vue)