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

package/knowledge/Furion_Teaching_Manual/29-/346/265/201/350/256/212/347/211/251/344/273/266Clay.md

@@ -0,0 +1,313 @@
+# 29. 流變物件（Clay / Shapeless）
+
+> **版本說明**：僅適用於 Furion 4.9.7+，不支援 .NET 8 以下版本。Furion 已內建；非 Furion 框架可安裝 `Shapeless` 或 `Shapeless.AspNetCore`。
+
+---
+
+## 29.1 概述
+
+流變物件（Clay）是基於 `DynamicObject` 建立的執行階段動態派生物件，提供類似 JavaScript JSON 物件的靈活操作能力，支援動態增刪改查、Linq/Lambda 查詢。
+
+**應用場景**：動態資料操作、第三方 API 整合、CMS、工作流表單、微服務資料整合、快速原型開發、資料分析報表、事件驅動架構、設定管理、範本引擎、電商自訂參數等。
+
+---
+
+## 29.2 快速入門
+
+### 建立單一物件（`{}`）
+
+```csharp
+dynamic clay = new Clay();                    // 或 new Clay.Object()
+dynamic clay = Clay.EmptyObject();
+dynamic clay = Clay.Parse("{}");
+dynamic clay = Clay.Parse(new { id = 1 });
+
+// 便捷初始化
+dynamic clay = new Clay { ["id"] = 1, ["name"] = "Shapeless" };
+```
+
+### 建立集合或陣列（`[]`）
+
+```csharp
+dynamic clay = new Clay(ClayType.Array);      // 或 new Clay.Array()
+dynamic clay = Clay.EmptyArray();
+dynamic clay = Clay.Parse("[]");
+dynamic clay = Clay.Parse(new List<int> { 1, 2, 3 });
+```
+
+### 基本操作（單一物件）
+
+```csharp
+clay.Id = 1;                        // 屬性方式新增/設定
+clay["Name"] = "Furion";            // 索引方式
+clay.Author = new { Name = "MonkSoul" };  // 巢狀物件
+clay.Remove("Name");                // 刪除
+clay.Id += 1;                       // 修改
+Console.WriteLine(clay);            // 輸出 JSON
+Console.WriteLine($"{clay:UZC}");   // U=取消Unicode C=camelCase Z=壓縮 P=Pascal
+```
+
+### 基本操作（集合/陣列）
+
+```csharp
+clay.Add(1);                        // 追加
+clay.AddRange(new object[] { 2, 3 });
+clay.Insert(0, "first");            // 插入
+clay[0] = "modified";               // 修改
+clay.Remove(0);                     // 刪除
+clay.Pop();                         // 移除末項
+clay.Reverse();                     // 反轉
+clay[1..^1];                        // 截取（Range）
+```
+
+### 從多種來源建立
+
+```csharp
+Clay.Parse("""{"id":1}""");                    // JSON 字串
+Clay.Parse(new YourModel { Id = 1 });          // 具體型別
+Clay.Parse(new { id = 1 });                    // 匿名物件
+Clay.Parse(new Dictionary<string, object> { {"id", 1} });
+Clay.Parse(byteArray);                         // byte[]
+Clay.Parse(stream);                            // Stream
+Clay.Parse(jsonElement);                       // JsonElement
+Clay.ParseFromFile("path.json");               // 檔案
+Clay.Parse("form=data&key=val");               // URL 表單
+new { id = 1 }.ToClay();                       // ToClay() 擴充方法
+```
+
+**隱式轉換**（4.9.8.12+）：
+
+```csharp
+Clay clay = """{"id":1}""";                    // string → Clay
+string json = Clay.Parse("{}");                // Clay → string
+Dictionary<string, object?> dic = clay;        // Clay → Dictionary
+```
+
+### 型別轉換
+
+```csharp
+ClayModel model = clay;                        // 隱式轉換
+var model = (ClayModel)clay;                   // 顯式轉換
+var model = clay.As<ClayModel>();              // As<T>() 方法
+var model = clay.As<ClayModel>(new JsonSerializerOptions { PropertyNameCaseInsensitive = true });
+XElement xml = clay;                           // 轉 XML
+IActionResult result = clay;                   // 轉 IActionResult
+
+// 屬性型別轉換
+var date = clay.date<DateTime>();
+var val = clay.Get<int>("id");
+var val = clay.Get("id", typeof(int));
+```
+
+### 輸出格式
+
+| 方法 | 說明 |
+|------|------|
+| `clay.ToString()` / `Console.WriteLine(clay)` | JSON（預設格式化 + Unicode 編碼） |
+| `clay.ToString("U")` / `$"{clay:U}"` | 取消中文 Unicode |
+| `clay.ToString("Z")` | 壓縮 JSON |
+| `clay.ToString("C")` / `"P"` | camelCase / PascalCase |
+| `clay.ToString("ZUC")` | 組合使用 |
+| `clay.ToJsonString(options)` | 完整 JsonSerializerOptions 控制 |
+| `clay.ToXmlString(settings)` | XML 輸出 |
+| `clay()` | 等同 `ToJsonString()` |
+
+---
+
+## 29.3 Clay 型別 API 速查
+
+### 內建屬性
+
+| 屬性 | 型別 | 說明 |
+|------|------|------|
+| `IsObject` / `IsArray` | `bool` | 型別判斷 |
+| `Type` | `ClayType` | Object / Array |
+| `Count` / `Length` | `int` | 鍵/元素數量 |
+| `IsEmpty` | `bool` | 是否為空 |
+| `Keys` | `IEnumerable<object>` | 鍵/索引列表 |
+| `MemberNames` | `IEnumerable<string>` | 屬性名列表（僅單一物件） |
+| `Values` | `IEnumerable<dynamic?>` | 值/元素列表 |
+| `IsReadOnly` | `bool` | 是否唯讀 |
+
+### 標識符（運算子）
+
+支援：字串鍵、整數索引、`Index`（`^1`）、`Range`（`1..^2`）、路徑（`AppInfo:Company:Name`）、JSON Path（`$.AppInfo.Company`）。
+
+### 核心方法
+
+| 方法 | 說明 |
+|------|------|
+| `Get(id)` / `Get<T>(id)` | 取值（支援型別轉換） |
+| `Set(id, value)` | 設值 |
+| `Contains(id)` / `IsDefined(id)` / `HasProperty(name)` | 檢查是否定義 |
+| `FindNode(id)` / `FindNodeByPath(path)` | 查找 JsonNode 節點 |
+| `Add(v)` / `Push(v)` / `Append(v)` / `AddRange(...)` | 追加（陣列） |
+| `Insert(index, v)` / `InsertRange(index, ...)` | 插入（陣列） |
+| `Pop()` | 移除末項（陣列） |
+| `Remove(id)` / `Delete(id)` | 刪除 |
+| `Reverse()` | 反轉 |
+| `Slice(range)` / `this[Range]` | 截取（陣列） |
+| `Combine(clay2, clay3)` | 合併多個流變物件 |
+| `DeepClone()` | 深度克隆 |
+| `Clear()` | 清空資料 |
+| `AsReadOnly()` / `AsMutable()` | 唯讀/可寫模式切換 |
+| `Rebuilt(options)` | 重建（套用新 ClayOptions） |
+| `KSort()` / `KRSort()` | 按鍵升序/降序排序（單一物件） |
+| `Extend(...)` | 擴充資料 |
+| `IndexOf(value)` | 取得元素索引（陣列） |
+| `Equals(other)` / `==` / `!=` | 相等比較 |
+| `WriteTo(Utf8JsonWriter)` | 寫入 JsonWriter |
+
+### 路徑操作
+
+```csharp
+clay.PathValue("AppInfo:Company:Name");          // 取值
+clay.SetPathValue("AppInfo:Name", "新值");        // 設值（僅更新已存在路徑）
+clay.RemovePathValue("AppInfo:Name");             // 刪除
+clay.ContainsByPath("AppInfo:Name");              // 檢查
+clay.FindNodeByPath("AppInfo:Company:Name");      // 查找 JsonNode
+clay["AppInfo:Name", true];                       // 路徑索引（第二參數 true）
+```
+
+### 遍歷與查詢
+
+```csharp
+// ForEach
+foreach (KeyValuePair<string, dynamic?> item in clay) { }  // 單一物件
+foreach (var item in array) { }                              // 陣列
+
+// 解構函數（推薦用於 Lambda/Linq）
+var (clay, enumerable) = Clay.Parse("...");
+var list = enumerable.Where(u => u?.Key == "id").ToList();
+
+// Map / Filter
+clay.Map(new Func<dynamic?, object?>(item => new { data = item?.Value }));
+clay.Filter(new Func<dynamic?, bool>(item => item?.Key != "id"));
+
+// 管道轉換
+dynamic data = Clay.Parse(json).Pipe(u => u.data);
+dynamic data = Clay.Parse(json).PipeTry(u => u.data2).Pipe(u => u.data);
+```
+
+### 動態委託方法（僅單一物件）
+
+```csharp
+clay.sayHello = (Func<string>)(() => $"Hello, {clay.name}!");
+Console.WriteLine(clay.sayHello());
+
+// 使用 ClayContext 避免閉包問題
+clay.greet = (Func<ClayContext, string>)(ctx => $"Hello, {ctx.Current.name}!");
+Console.WriteLine(clay.greet());  // 無需傳入 ClayContext
+```
+
+### 處理 JSON 雙重序列化
+
+```csharp
+dynamic clay = Clay.Parse(json).ParseJson("fieldName");  // 指定路徑
+dynamic clay = Clay.Parse(json).ParseJson();              // 自動遍歷（預設深度 3）
+```
+
+---
+
+## 29.4 ClayOptions 設定
+
+| 屬性 | 型別 | 預設值 | 說明 |
+|------|------|--------|------|
+| `ScalarValueKey` | `string` | `"value"` | 非物件/陣列字面量的鍵名 |
+| `AllowMissingProperty` | `bool` | `false` | 允許存取不存在的屬性（回傳 null） |
+| `AllowIndexOutOfRange` | `bool` | `false` | 允許存取越界索引（回傳 null） |
+| `AutoCreateNestedObjects` | `bool` | `false` | 自動建立巢狀物件 |
+| `AutoCreateNestedArrays` | `bool` | `false` | 自動建立巢狀陣列 |
+| `AutoExpandArrayWithNulls` | `bool` | `false` | 超出陣列長度時自動補 null |
+| `ValidateAfterConversion` | `bool` | `false` | 轉換後執行模型驗證 |
+| `DateJsonToDateTime` | `bool` | `false` | 日期字串自動轉 DateTime |
+| `KeyValueJsonToObject` | `bool` | `false` | key/value JSON 轉單一物件 |
+| `PropertyNameCaseInsensitive` | `bool` | `false` | 屬性名不區分大小寫 |
+| `PathSeparator` | `string[]` | `[":"]` | 路徑分隔符 |
+| `ReadOnly` | `bool` | `false` | 唯讀模式 |
+| `JsonSerializerOptions` | — | 預設設定 | JSON 序列化選項 |
+
+**快捷設定**：`ClayOptions.Flexible`（AllowMissingProperty + AllowIndexOutOfRange + PropertyNameCaseInsensitive 皆為 true）。
+
+---
+
+## 29.5 事件監聽
+
+```csharp
+Clay clayObject = clay;  // 需轉回 Clay 型別
+
+clayObject.Changing += (sender, args) => { };   // 變更前
+clayObject.Changed += (sender, args) => { };    // 變更後
+clayObject.Removing += (sender, args) => { };   // 移除前
+clayObject.Removed += (sender, args) => { };    // 移除後
+
+// 或使用 AddEvent（無需型別轉換）
+clay.AddEvent("Changed", new ClayEventHandler((sender, args) => { }));
+clay.AddEvent("Changed", new Action<dynamic, ClayEventArgs>((sender, args) => { }));
+```
+
+---
+
+## 29.2.11 在 ASP.NET 應用中使用
+
+### 設定
+
+```csharp
+services.AddControllers()
+    .AddClayOptions(options => { options.KeyValueJsonToObject = true; });
+```
+
+### WebAPI
+
+```csharp
+[HttpPost]
+public dynamic PostClay([Clay] dynamic clay) => clay;
+
+[HttpPost]
+public YourModel PostData()
+{
+    dynamic clay = Clay.Parse("""{"id":1}""");
+    return clay;  // 自動轉換為目標型別
+}
+```
+
+### MVC
+
+```csharp
+public IActionResult Index()
+    => View(Clay.Parse("""{"id":1,"name":"Furion"}"""));
+// 視圖：@model dynamic → @Model.id
+```
+
+---
+
+## 29.7 HTTP 遠端請求中使用
+
+```csharp
+// 設定轉換器
+services.AddHttpRemote().ConfigureOptions(opt =>
+    opt.JsonSerializerOptions.AddClayConverters());
+
+// 發送請求
+dynamic payload = new Clay();
+payload.id = 1;
+var content = await httpRemoteService.PostAsStringAsync(url,
+    b => b.SetJsonContent(payload));
+dynamic result = Clay.Parse(content);
+```
+
+---
+
+## 29.8 常見問題速查
+
+| 問題 | 解法 |
+|------|------|
+| 屬性不存在拋異常 | `ClayOptions.Flexible` 或 `AllowMissingProperty = true` |
+| 索引越界拋異常 | `AllowIndexOutOfRange = true` |
+| 屬性大小寫敏感 | `PropertyNameCaseInsensitive = true` |
+| C# 關鍵字鍵名 | 屬性方式加 `@`（如 `clay.@int`），索引方式不需要 |
+| 中文亂碼 | `ToString("U")` 或 `ToJsonString()` |
+| WebAPI 回傳 key/value 格式 | 新增 `.AddClayOptions()` |
+| 捕獲溢出欄位 | 在目標型別加 `[JsonExtensionData] Dictionary<string, JsonElement>` |
+| Newtonsoft.Json 支援 | `.AddNewtonsoftJson(opt => opt.SerializerSettings.Converters.AddClayConverters())` |
+| Swagger Schema 問題 | 用 `<remarks>` + Markdown 描述參數格式 |

package/knowledge/Furion_Teaching_Manual/30-/350/204/253/346/225/217/350/231/225/347/220/206/357/274/210Sensitive Detection).md"

@@ -0,0 +1,168 @@
+# Furion 脫敏處理（Sensitive Detection）筆記
+
+> 適用版本：Furion 2.4.4+，部分功能需更高版本，詳見各節說明。
+
+---
+
+## 版本更新重點
+
+| 類型 | 說明 | 版本 |
+|------|------|------|
+| 新增 | `[SensitiveDetection]` 特性支援 `ShowSensitiveWords` 屬性顯示命中敏感詞 | 4.9.8.10 |
+| 新增 | `[SensitiveDetection]` 特性支援預設錯誤訊息 | 4.9.8.13 |
+| 新增 | 全模組同步方法（`GetWords`、`IsValid`、`Replace`、`FoundSensitiveWords`） | 4.9.8.10 |
+| 新增 | 支援自訂嵌入詞庫檔名 | 4.9.1.45 |
+| 新增 | `FoundSensitiveWordsAsync`：取得敏感詞及位置 | 4.9.1.45 |
+| **調整** | `VaildedAsync` 更名為 `IsValidAsync` | 4.9.8.9 |
+| 修復 | `[SensitiveDetection]` 不支援格式符 `{0}` | 4.9.8.10 |
+| 修復 | 跨平台換行符差異導致詞彙分割失敗 | 4.9.8.9 |
+| 修復 | 程式集名自訂導致無法載入詞庫資源 | 4.9.7.119 |
+
+---
+
+## 1. 註冊服務
+
+```csharp
+// 基本註冊
+services.AddSensitiveDetection();
+
+// 自訂詞庫檔名（4.9.1.45+）
+services.AddSensitiveDetection(options =>
+{
+    options.EmbedFileName = "custom-words.txt";
+});
+
+// 自訂 Provider
+services.AddSensitiveDetection<YourSensitiveDetectionProvider>();
+```
+
+---
+
+## 2. 詞庫檔案（sensitive-words.txt）
+
+- 在 Web 啟動層建立 `sensitive-words.txt`
+- 編碼：**UTF-8**（4.8.6.7+ 支援 UTF-8 BOM）
+- 必須設定為**嵌入式資源**
+
+```
+// 每行一個詞（換行格式）
+壞人
+無語
+滾開
+
+// 或用 | 分隔（3.8.9+，節省空間）
+壞人|無語|滾開|八嘎
+```
+
+> ⚠️ 若未設為嵌入式資源，詞庫將無法載入。
+
+---
+
+## 3. 使用方式
+
+### 3.1 Attribute 驗證（自動）
+
+```csharp
+public class Content
+{
+    // 基本用法
+    [SensitiveDetection]
+    public string Text { get; set; }
+
+    // 自訂錯誤訊息
+    [SensitiveDetection(ErrorMessage = "包含敏感詞")]
+    public string Title { get; set; }
+
+    // 顯示命中詞（4.9.8.10+）
+    [SensitiveDetection(
+        ErrorMessage = "{0} 包含敏感詞，命中：{1}",
+        ShowSensitiveWords = true)]
+    public string Comment { get; set; }
+
+    // 自動替換為指定字元（3.8.8+ 支援方法參數）
+    [SensitiveDetection('*')]
+    public string Body { get; set; }
+}
+
+// DynamicApi / Controller 參數
+public void Post([SensitiveDetection] string text) { }
+public void Post([SensitiveDetection('*')] string text) { }
+```
+
+### 3.2 ISensitiveDetectionProvider（手動）
+
+```csharp
+public class YourService : IDynamicApiController
+{
+    private readonly ISensitiveDetectionProvider _sdp;
+
+    public YourService(ISensitiveDetectionProvider sdp)
+    {
+        _sdp = sdp;
+    }
+
+    // 取得所有敏感詞
+    public async Task<IEnumerable<string>> GetWordsAsync()
+        => await _sdp.GetWordsAsync();
+
+    // 驗證：true = 正常，false = 命中敏感詞
+    public async Task<bool> IsValidAsync(string text)
+        => await _sdp.IsValidAsync(text);
+
+    // 替換命中詞為 *
+    public async Task<string> ReplaceAsync(string text)
+        => await _sdp.ReplaceAsync(text, '*');
+
+    // 取得命中詞與位置（4.9.1.45+）
+    public async Task<Dictionary<string, List<int>>> FoundAsync(string text)
+        => await _sdp.FoundSensitiveWordsAsync(text);
+}
+```
+
+---
+
+## 4. 介面方法速查
+
+| 方法 | 回傳值 | 說明 |
+|------|--------|------|
+| `GetWordsAsync()` | `IEnumerable<string>` | 取得所有敏感詞清單 |
+| `IsValidAsync(text)` | `bool` | `true` = 無敏感詞（正常） |
+| `ReplaceAsync(text, '*')` | `string` | 將命中詞替換為指定字元 |
+| `FoundSensitiveWordsAsync(text)` | `Dictionary<string, List<int>>` | 命中詞與其位置索引（4.9.1.45+） |
+
+> 4.9.8.10+ 以上方法均有同步版本（去掉 `Async` 後綴）。
+
+---
+
+## 5. 自訂 Provider
+
+```csharp
+public class DbSensitiveProvider : ISensitiveDetectionProvider
+{
+    // 從資料庫取詞，建議搭配 MemoryCache / Redis
+    public async Task<IEnumerable<string>> GetWordsAsync()
+    {
+        // 實作：查 DB 或快取
+    }
+
+    // true = 正常，false = 命中敏感詞
+    public async Task<bool> IsValidAsync(string text)
+    {
+        // 實作：判斷邏輯
+    }
+
+    // 替換命中詞
+    public async Task<string> ReplaceAsync(string text, char transfer = '*')
+    {
+        // 實作：替換邏輯
+    }
+
+    // 查找詞與位置（4.9.1.45+）
+    public async Task<Dictionary<string, List<int>>> FoundSensitiveWordsAsync(string text)
+    {
+        // 實作：查找邏輯
+    }
+}
+```
+
+> 💡 `GetWordsAsync` 若從資料庫取詞，務必搭配快取，避免每次請求都查 DB。

package/knowledge/Furion_Teaching_Manual/32-/346/234/203/350/251/261/345/222/214/347/213/200/346/205/213/347/256/241/347/220/206.md

@@ -0,0 +1,147 @@
+# 32. 會話和狀態管理
+
+---
+
+## 32.1 概述
+
+HTTP 是無狀態的協定，預設不保留使用者資料。可透過以下方式保留請求間的使用者資料：
+
+| 方式 | 儲存位置 | 生命週期 |
+|------|---------|---------|
+| **Cookie** | 客戶端 | 可設定過期時間 |
+| **Session** | 伺服器端（記憶體/分散式） | 閒置逾時後銷毀 |
+| **Query Strings** | URL 參數 | 單次請求 |
+| **HttpContext.Items** | 伺服器端 | 單次請求結束即銷毀 |
+| **Cache** | 伺服器端 | 依快取策略 |
+| **AsyncLocal\<T\>** | 非同步控制流 | 跨執行緒共享 |
+
+---
+
+## 32.2 使用方式
+
+### 32.2.1 Cookie
+
+```csharp
+// 讀取
+var value = httpContext.Request.Cookies["key"];
+
+// 設定
+var option = new CookieOptions { Expires = DateTime.Now.AddMilliseconds(10) };
+httpContext.Response.Cookies.Append(key, value, option);
+
+// 刪除
+httpContext.Response.Cookies.Delete(key);
+```
+
+> `httpContext` 可透過 `IHttpContextAccessor` 或 `App.HttpContext` 取得。Cookie 還可實現授權及單點登入（SSO）。
+
+### 32.2.2 Session
+
+**註冊服務**（必須在控制器之前）：
+
+```csharp
+services.AddSession(options =>
+{
+    options.IdleTimeout = TimeSpan.FromSeconds(10);
+    options.Cookie.HttpOnly = true;
+    options.Cookie.IsEssential = true;
+});
+```
+
+**註冊中介軟體**（必須在 `UseRouting` 和 `UseEndpoints` 之間）：
+
+```csharp
+app.UseRouting();
+app.UseAuthentication();
+app.UseAuthorization();
+app.UseSession();  // ← 在這裡
+app.UseEndpoints(...);
+```
+
+**常見操作**：
+
+```csharp
+// 讀取
+var str = httpContext.Session.GetString("key");
+var num = httpContext.Session.GetInt32("key");
+
+// 設定
+httpContext.Session.SetString("key", "value");
+httpContext.Session.SetInt32("key", 1);
+```
+
+**自訂任意型別擴充**：
+
+```csharp
+public static class SessionExtensions
+{
+    public static void Set<T>(this ISession session, string key, T value)
+        => session.SetString(key, JsonSerializer.Serialize(value));
+
+    public static T Get<T>(this ISession session, string key)
+    {
+        var value = session.GetString(key);
+        return value == null ? default : JsonSerializer.Deserialize<T>(value);
+    }
+}
+```
+
+**防止 Session ID 改變或失效**：
+
+```csharp
+services.Configure<CookiePolicyOptions>(options =>
+{
+    options.CheckConsentNeeded = context => false;
+    options.MinimumSameSitePolicy = SameSiteMode.None;
+});
+```
+
+### 32.2.3 Query Strings
+
+```csharp
+var value = httpContext.Request.Query["key"];
+```
+
+### 32.2.4 HttpContext.Items
+
+單次請求間共享資料，請求結束立即銷毀，可儲存任何型別：
+
+```csharp
+// 讀取
+var value = httpContext.Items["key"];
+
+// 設定
+httpContext.Items["key"] = "任何值包括物件";
+
+// 刪除
+httpContext.Items.Remove("key");
+```
+
+### 32.2.5 Cache
+
+參見 **14. 分散式快取** 章節。
+
+### 32.2.6 AsyncLocal\<T\>
+
+跨執行緒、非同步控制流中共享資料的利器：
+
+```csharp
+static AsyncLocal<string> _asyncLocalString = new AsyncLocal<string>();
+
+_asyncLocalString.Value = "Value 1";
+// 在非同步方法中仍可正確讀取 "Value 1"
+```
+
+> `AsyncLocal<T>` 會隨非同步控制流傳遞值，而 `ThreadLocal<T>` 在 `await` 之後可能丟失值。
+
+**Furion 簡化用法**（v2.18+）：
+
+```csharp
+// 設定
+CallContext.SetLocalValue("name", "Furion");
+CallContext<int>.SetLocalValue("count", 1);
+
+// 讀取
+var name = CallContext.GetLocalValue("name");
+var count = CallContext<int>.GetLocalValue("count");
+```