@elf-express/admin-net-mcp 1.0.0

package/dist/knowledge/vue-typescript.js

@@ -0,0 +1,343 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vueTypescriptGuide = void 0;
+exports.vueTypescriptGuide = `
+# Vue 3 + TypeScript 採坑記錄
+
+本文記錄 Admin.NET 前端（Vue 3 + Element Plus + Vite）開發中實際踩過的坑。
+
+---
+
+## 一、響應式（Reactivity）
+
+### 坑 1：解構 reactive 物件後失去響應性
+\`\`\`typescript
+// ❌ 錯誤：解構後 name 不是響應式
+const state = reactive({ name: '張三', age: 18 })
+const { name } = state  // name 是普通字串，不會更新
+
+// ✅ 正確方式一：用 toRefs
+const { name } = toRefs(state)
+
+// ✅ 正確方式二：直接用 ref
+const name = ref('張三')
+\`\`\`
+
+### 坑 2：ref 物件忘記 .value
+\`\`\`typescript
+// ❌ 常見錯誤
+const count = ref(0)
+count = 5  // 這會替換掉 ref 本身！
+
+// ✅ 正確
+count.value = 5
+
+// template 中不需要 .value（自動解包）
+// <span>{{ count }}</span>  ← 正確
+\`\`\`
+
+### 坑 3：watch 監聽物件屬性需要 getter
+\`\`\`typescript
+const user = reactive({ name: '張三' })
+
+// ❌ 不會觸發（監聽的是初始值字串）
+watch(user.name, (newVal) => { })
+
+// ✅ 用 getter 函式
+watch(() => user.name, (newVal) => { })
+
+// ✅ 監聽整個 reactive 物件（深層）
+watch(user, (newVal) => { }, { deep: true })
+\`\`\`
+
+### 坑 4：陣列操作不觸發更新
+\`\`\`typescript
+const list = ref<string[]>([])
+
+// ❌ 直接賦值 index 不觸發
+list.value[0] = '新值'
+
+// ✅ 用 splice
+list.value.splice(0, 1, '新值')
+
+// ✅ 或整個陣列替換
+list.value = [...list.value.slice(0, 0), '新值', ...list.value.slice(1)]
+
+// ✅ push/pop/shift/splice 等方法都能正確觸發
+list.value.push('新項目')
+\`\`\`
+
+---
+
+## 二、TypeScript 型別陷阱
+
+### 坑 5：Event 型別錯誤
+\`\`\`typescript
+// ❌ Event 沒有 target.value
+const handleInput = (e: Event) => {
+  console.log(e.target.value)  // TS 報錯：Object is possibly null
+}
+
+// ✅ 明確型別
+const handleInput = (e: Event) => {
+  const target = e.target as HTMLInputElement
+  console.log(target.value)
+}
+
+// ✅ Element Plus 元件直接拿值
+const handleChange = (value: string) => {
+  // el-input 的 change 事件直接傳值，不是 Event
+}
+\`\`\`
+
+### 坑 6：Ref 泛型推斷失敗
+\`\`\`typescript
+// ❌ 初始 null 時 TS 無法推斷型別
+const userInfo = ref(null)
+userInfo.value.name  // 報錯：Object is possibly null
+
+// ✅ 明確指定泛型
+interface UserInfo { name: string; age: number }
+const userInfo = ref<UserInfo | null>(null)
+
+// 使用時加判斷
+if (userInfo.value) {
+  console.log(userInfo.value.name)  // OK
+}
+\`\`\`
+
+### 坑 7：Snowflake ID 精度問題（Admin.NET 專屬！）
+\`\`\`typescript
+// ❌ 後端回傳的 long ID 在 JS 中會丟失精度
+// 例：8107821456789012345 → 8107821456789012000（最後幾位變0）
+
+// ✅ Admin.NET 後端已設定 Long→String 序列化
+// 前端所有 ID 欄位必須宣告為 string，不是 number
+interface SysUser {
+  id: string      // ✅ string
+  // id: number   // ❌ 會丟精度
+  name: string
+}
+
+// API 呼叫時 ID 也傳字串
+await deleteUser({ id: '8107821456789012345' })  // ✅
+\`\`\`
+
+### 坑 8：defineProps 解構失去響應性（Vue 3.4 以前）
+\`\`\`typescript
+// ❌ Vue 3.3 以前解構 props 失去響應性
+const { title, visible } = defineProps<{ title: string; visible: boolean }>()
+// visible 變成靜態值，父元件更新不反映
+
+// ✅ Vue 3.4+ 才支援響應式解構（withDefaults 搭配）
+// 保險做法：不解構，直接用 props.xxx
+const props = defineProps<{ title: string; visible: boolean }>()
+watch(() => props.visible, ...)
+\`\`\`
+
+---
+
+## 三、Element Plus 陷阱
+
+### 坑 9：el-dialog v-model 更新父元件的方式
+\`\`\`vue
+<!-- ❌ 在子元件直接修改 prop -->
+<el-dialog :visible="visible" @update:visible="visible = $event">
+<!-- visible 是 prop，直接賦值會報警告 -->
+
+<!-- ✅ 正確：emit update:modelValue -->
+<script setup lang="ts">
+const props = defineProps<{ modelValue: boolean }>()
+const emit = defineEmits<{ 'update:modelValue': [value: boolean] }>()
+</script>
+<template>
+  <el-dialog
+    :model-value="props.modelValue"
+    @update:model-value="emit('update:modelValue', $event)"
+  />
+</template>
+\`\`\`
+
+### 坑 10：el-table 選取行後刪除資料，選取狀態殘留
+\`\`\`typescript
+// 刪除資料後需要手動清除選取
+const tableRef = ref<InstanceType<typeof ElTable>>()
+
+const handleDelete = async (id: string) => {
+  await deleteApi(id)
+  tableRef.value?.clearSelection()  // ← 必須手動清除
+  await loadData()
+}
+\`\`\`
+
+### 坑 11：el-form validate 在非同步場景的時機問題
+\`\`\`typescript
+const formRef = ref<FormInstance>()
+
+// ❌ validate 是非同步但忘記 await
+const handleSubmit = () => {
+  formRef.value?.validate()  // 不等驗證完就繼續執行
+  submitData()  // 驗證還沒完成就送出
+}
+
+// ✅ 正確
+const handleSubmit = async () => {
+  const valid = await formRef.value?.validate().catch(() => false)
+  if (!valid) return
+  await submitData()
+}
+\`\`\`
+
+### 坑 12：el-select 選項 value 型別不匹配
+\`\`\`vue
+<!-- ❌ v-model 是 number，但 option value 是 string -->
+<el-select v-model="status">  <!-- status: number = 1 -->
+  <el-option :value="'1'" label="啟用" />  <!-- value 是字串 '1' -->
+</el-select>
+<!-- 永遠選不中！ -->
+
+<!-- ✅ 統一型別 -->
+<el-select v-model="status">
+  <el-option :value="1" label="啟用" />   <!-- :value 綁定數字 -->
+</el-select>
+\`\`\`
+
+---
+
+## 四、Vite + 模組系統陷阱
+
+### 坑 13：動態 import 路徑不能全動態
+\`\`\`typescript
+// ❌ Vite 無法靜態分析完全動態的路徑
+const modulePath = getPathFromApi()
+const module = await import(modulePath)  // 打包時報錯或執行時找不到
+
+// ✅ 必須有靜態前綴讓 Vite 分析
+const module = await import(\`../views/\${pageName}.vue\`)
+\`\`\`
+
+### 坑 14：@/ 別名在某些設定下失效
+\`\`\`typescript
+// vite.config.ts 需要設定 resolve.alias
+import path from 'path'
+export default {
+  resolve: {
+    alias: {
+      '/@/': path.resolve(__dirname, 'src'),  // Admin.NET 前端用 /@/
+      '@/': path.resolve(__dirname, 'src'),   // 也可同時支援兩種
+    }
+  }
+}
+
+// tsconfig.json 也要同步設定
+{
+  "compilerOptions": {
+    "paths": {
+      "/@/*": ["src/*"]
+    }
+  }
+}
+\`\`\`
+
+### 坑 15：.env 環境變數需要 VITE_ 前綴
+\`\`\`bash
+# ❌ 前端讀取不到（只有 Node.js 環境能讀）
+API_URL=https://api.example.com
+
+# ✅ 加 VITE_ 前綴才能在前端使用
+VITE_API_URL=https://api.example.com
+\`\`\`
+\`\`\`typescript
+// 使用
+const apiUrl = import.meta.env.VITE_API_URL
+\`\`\`
+
+---
+
+## 五、Pinia 狀態管理
+
+### 坑 16：在 setup() 外部使用 store 需要傳入 pinia 實例
+\`\`\`typescript
+// ❌ 在 router guard 或工具函式中直接呼叫
+const userStore = useUserStore()  // 可能報錯：no active Pinia
+
+// ✅ 傳入 pinia 實例（main.ts 中建立的）
+import { pinia } from '/@/main'
+const userStore = useUserStore(pinia)
+\`\`\`
+
+### 坑 17：storeToRefs 只解構 state 和 getters
+\`\`\`typescript
+const store = useUserStore()
+
+// ❌ actions 用 storeToRefs 解構後會失去方法
+const { fetchUser } = storeToRefs(store)  // fetchUser 變成 ref，不能呼叫
+
+// ✅ actions 直接從 store 解構
+const { fetchUser, updateUser } = store  // actions 直接解構 OK
+const { name, age } = storeToRefs(store)  // state/getters 用 storeToRefs
+\`\`\`
+
+---
+
+## 六、非同步與生命週期
+
+### 坑 18：onMounted 中的非同步初始化
+\`\`\`typescript
+// ❌ onMounted 不能直接 async（會吞掉錯誤）
+onMounted(async () => {
+  await fetchData()  // 錯誤不會被 Vue 的錯誤處理捕獲
+})
+
+// ✅ 包一層 try/catch 或用獨立函式
+const init = async () => {
+  try {
+    await fetchData()
+  } catch (err) {
+    ElMessage.error('載入失敗')
+  }
+}
+onMounted(init)
+\`\`\`
+
+### 坑 19：nextTick 取得更新後的 DOM
+\`\`\`typescript
+// ❌ 資料改變後立即操作 DOM（DOM 還沒更新）
+tableData.value = newData
+tableRef.value?.doLayout()  // 可能拿到舊的 DOM
+
+// ✅ 等 DOM 更新後再操作
+tableData.value = newData
+await nextTick()
+tableRef.value?.doLayout()
+\`\`\`
+
+---
+
+## 七、Admin.NET 前端特定
+
+### 坑 20：API 回應的統一格式
+\`\`\`typescript
+// Admin.NET 所有 API 回應包在統一格式中
+// { code: 200, message: "成功", data: { ... } }
+
+// ❌ 以為 response 直接是資料
+const user = await getUserApi(id)
+console.log(user.name)  // undefined！data 在 response.data 中
+
+// ✅ axios interceptor 已處理，直接拿 data
+// 查看 Web/src/utils/request.ts 的攔截器設定
+const user = await getUserApi(id)  // interceptor 已解包 data
+console.log(user.name)  // OK（視攔截器實作而定）
+\`\`\`
+
+### 坑 21：路由動態載入元件路徑大小寫問題
+\`\`\`typescript
+// Windows 開發環境不區分大小寫，Linux 伺服器區分
+// ❌ 本機 OK 但上線後 404
+component: () => import('../views/System/User.vue')  // 實際檔名 user.vue
+
+// ✅ 保持檔名與 import 路徑大小寫完全一致
+// 建議統一使用 kebab-case 檔名：user-manage.vue
+\`\`\`
+`;

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@elf-express/admin-net-mcp",
+  "version": "1.0.0",
+  "description": "Admin.NET / Furion / SqlSugar / Vue 3 framework knowledge MCP server",
+  "main": "dist/index.js",
+  "bin": {
+    "admin-net-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/elf-express/platfrom-admin.git"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build && node -e \"const fs=require('fs');const f='dist/index.js';const c=fs.readFileSync(f,'utf8');if(!c.startsWith('#!/'))fs.writeFileSync(f,'#!/usr/bin/env node\\n'+c);\""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.0.0"
+  }
+}