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

package/knowledge/Furion_Teaching_Manual/26-2-Cron/350/241/250/351/201/224/345/274/217.md

@@ -0,0 +1,203 @@
+# 26.2 Cron 表達式
+
+> **版本說明**：Furion 4.8.0+ 採用 TimeCrontab 作為 Cron 表達式解析。非 Furion 框架可安裝 `TimeCrontab` 套件。
+
+---
+
+## 26.2.1 概述
+
+Cron 表達式是由 5～7 個域組成的字串，每個域代表一個時間單位，是定時任務排程的核心基礎。
+
+---
+
+## 26.2.2 快速入門
+
+### 四種格式
+
+```csharp
+// 常規：分 時 天 月 周
+var crontab = Crontab.Parse("* * * * *");
+
+// 含年份：分 時 天 月 周 年
+var crontab = Crontab.Parse("* * * * * *", CronStringFormat.WithYears);
+
+// 含秒數：秒 分 時 天 月 周
+var crontab = Crontab.Parse("* * * * * *", CronStringFormat.WithSeconds);
+
+// 含秒和年：秒 分 時 天 月 周 年
+var crontab = Crontab.Parse("* * * * * * *", CronStringFormat.WithSecondsAndYears);
+
+// 取得下一個/上一個發生時間
+var next = crontab.GetNextOccurrence(DateTime.Now);
+var prev = crontab.GetPreviousOccurrence(DateTime.Now); // 4.9.7.6+
+```
+
+### Macro 標識符與靜態屬性
+
+```csharp
+// 字串方式
+var secondly = Crontab.Parse("@secondly");  // 每秒
+var minutely = Crontab.Parse("@minutely");  // 每分鐘
+var hourly   = Crontab.Parse("@hourly");    // 每小時
+var daily    = Crontab.Parse("@daily");     // 每天 00:00:00
+var monthly  = Crontab.Parse("@monthly");   // 每月 1 號
+var weekly   = Crontab.Parse("@weekly");    // 每週日
+var yearly   = Crontab.Parse("@yearly");    // 每年 1/1
+var workday  = Crontab.Parse("@workday");   // 週一至週五
+
+// 靜態屬性方式
+var secondly = Crontab.Secondly;
+var minutely = Crontab.Minutely;
+// ... 同上
+```
+
+### Macro At 標識符
+
+```csharp
+Crontab.SecondlyAt(3, 5, 6);     // 每第 3、5、6 秒
+Crontab.MinutelyAt(3);           // 每分鐘第 3 秒
+Crontab.HourlyAt(3, 5, 6);      // 每小時第 3、5、6 分鐘
+Crontab.DailyAt(3);              // 每天第 3 小時
+Crontab.MonthlyAt(3, 5, 6);     // 每月第 3、5、6 天
+Crontab.WeeklyAt(3, "FRI", 6);  // 每週星期 3、五、6（支援混合）
+Crontab.YearlyAt(3, "MAY", 6);  // 每年第 3、五、6 月
+```
+
+> 星期縮寫：`SUN`、`MON`、`TUE`、`WED`、`THU`、`FRI`、`SAT`  
+> 月份縮寫：`JAN`～`DEC`
+
+### R 隨機時刻（4.9.6.17+）
+
+```csharp
+// 每天 00:00 的隨機秒數觸發
+var crontab = Crontab.Parse("R 0 0 * * ? *", CronStringFormat.WithSecondsAndYears);
+```
+
+---
+
+## 26.2.3 各欄位說明
+
+| 欄位 | 允許值 | 特殊符號 | 格式化要求 |
+|------|--------|----------|-----------|
+| 秒 | 0-59 | `*` `,` `-` `/` `R` | WithSeconds / WithSecondsAndYears |
+| 分鐘 | 0-59 | `*` `,` `-` `/` `R` | ALL |
+| 小時 | 0-23 | `*` `,` `-` `/` `R` | ALL |
+| 天 | 1-31 | `*` `,` `-` `/` `?` `L` `W` | ALL |
+| 月份 | 1-12 / JAN-DEC | `*` `,` `-` `/` | ALL |
+| 星期 | 0-6 / SUN-SAT | `*` `,` `-` `/` `?` `L` `#` | ALL |
+| 年份 | 0001-9999 | `*` `,` `-` `/` | WithYears / WithSecondsAndYears |
+
+### 特殊符號說明
+
+| 符號 | 說明 |
+|------|------|
+| `*` | 匹配任意值 |
+| `?` | 僅用於「天」和「星期」，避免兩者衝突 |
+| `-` | 範圍，如 `5-20` 表示 5 到 20 |
+| `/` | 步進，如 `5/20` 表示從 5 開始每隔 20 |
+| `,` | 列舉，如 `5,20` |
+| `L` | 最後，如星期域 `5L` = 最後一個星期四 |
+| `W` | 最近工作日，如 `5W` = 離 5 號最近的工作日 |
+| `LW` | 某月最後一個工作日 |
+| `#` | 第幾個星期幾，如 `2#3` = 第三個星期二 |
+| `R` | 隨機時刻（4.9.6.17+） |
+
+---
+
+## 26.2.4 CronStringFormat 格式化
+
+| 格式 | 書寫順序 |
+|------|---------|
+| `Default` | 分 時 天 月 周 |
+| `WithYears` | 分 時 天 月 周 年 |
+| `WithSeconds` | 秒 分 時 天 月 周 |
+| `WithSecondsAndYears` | 秒 分 時 天 月 周 年 |
+
+---
+
+## 26.2.6 實現簡單定時任務
+
+### while + Task 方式
+
+```csharp
+var crontab = Crontab.Parse("* * * * * *", CronStringFormat.WithSeconds);
+
+// 無阻塞方式
+Task.Factory.StartNew(async () =>
+{
+    while (true)
+    {
+        await Task.Delay(crontab.GetSleepTimeSpan(DateTime.Now));
+        Console.WriteLine(DateTime.Now.ToString("G"));
+    }
+}, TaskCreationOptions.LongRunning);
+```
+
+### BackgroundService 方式
+
+```csharp
+public class Worker : BackgroundService
+{
+    private readonly Crontab _crontab;
+
+    public Worker(ILogger<Worker> logger)
+    {
+        _crontab = Crontab.Parse("* * * * * *", CronStringFormat.WithSeconds);
+    }
+
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            var taskFactory = new TaskFactory(TaskScheduler.Current);
+            await taskFactory.StartNew(async () =>
+            {
+                // 業務程式碼
+                await Task.CompletedTask;
+            }, stoppingToken);
+
+            await Task.Delay(_crontab.GetSleepTimeSpan(DateTime.Now), stoppingToken);
+        }
+    }
+}
+```
+
+> 建議使用 **26.1 排程作業** 實現強大的分散式定時任務。
+
+---
+
+## 26.2.7 Crontab 物件 API 速查
+
+### 實例方法
+
+| 方法 | 說明 |
+|------|------|
+| `GetNextOccurrence(startTime)` | 下一個執行時間 |
+| `GetNextOccurrence(startTime, endTime)` | 指定範圍內下一個時間 |
+| `GetNextOccurrences(startTime, endTime)` | 指定範圍內所有執行時間 |
+| `GetPreviousOccurrence(startTime)` | 上一個執行時間（4.9.7.6+） |
+| `GetPreviousOccurrences(startTime, endTime)` | 指定範圍內所有過去時間（4.9.7.6+） |
+| `GetSleepMilliseconds(baseTime)` | 距下次觸發的毫秒數 |
+| `GetSleepTimeSpan(baseTime)` | 距下次觸發的 TimeSpan（4.8.4.10+） |
+| `ToString()` | 轉換為 Cron 表達式字串 |
+
+### 靜態方法
+
+| 方法 | 說明 |
+|------|------|
+| `Parse(expr, format)` | 解析表達式 |
+| `TryParse(expr, format)` | 嘗試解析（不拋例外） |
+| `ParseAt(macro, params)` | 建立 Macro At 物件 |
+| `IsValid(expr, format)` | 判斷是否有效（4.8.7.17+） |
+| `SecondlyAt(...)` / `MinutelyAt(...)` / `HourlyAt(...)` | 秒/分/時 At |
+| `DailyAt(...)` / `MonthlyAt(...)` / `WeeklyAt(...)` / `YearlyAt(...)` | 天/月/週/年 At |
+
+### 靜態屬性
+
+`Secondly` / `Minutely` / `Hourly` / `Daily` / `Monthly` / `Weekly` / `Yearly` / `Workday`
+
+---
+
+## 線上工具
+
+推薦使用線上 Cron 表達式生成器：https://cron.qqe2.com/

package/knowledge/Furion_Teaching_Manual/26-3-/344/273/273/345/213/231/344/275/207/345/210/227TaskQueue.md

@@ -0,0 +1,215 @@
+# 26.3 任務佇列（TaskQueue）
+
+> **版本說明**：僅適用於 Furion 4.8.3+ 版本。可取代舊版 `SpareTime.DoIt()` 和 `SpareTime.DoOnce`。
+
+---
+
+## 26.3.1 概述
+
+任務佇列用於管理背景工作，不會阻塞主執行緒。基於 `Channel + Task + ThreadPool` 實作，入隊/出隊速度極快，吞吐量極高。
+
+**應用場景**：發送郵件、發送簡訊等可能長時間執行或不需要即時回饋的任務。
+
+**與事件匯流排的區別**：事件匯流排基於訊息通訊（無序，需匹配 Id）；任務佇列按入隊順序依次出隊執行。
+
+---
+
+## 26.3.3 快速入門
+
+### 註冊服務
+
+```csharp
+services.AddTaskQueue();
+```
+
+### 使用 ITaskQueue
+
+```csharp
+public class YourService : IYourService
+{
+    private readonly ITaskQueue _taskQueue;
+    public YourService(ITaskQueue taskQueue) => _taskQueue = taskQueue;
+
+    // 同步入隊
+    public void SyncTask()
+    {
+        _taskQueue.Enqueue(provider => Console.WriteLine("同步任務"));
+    }
+
+    // 同步入隊，延遲 3 秒
+    public void SyncTaskDelay()
+    {
+        _taskQueue.Enqueue(_ => Console.WriteLine("延遲 3 秒"),
+            task => task.WithDelay(3000));
+    }
+
+    // 非同步入隊
+    public async Task AsyncTask()
+    {
+        await _taskQueue.EnqueueAsync(async (provider, token) =>
+        {
+            Console.WriteLine("非同步任務");
+            await ValueTask.CompletedTask;
+        });
+    }
+
+    // 非同步入隊，延遲 3 秒
+    public async Task AsyncTaskDelay()
+    {
+        await _taskQueue.EnqueueAsync(async (_, _) =>
+        {
+            Console.WriteLine("延遲 3 秒");
+            await ValueTask.CompletedTask;
+        }, task => task.WithDelay(3000));
+    }
+
+    // Cron 表達式延遲
+    public void CronTask()
+    {
+        _taskQueue.Enqueue(_ => Console.WriteLine("Cron"),
+            task => task.WithDelay("* * * * *"));
+    }
+
+    // 延遲 + 立即執行一次（4.9.1.56+）
+    public void DelayWithRunOnce()
+    {
+        _taskQueue.Enqueue(_ => Console.WriteLine("延遲但先執行一次"),
+            task => task.WithDelay(3000).WithRunOnceIfDelaySet(true));
+    }
+}
+```
+
+### TaskQueued 靜態類
+
+```csharp
+TaskQueued.Enqueue(provider => { });
+await TaskQueued.EnqueueAsync(async (provider, token) => { });
+```
+
+---
+
+## 26.3.5 在處理程式中使用服務
+
+```csharp
+_taskQueue.Enqueue(provider =>
+{
+    // 範圍/瞬時服務需建立作用域
+    using var scoped = provider.CreateScope();
+    var repository = scoped.ServiceProvider.GetService<IRepository<User>>();
+
+    // 單例服務可直接使用外部注入的實例
+    _logger.LogInformation("OK");
+});
+```
+
+---
+
+## 26.3.6 訂閱未察覺異常
+
+```csharp
+services.AddTaskQueue(builder =>
+{
+    builder.UnobservedTaskExceptionHandler = (obj, args) => { };
+});
+```
+
+---
+
+## 26.3.7 並行與串行（4.9.1.22+）
+
+```csharp
+// 全域設定
+services.AddTaskQueue(builder =>
+{
+    builder.Concurrent = false; // 串行（預設並行）
+});
+
+// 局部設定（4.9.1.38+）
+await _taskQueue.EnqueueAsync(async (_, _) => { },
+    task => task.WithDelay(3000).WithConcurrent(false)); // 串行
+```
+
+---
+
+## 26.3.8 任務標識 TaskId（4.9.1.28+）
+
+```csharp
+// 自動產生 TaskId
+var taskId = await _taskQueue.EnqueueAsync(async (_, _) => { });
+
+// 自訂 TaskId（4.9.1.38+）
+var taskId = await _taskQueue.EnqueueAsync(async (_, _) => { },
+    task => task.WithTaskId("唯一 id"));
+```
+
+---
+
+## 26.3.9 任務管道 Channel（4.9.1.28+）
+
+```csharp
+var taskId = await _taskQueue.EnqueueAsync(async (_, _) => { },
+    task => task.WithChannel("批次1"));
+```
+
+可根據 Channel 進行任務執行結果訂閱。
+
+---
+
+## 26.3.10 異常重試設定（4.9.1.24+）
+
+```csharp
+services.AddTaskQueue(builder =>
+{
+    builder.NumRetries = 3;        // 預設重試 3 次
+    builder.RetryTimeout = 1000;   // 每次間隔 1000ms
+});
+```
+
+---
+
+## 26.3.11 任務執行結果訂閱（4.9.1.28+）
+
+```csharp
+_taskQueue.OnExecuted += (sender, args) =>
+{
+    Console.WriteLine($"任務 {args.TaskId} 管道 {args.Channel}，狀態：{args.Status}，異常：{args.Exception}");
+};
+```
+
+### 重複訂閱問題
+
+`ITaskQueue` 為單例，非單例服務中訂閱後需在 `Dispose` 中移除：
+
+```csharp
+public class SomeService : ISomeService, IScoped, IDisposable
+{
+    private readonly ITaskQueue _taskQueue;
+
+    public SomeService(ITaskQueue taskQueue)
+    {
+        _taskQueue = taskQueue;
+        _taskQueue.OnExecuted += Subscribe;
+    }
+
+    void Subscribe(object sender, TaskHandlerEventArgs args) { }
+
+    public void Dispose() => _taskQueue.OnExecuted -= Subscribe;
+}
+```
+
+### 最佳推薦
+
+在 `Startup.cs` 的 `Configure` 中或**單例服務**中訂閱，避免重複多播。
+
+---
+
+## 任務設定方法速查
+
+| 方法 | 說明 |
+|------|------|
+| `.WithDelay(ms)` | 延遲毫秒數 |
+| `.WithDelay(cronExpr, format)` | Cron 表達式延遲 |
+| `.WithRunOnceIfDelaySet(true)` | 延遲佇列先立即執行一次（4.9.1.56+） |
+| `.WithConcurrent(bool)` | 局部並行/串行（4.9.1.38+） |
+| `.WithTaskId(object)` | 自訂任務 Id（4.9.1.38+） |
+| `.WithChannel(string)` | 設定管道/批次（4.9.1.28+） |

package/knowledge/Furion_Teaching_Manual/27-/345/210/206/346/225/243/345/274/217ID/347/224/237/346/210/220.md

@@ -0,0 +1,86 @@
+# 27. 分散式 ID 生成
+
+---
+
+## 27.1 為什麼需要分散式 ID
+
+- **全域唯一性**：不能出現重複的 ID，這是最基本的要求。
+- **趨勢遞增**：MySQL InnoDB 使用聚集索引，B-tree 資料結構下應盡量使用有序主鍵以保證寫入效能。
+- **單調遞增**：保證下一個 ID 一定大於上一個 ID，適用於交易版本號、IM 增量訊息、排序等場景。
+- **資訊安全**：連續 ID 容易被惡意爬取或讓競爭對手推算訂單量，某些場景下需要 ID 無規則。
+
+---
+
+## 27.2 分散式 ID 種類
+
+| 類型 | 說明 |
+|------|------|
+| 連續 GUID | 基於時間戳的有序 GUID |
+| 短 ID | 適用於低並發內部系統（任務 ID、Issue 編號等） |
+| 雪花演算法 ID | 2.1+ 版本已移除，建議自行整合 |
+
+---
+
+## 27.3 如何使用
+
+### 27.3.1 連續 GUID
+
+**靜態 `IDGen` 方式：**
+
+```csharp
+var guid = IDGen.NextID();
+
+// 更多參數
+var guid2 = IDGen.NextID(new SequentialGuidSettings { LittleEndianBinary16Format = true });
+```
+
+> ⚠️ 在迴圈中使用 `IDGen` 靜態類效能最差（底層不斷解析服務）。非迴圈中效能等同於以下兩種方式。
+
+**`IDistributedIDGenerator` 注入方式（推薦）：**
+
+```csharp
+private readonly IDistributedIDGenerator _idGenerator;
+
+public AppServices(IDistributedIDGenerator idGenerator)
+{
+    _idGenerator = idGenerator;
+    var guidObject = _idGenerator.Create();
+}
+```
+
+**`SequentialGuidIDGenerator` 方式：**
+
+```csharp
+var idGen = new SequentialGuidIDGenerator();
+var guid = idGen.Create();
+
+// 更多參數
+var guid2 = idGen.Create(new SequentialGuidSettings { LittleEndianBinary16Format = true });
+```
+
+### 27.3.2 短 ID
+
+```csharp
+var shortid = ShortIDGen.NextID(); // 包含數字、字母，不含特殊符號，8 位
+
+// 更多設定
+var shortid = ShortIDGen.NextID(new GenerationOptions
+{
+    UseNumbers = false,              // 不包含數字
+    UseSpecialCharacters = true,     // 包含特殊符號
+    Length = 8                       // 設定長度（不設定則為隨機長度）
+});
+
+// 自訂參與運算的字元
+ShortIDGen.SetCharacters("ⒶⒷⒸⒹⒺⒻⒼⒽⒾⒿⓀⓁⓂⓃⓄⓅⓆⓇⓈⓉⓊⓋⓌⓍⓎⓏ...");
+
+// 自訂隨機數步長
+ShortIDGen.SetSeed(1939048828);
+
+// 重置所有自訂設定
+ShortIDGen.Reset();
+```
+
+### 27.3.3 雪花演算法 ID
+
+Furion 2.1+ 版本已移除雪花演算法 ID 功能，因使用頻率不高且實作方式各異，建議採用擴充或自行整合的方式。

package/knowledge/Furion_Teaching_Manual/28-/346/250/241/347/265/204/345/214/226/351/226/213/347/231/274.md

@@ -0,0 +1,68 @@
+# 28. 模組化開發
+
+---
+
+## 28.1 概述
+
+模組化是將不同功能組裝在一起的程式碼組織方式，像樂高積木一樣，各模組形狀功能不同，互相依賴支撐，最終組成完整專案。
+
+### 模組分類
+
+| 類型 | 說明 |
+|------|------|
+| **應用程式模組** | 完整的應用程式，可獨立執行，有自己的實體、服務、API 及 UI |
+| **框架級模組** | 解決特定業務功能的模組，如上傳檔案、分散式快取、資料驗證等 |
+
+---
+
+## 28.3 啟用模組化支援
+
+> ⚠️ 以下設定**必須**在 `appsettings.json` 中設定才有效（啟動時自訂設定檔尚未載入）。
+
+```json
+{
+  "AppSettings": {
+    "EnabledReferenceAssemblyScan": true,
+    "SupportPackageNamePrefixs": ["Module1", "Module2"],
+    "ExternalAssemblies": ["plugins/Module1.dll", "plugins/Module2.dll"]
+  }
+}
+```
+
+### 四種新增模組方式
+
+| 方式 | 設定 | 說明 |
+|------|------|------|
+| **專案引用** | 無需設定 | 直接新增專案參考或編輯 `.csproj`，Furion 自動載入 |
+| **DLL 引用** | `EnabledReferenceAssemblyScan: true` | 新增 `.dll` 參考方式 |
+| **NuGet 安裝** | `SupportPackageNamePrefixs: [...]` | 設定 NuGet 套件名稱前綴 |
+| **動態載入 DLL** | `ExternalAssemblies: [...]` | 放入 plugins 資料夾，無需新增參考（4.9.2.14+ 支援目錄掃描） |
+
+### 動態載入 DLL 發佈設定
+
+預設插件/模組資料夾不會輸出到發佈目錄，需編輯 `.csproj`：
+
+```xml
+<ItemGroup>
+  <None Update="plugins\**\**">
+    <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+  </None>
+</ItemGroup>
+```
+
+---
+
+## 28.4 注意事項
+
+- 每個模組應有獨立的路由格式：`/模組名稱/路由位址`，避免衝突
+- 若包含 UI 元素（檢視、HTML/CSS/JS），應採用**嵌入式資源**方式
+- 模組需新增第三方服務時，應設定在 `AppStartup` 的衍生類別中
+- 模組的註解檔 `.xml` 需放在與 `.dll` 同級目錄
+
+---
+
+## 28.5 關於熱插拔機制
+
+Furion v2.4.0+ 已移除執行階段熱載入/熱卸載模組功能，因為微軟的 `AssemblyLoadContext` + 資料夾監控機制尚未成熟。
+
+目前框架僅支援**啟動時載入模組**，不在執行階段進行任何處理。