@elf-express/admin-net-mcp 1.0.0 → 1.1.0

package/knowledge/sqlsugar.md

@@ -0,0 +1,172 @@
+# Admin.NET SqlSugar ORM 指南
+
+## AOP 自動填充欄位
+
+SqlSugar AOP 在 Insert/Update 時自動填入以下欄位（無需手動設定）：
+
+### Insert 時自動填充
+| 欄位 | 來源 | 條件 |
+|------|------|------|
+| Id（long） | YitIdHelper.NextId() | 值為 0 或 null 時 |
+| CreateTime | DateTime.Now | 為 null 或 MinValue 時 |
+| CreateUserId | ClaimConst.UserId（JWT） | 為 null 或 0 時 |
+| CreateUserName | ClaimConst.RealName（JWT） | 為空字串時 |
+| TenantId | ClaimConst.TenantId（JWT） | 為 null 或 0，且實體實作 ITenantIdFilter |
+
+### Update 時自動填充
+| 欄位 | 來源 |
+|------|------|
+| UpdateTime | DateTime.Now（永遠更新） |
+| UpdateUserId | 目前使用者 ID |
+| UpdateUserName | 目前使用者姓名 |
+| DeleteTime | DateTime.Now（當 IsDelete=true） |
+
+**注意**：種子資料初始化時（\_isHandlingSeedData=true）AOP 會跳過，使用明確設定的值。
+
+## 自動查詢過濾
+
+SqlSugar 根據實體實作的介面自動加入 WHERE 條件：
+
+```csharp
+// 軟刪除過濾（實作 IDeletedFilter 的實體自動套用）
+WHERE IsDelete = 0
+
+// 租戶過濾（實作 ITenantIdFilter 的實體自動套用）
+WHERE TenantId = 目前使用者的 TenantId
+
+// 組織資料權限（實作 IOrgIdFilter 的實體自動套用）
+WHERE OrgId IN (使用者有權限的組織清單)
+```
+
+**SuperAdmin 例外**：DbConnectionOptions.SuperAdminIgnoreIDeletedFilter = true 時，超級管理員可看到已刪除資料。
+
+## SqlSugarRepository<T> 使用方式
+
+### 注入
+```csharp
+public class OrderService : IDynamicApiController, ITransient
+{
+    private readonly SqlSugarRepository<Order> _orderRep;
+
+    public OrderService(SqlSugarRepository<Order> orderRep)
+    {
+        _orderRep = orderRep;
+    }
+}
+```
+
+### 常用查詢
+```csharp
+// 取得單筆
+var order = await _orderRep.GetFirstAsync(u => u.Id == id);
+
+// 查詢清單
+var list = await _orderRep.GetListAsync(u => u.Status == 1);
+
+// 分頁（推薦）
+var paged = await _orderRep.AsQueryable()
+    .WhereIF(!string.IsNullOrWhiteSpace(keyword), u => u.Name.Contains(keyword))
+    .OrderBy(u => u.CreateTime, OrderByType.Desc)
+    .ToPagedListAsync(page, pageSize);
+
+// 判斷是否存在
+var exists = await _orderRep.IsAnyAsync(u => u.OrderNo == orderNo);
+
+// 計數
+var count = await _orderRep.CountAsync(u => u.Status == 1);
+```
+
+### 新增/更新/刪除
+```csharp
+// 新增
+await _orderRep.InsertAsync(order);
+await _orderRep.InsertRangeAsync(orders);
+
+// 更新（整筆）
+await _orderRep.UpdateAsync(order);
+
+// 部分欄位更新
+await _orderRep.UpdateAsync(
+    u => new Order { Status = 2, UpdateTime = DateTime.Now },
+    u => u.Id == id);
+
+// 軟刪除（需實作 IDeletedFilter）
+await _orderRep.UpdateAsync(
+    u => new Order { IsDelete = true },
+    u => u.Id == id);
+
+// 真實刪除
+await _orderRep.DeleteAsync(id);
+```
+
+### 聯表查詢
+```csharp
+var result = await _orderRep.AsQueryable()
+    .LeftJoin<OrderItem>((o, i) => o.Id == i.OrderId)
+    .Select((o, i) => new OrderWithItemsOutput
+    {
+        OrderNo = o.OrderNo,
+        ItemCount = SqlFunc.AggregateCount(i.Id)
+    })
+    .ToListAsync();
+```
+
+## 交易管理（UnitOfWork）
+
+### 方式一：[UnitOfWork] Attribute（推薦）
+```csharp
+[UnitOfWork]
+public async Task CreateOrderWithItems(CreateOrderInput input)
+{
+    var order = input.Adapt<Order>();
+    await _orderRep.InsertAsync(order);
+    // 例外時自動回滾
+    await _itemRep.InsertRangeAsync(items);
+}
+```
+
+### 方式二：手動交易
+```csharp
+var db = _orderRep.Context;
+try
+{
+    db.BeginTran();
+    await _orderRep.InsertAsync(order);
+    await _itemRep.InsertRangeAsync(items);
+    db.CommitTran();
+}
+catch
+{
+    db.RollbackTran();
+    throw;
+}
+```
+
+## 多資料庫路由
+
+Repository 依實體 Attribute 自動選擇連線：
+1. `[TenantAttribute]` → 租戶專屬 DB
+2. `[LogTableAttribute]` → Log 專用 DB
+3. `[SysTableAttribute]` → 主 DB（強制）
+4. Request Header 中的 TenantId → 租戶 DB
+5. 預設 → 主 DB
+
+## 分表（Split Table）方法
+
+用於日期分表或大型資料集：
+```csharp
+await _logRep.SplitTableInsertAsync(logEntry);
+var logs = await _logRep.SplitTableGetListAsync(u => u.CreateTime > startDate);
+```
+
+## 原始 SQL（謹慎使用）
+```csharp
+var result = await db.SqlQueryable<OrderOutput>("SELECT * FROM Orders WHERE Status=@status")
+    .AddParameters(new SugarParameter("@status", 1))
+    .ToListAsync();
+```
+
+## 檔案位置
+- SqlSugar 設定（AOP）：`Admin.NET.Core/SqlSugar/SqlSugarSetup.cs`
+- Repository 實作：`Admin.NET.Core/SqlSugar/SqlSugarRepository.cs`
+- UnitOfWork：`Admin.NET.Core/SqlSugar/SqlSugarUnitOfWork.cs`

package/knowledge/vue-typescript.md

@@ -0,0 +1,338 @@
+# 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

@@ -1,13 +1,14 @@
 {
   "name": "@elf-express/admin-net-mcp",
-  "version": "1.0.0",
+  "version": "1.1.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/"
+    "dist/",
+    "knowledge/"
   ],
   "publishConfig": {
     "access": "public"