@elf-express/admin-net-mcp 1.0.0

package/dist/knowledge/event.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eventGuide = void 0;
+exports.eventGuide = `
+# Admin.NET 事件匯流排指南
+
+## 基本概念
+
+Admin.NET 使用 Furion 的事件匯流排，透過 [EventSubscribe] 屬性訂閱事件，解耦業務邏輯。
+
+## 訂閱者模式
+
+\`\`\`csharp
+public class OrderEventSubscriber : IEventSubscriber, ISingleton, IDisposable
+{
+    private readonly IServiceScopeFactory _scopeFactory;
+
+    public OrderEventSubscriber(IServiceScopeFactory scopeFactory)
+    {
+        _scopeFactory = scopeFactory;
+    }
+
+    [EventSubscribe("Order:Created")]
+    public async Task OnOrderCreated(EventHandlerExecutingContext context)
+    {
+        // context.Source.EventId — 事件名稱
+        // context.Source.Payload — 事件資料（object）
+        var order = context.Source.Payload as Order;
+
+        using var scope = _scopeFactory.CreateScope();
+        var emailService = scope.ServiceProvider.GetRequiredService<IEmailService>();
+        await emailService.SendOrderConfirmation(order);
+    }
+
+    [EventSubscribe("Order:Cancelled")]
+    public async Task OnOrderCancelled(EventHandlerExecutingContext context)
+    {
+        var payload = (OrderCancelledPayload)context.Source.Payload;
+        // 處理取消邏輯
+    }
+
+    public void Dispose() { }
+}
+\`\`\`
+
+## 必要條件
+
+| 項目 | 說明 |
+|------|------|
+| \`IEventSubscriber\` | 必須實作此介面 |
+| \`ISingleton\` | 通常使用 Singleton（也可 ITransient） |
+| \`IDisposable\` | 建議實作，釋放資源 |
+| \`IServiceScopeFactory\` | 訂閱者是 Singleton，需透過 Scope 使用 Scoped 服務 |
+
+## 發布事件
+
+### 方式一：非同步發布（推薦）
+\`\`\`csharp
+await App.GetRequiredService<IEventPublisher>().PublishAsync(
+    new ChannelEventSource("Order:Created", order));
+\`\`\`
+
+### 方式二：在 AOP / Filter 中發布
+\`\`\`csharp
+await App.PublishAsync(new EventSource
+{
+    EventId = CommonConst.AddExLog,
+    Payload = logEntity
+});
+\`\`\`
+
+### 方式三：透過注入的 IEventPublisher
+\`\`\`csharp
+public class OrderService : IDynamicApiController, ITransient
+{
+    private readonly IEventPublisher _eventPublisher;
+
+    public OrderService(IEventPublisher eventPublisher)
+    {
+        _eventPublisher = eventPublisher;
+    }
+
+    public async Task CreateOrder(CreateOrderInput input)
+    {
+        var order = await SaveOrder(input);
+        await _eventPublisher.PublishAsync("Order:Created", order);
+    }
+}
+\`\`\`
+
+## 系統內建事件
+
+### CommonConst 定義的事件
+| 事件名稱 | 說明 |
+|----------|------|
+| \`CommonConst.AddExLog\` ("Add:ExLog") | 記錄例外 Log |
+| \`CommonConst.SendErrorMail\` ("Send:ErrorMail") | 發送錯誤通知郵件 |
+
+### 使用者事件（SysUserEventTypeEnum）
+| 事件 | 說明 |
+|------|------|
+| SysUserEventTypeEnum.Add | 使用者建立 |
+| SysUserEventTypeEnum.Register | 使用者自行注冊 |
+| SysUserEventTypeEnum.Update | 使用者更新 |
+| SysUserEventTypeEnum.Delete | 使用者刪除 |
+| SysUserEventTypeEnum.SetStatus | 狀態變更 |
+| SysUserEventTypeEnum.UpdateRole | 角色指派 |
+| SysUserEventTypeEnum.UnlockLogin | 解鎖登入 |
+
+## 事件儲存設定（EventBus.json）
+
+| 設定 | 說明 |
+|------|------|
+| InMemory | 記憶體（預設，不持久化） |
+| Redis | Redis 佇列（需要 RedisEventSourceStorer） |
+| RabbitMQ | RabbitMQ 訊息佇列 |
+
+## 最佳實踐
+
+1. **在訂閱者中取得 Scoped 服務**：使用 IServiceScopeFactory.CreateScope()（因訂閱者是 Singleton）
+2. **Payload 型別**：發布和訂閱要使用相同型別，或用 JSON 字串中轉
+3. **例外處理**：訂閱者的例外不會傳播到發布者，需要在訂閱者中自行 try/catch
+4. **避免循環事件**：A 事件觸發 B 事件觸發 A 事件會造成無限循環
+
+## 檔案位置
+- 核心事件訂閱：\`Admin.NET.Core/EventBus/AppEventSubscriber.cs\`
+- 應用層事件：\`Admin.NET.Application/EventBus/\`
+- 常數定義：\`Admin.NET.Core/Const/CommonConst.cs\`
+`;

package/dist/knowledge/plugin.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pluginGuide = void 0;
+exports.pluginGuide = `
+# Admin.NET 插件系統指南
+
+## 插件載入機制
+
+插件是獨立的 .NET 專案，透過 App.json 中的 ExternalAssemblies 設定自動載入：
+
+\`\`\`json
+// Admin.NET.Application/Configuration/App.json
+{
+  "App": {
+    "ExternalAssemblies": ["plugins"]
+  }
+}
+\`\`\`
+
+Furion 掃描 plugins 目錄中的所有組件，自動發現並載入 [AppStartup] 類別。
+
+## Startup 類別模式
+
+每個插件必須有一個 Startup 類別：
+
+\`\`\`csharp
+namespace Admin.NET.Plugin.MyFeature;
+
+[AppStartup(200)]  // 數字越小，越早執行
+public class Startup : AppStartup
+{
+    public void ConfigureServices(IServiceCollection services)
+    {
+        // 註冊插件的 DI 服務
+        services.AddSingleton<IMyService, MyService>();
+
+        // 設定插件選項
+        services.AddConfigurableOptions<MyFeatureOptions>();
+    }
+
+    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
+    {
+        // 中介軟體設定
+        app.UseMyFeatureMiddleware();
+    }
+}
+\`\`\`
+
+## 執行優先順序
+
+| Startup 類別 | 優先順序 | 說明 |
+|-------------|----------|------|
+| Admin.NET.Web.Core/Startup | int.MaxValue | 最先執行（框架核心） |
+| Admin.NET.Application/Startup | 100 | 應用層設定 |
+| 各插件 Startup | 自訂（1~99） | 數字越大越晚執行 |
+
+**規則**：數字越大的 [AppStartup(N)] 越晚執行（與直覺相反）。
+框架核心用 MaxValue 確保最先執行，應用層用 100，插件通常用 1-99。
+
+## 插件目錄結構
+
+\`\`\`
+Plugins/
+└── Admin.NET.Plugin.MyFeature/
+    ├── Admin.NET.Plugin.MyFeature.csproj
+    ├── Startup.cs
+    ├── Entity/
+    │   └── MyEntity.cs
+    ├── Service/
+    │   └── MyService.cs
+    └── Option/
+        └── MyFeatureOptions.cs
+\`\`\`
+
+## .csproj 設定
+
+\`\`\`xml
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+  </PropertyGroup>
+  <ItemGroup>
+    <!-- 只需引用 Admin.NET.Core -->
+    <ProjectReference Include="..\\..\\Admin.NET.Core\\Admin.NET.Core.csproj" />
+  </ItemGroup>
+</Project>
+\`\`\`
+
+## 現有插件清單
+
+| 插件 | 說明 |
+|------|------|
+| Admin.NET.Plugin.GoView | 低代碼視覺化大屏 |
+| Admin.NET.Plugin.DingTalk | 釘釘整合 |
+| Admin.NET.Plugin.ReZero | 介面零程式碼配置 |
+| Admin.NET.Plugin.ApprovalFlow | 審批流程 |
+| Admin.NET.Plugin.K3Cloud | 金蝶 K3 Cloud 整合 |
+| Admin.NET.Plugin.WorkWeixin | 企業微信整合 |
+
+## 插件間通訊
+
+插件之間透過 DI 介面通訊（不直接引用）：
+
+\`\`\`csharp
+// 定義介面（放在共用的 Core 層或介面插件）
+public interface IApprovalService
+{
+    Task<bool> SubmitForApproval(long entityId, string entityType);
+}
+
+// 在其他插件/服務中使用
+public class OrderService : IDynamicApiController, ITransient
+{
+    private readonly IApprovalService _approvalService;
+
+    public OrderService(IApprovalService approvalService)
+    {
+        _approvalService = approvalService;
+    }
+}
+\`\`\`
+
+## 開發新插件步驟
+
+1. 在 \`Plugins/\` 建立新專案 \`Admin.NET.Plugin.{FeatureName}\`
+2. \`.csproj\` 引用 \`Admin.NET.Core\`
+3. 建立 \`Startup.cs\`（繼承 AppStartup，加上 [AppStartup(N)]）
+4. 在 \`ConfigureServices\` 中註冊所需服務
+5. 建立 Entity、Service、Option 等類別
+6. 確認輸出目錄在 \`Admin.NET.Web.Entry/plugins/\` 中（或設定 post-build copy）
+
+## 注意事項
+
+- 插件不可相互直接引用（防止循環依賴）
+- 業務邏輯變更應放插件，不要修改 Admin.NET.Core（方便升級核心）
+- 插件的實體會自動被 SqlSugar 掃描並建立資料表（依 SeedData 設定）
+
+## 檔案位置
+- 插件目錄：\`Admin.NET/Plugins/\`
+- App.json：\`Admin.NET.Application/Configuration/App.json\`
+`;

package/dist/knowledge/service.js

@@ -0,0 +1,151 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serviceGuide = void 0;
+exports.serviceGuide = `
+# Admin.NET 服務（Service）設計指南
+
+## IDynamicApiController 模式
+
+Admin.NET 使用 Furion 的動態 API Controller，Service 同時作為業務邏輯層和 API 端點。
+
+\`\`\`csharp
+[ApiDescriptionSettings(ApplicationConst.GroupName, Order = 100)]
+public class OrderService : IDynamicApiController, ITransient
+{
+    private readonly SqlSugarRepository<Order> _orderRep;
+
+    public OrderService(SqlSugarRepository<Order> orderRep)
+    {
+        _orderRep = orderRep;
+    }
+
+    [DisplayName("分頁查詢訂單")]
+    [ApiDescriptionSettings(Name = "Page"), HttpPost]
+    public async Task<SqlSugarPagedList<OrderOutput>> Page(PageOrderInput input)
+    {
+        // ...
+    }
+}
+\`\`\`
+
+## DI 生命週期
+
+| 介面 | 生命週期 | 說明 |
+|------|----------|------|
+| \`ITransient\` | Scoped（每次請求新實例） | 最常用，業務服務預設使用 |
+| \`ISingleton\` | Singleton（應用程式存活期間唯一） | 快取、設定等無狀態服務 |
+
+## 關鍵 Attribute
+
+### [ApiDescriptionSettings]
+控制路由和 Swagger 分組：
+\`\`\`csharp
+[ApiDescriptionSettings(
+    GroupName,        // API 分組（通常用 ApplicationConst.GroupName）
+    Name = "Page",    // 自訂路由片段（預設為方法名稱）
+    Order = 100       // Swagger 排序
+)]
+\`\`\`
+**路由格式**：\`/api/{ClassName去掉Service}/{Name}\`
+例：OrderService + Name="Page" → \`POST /api/order/page\`
+
+### [DisplayName]
+Swagger 操作說明（必填，用於中文描述）：
+\`\`\`csharp
+[DisplayName("新增訂單")]
+\`\`\`
+
+### [UnitOfWork]
+自動開啟/提交/回滾交易：
+\`\`\`csharp
+[UnitOfWork]
+public async Task CreateOrderWithItems(CreateOrderInput input)
+{
+    // 多個 DB 操作，任何例外都會自動回滾
+    await _orderRep.InsertAsync(order);
+    await _itemRep.InsertRangeAsync(items);
+}
+\`\`\`
+
+### HTTP 方法
+\`\`\`csharp
+[HttpGet]   // GET 請求
+[HttpPost]  // POST 請求（預設）
+\`\`\`
+
+## BaseService<TEntity> 泛型 CRUD
+
+繼承 BaseService<T> 可直接獲得標準 CRUD，無需自行實作：
+
+\`\`\`csharp
+public class OrderService : BaseService<Order>, IDynamicApiController, ITransient
+{
+    // 自動繼承以下方法：
+    // GET  /api/order/detail?id=xxx   → GetDetail(long id)
+    // GET  /api/order/list            → GetList()
+    // POST /api/order/add             → Add(Order entity)
+    // POST /api/order/update          → Update(Order entity)
+    // POST /api/order/delete          → Delete(long id)
+}
+\`\`\`
+
+BaseService<T> 方法：
+| 方法 | HTTP | 路由 | 說明 |
+|------|------|------|------|
+| GetDetail(long id) | GET | /detail | 取得單筆 |
+| GetList() | GET | /list | 取得全部 |
+| Add(T entity) | POST | /add | 新增 |
+| Update(T entity) | POST | /update | 更新 |
+| Delete(long id) | POST | /delete | 刪除 |
+
+## DTO 命名慣例
+
+\`\`\`
+Add{Entity}Input   — 新增用 DTO（繼承 Base{Entity}Input）
+Update{Entity}Input — 更新用 DTO（繼承 Base{Entity}Input）
+{Entity}Output     — 查詢回傳 DTO
+Page{Entity}Input  — 分頁查詢輸入（含 Page、PageSize、Keyword）
+Query{Entity}Input — 單一查詢（含 Id）
+\`\`\`
+
+## Mapster 物件映射
+
+\`\`\`csharp
+// DTO → Entity
+var entity = input.Adapt<Order>();
+
+// 更新現有實體
+input.Adapt(existingOrder);
+
+// Entity → Output DTO
+var output = entity.Adapt<OrderOutput>();
+\`\`\`
+
+## 分頁查詢範例
+
+\`\`\`csharp
+[DisplayName("分頁查詢")]
+[ApiDescriptionSettings(Name = "Page"), HttpPost]
+public async Task<SqlSugarPagedList<OrderOutput>> Page(PageOrderInput input)
+{
+    return await _orderRep.AsQueryable()
+        .WhereIF(!string.IsNullOrWhiteSpace(input.Keyword),
+            u => u.OrderNo.Contains(input.Keyword))
+        .Select<OrderOutput>()
+        .ToPagedListAsync(input.Page, input.PageSize);
+}
+\`\`\`
+
+## 取得目前使用者資訊
+
+\`\`\`csharp
+// 從 JWT Claims 取得
+var userId = App.User?.FindFirst(ClaimConst.UserId)?.Value;
+var tenantId = App.User?.FindFirst(ClaimConst.TenantId)?.Value;
+var realName = App.User?.FindFirst(ClaimConst.RealName)?.Value;
+\`\`\`
+
+## 檔案位置
+- BaseService：\`Admin.NET.Core/Service/BaseService.cs\`
+- 業務服務範例：\`Admin.NET.Application/Service/\`
+`;

package/dist/knowledge/sqlsugar.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sqlsugarGuide = void 0;
+exports.sqlsugarGuide = `
+# 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\`
+`;