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

package/knowledge/Furion_Teaching_Manual/20-/351/231/204/351/214/204-KSort/350/263/207/346/226/231/347/260/275/345/220/215/345/256/214/346/225/264/345/216/237/345/247/213/347/242/274.md

@@ -0,0 +1,305 @@
+# KSort API 資料簽名 — 完整原始碼參考
+
+> Furion 4.9.5.10+ 內建，用於前後端資料完整性驗證，防止資料被篡改。
+
+---
+
+## 演算法原理
+
+1. 將 `app_id`、`app_key`、`command`、`data`、`timestamp` 組成字典
+2. 按 key 字母順序排序（KSort）
+3. 以半形逗號連接為 `key=value,key=value,...` 格式
+4. 對連接結果進行 MD5 加密（32 位小寫）作為 `signature`
+
+---
+
+## C# 後端原始碼
+
+### KSortEncryption.cs
+
+```csharp
+using System.Text.Json;
+
+namespace Furion.DataEncryption;
+
+/// <summary>
+/// KSort 加密（資料簽名）
+/// </summary>
+[SuppressSniffer]
+public class KSortEncryption
+{
+    private static DateTime _timeStampStartTime = new(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc);
+
+    /// <summary>
+    /// 資料加密（簽名）
+    /// </summary>
+    public static KSortSignature Encrypt(string appId, string appKey, string command, string data, long? timestamp = null)
+    {
+        ArgumentNullException.ThrowIfNull(appId);
+        ArgumentNullException.ThrowIfNull(appKey);
+        ArgumentNullException.ThrowIfNull(command);
+
+        timestamp ??= (long)(DateTime.Now.ToUniversalTime() - _timeStampStartTime).TotalMilliseconds;
+
+        var dic = new Dictionary<string, object>
+        {
+            { "app_id", appId },
+            { "app_key", appKey },
+            { "command", command },
+            { "data", data },
+            { "timestamp", timestamp },
+        };
+
+        // ksort 排序
+        var sortedDic = dic.OrderBy(kvp => kvp.Key);
+
+        // 半形逗號連接
+        var output = string.Join(",", sortedDic.Select(kvp => $"{kvp.Key}={kvp.Value}"));
+
+        // UTF-8 編碼，32 位小寫 MD5
+        var signature = MD5Encryption.Encrypt(output);
+
+        return new KSortSignature
+        {
+            app_id = appId,
+            app_key = appKey,
+            command = command,
+            data = data,
+            timestamp = timestamp.Value,
+            signature = signature
+        };
+    }
+
+    /// <summary>
+    /// 比較資料簽名（KSortSignature 物件）
+    /// </summary>
+    public static bool Compare(KSortSignature kSortSignature)
+    {
+        ArgumentNullException.ThrowIfNull(kSortSignature);
+        return Encrypt(kSortSignature.app_id, kSortSignature.app_key,
+            kSortSignature.command, kSortSignature.data, kSortSignature.timestamp) == kSortSignature;
+    }
+
+    /// <summary>
+    /// 比較資料簽名（JSON 字串）
+    /// </summary>
+    public static bool Compare(string signatureData)
+    {
+        var kSortSignature = JsonSerializer.Deserialize<KSortSignature>(signatureData);
+        ArgumentNullException.ThrowIfNull(kSortSignature);
+        return Encrypt(kSortSignature.app_id, kSortSignature.app_key,
+            kSortSignature.command, kSortSignature.data, kSortSignature.timestamp) == kSortSignature;
+    }
+}
+```
+
+### KSortSignature.cs
+
+```csharp
+/// <summary>
+/// KSort 簽名類
+/// </summary>
+public class KSortSignature : IEquatable<KSortSignature>
+{
+    public string app_id { get; set; }
+    public string app_key { get; set; }
+    public string command { get; set; }
+    public string data { get; set; }
+    public long timestamp { get; set; }
+    public string signature { get; set; }
+
+    public bool Equals(KSortSignature other)
+    {
+        if (other == null) return false;
+        return app_id == other.app_id &&
+               app_key == other.app_key &&
+               command == other.command &&
+               data == other.data &&
+               timestamp == other.timestamp &&
+               signature == other.signature;
+    }
+
+    public override bool Equals(object obj) => Equals(obj as KSortSignature);
+
+    public override int GetHashCode()
+        => HashCode.Combine(app_id, app_key, command, data, timestamp, signature);
+
+    public static bool operator ==(KSortSignature lhs, KSortSignature rhs)
+    {
+        if (ReferenceEquals(lhs, rhs)) return true;
+        if (lhs is null || rhs is null) return false;
+        return lhs.Equals(rhs);
+    }
+
+    public static bool operator !=(KSortSignature lhs, KSortSignature rhs) => !(lhs == rhs);
+}
+```
+
+---
+
+## TypeScript 前端原始碼
+
+### data-signature.ts
+
+```typescript
+import CryptoJS from "crypto-js";
+
+/**
+ * 生成 KSort 簽名
+ * @param appId APP_ID
+ * @param appKey APP_KEY
+ * @param command 命令
+ * @param data 資料
+ * @param timestamp 時間戳（可選）
+ */
+export function signatureByKSort(
+  appId: string,
+  appKey: string,
+  command: string,
+  data: any,
+  timestamp: number | null = null
+) {
+  // 序列化資料
+  const input =
+    typeof data === "string" ? (data as string) : JSON.stringify(data);
+
+  // 生成時間戳
+  if (!timestamp) {
+    timestamp =
+      new Date().getTime() - new Date("1970-01-01T00:00:00Z").getTime();
+  }
+
+  const sData: any = {
+    app_id: appId,
+    app_key: appKey,
+    command,
+    data: input,
+    timestamp,
+  };
+
+  // 取得所有 key 並排序
+  const keys = Object.keys(sData);
+  keys.sort();
+
+  // 生成簽名字串
+  let result = "";
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    const value = sData[key];
+    result += key + "=" + value;
+    if (i < keys.length - 1) {
+      result += ",";
+    }
+  }
+
+  // MD5 小寫加密
+  const hash = CryptoJS.MD5(result);
+  const hexString = hash.toString(CryptoJS.enc.Hex);
+  const signature = hexString.toLowerCase();
+
+  return {
+    app_id: appId,
+    app_key: appKey,
+    command,
+    data: input,
+    timestamp,
+    signature,
+  };
+}
+```
+
+> 需安裝：`npm install crypto-js`
+
+---
+
+## JavaScript 前端原始碼（ES Module）
+
+### data-signature.js
+
+```javascript
+import CryptoJS from "crypto-js";
+
+export function signatureByKSort(appId, appKey, command, data, timestamp = null) {
+  const input = typeof data === "string" ? data : JSON.stringify(data);
+
+  if (!timestamp) {
+    timestamp = new Date().getTime() - new Date("1970-01-01T00:00:00Z").getTime();
+  }
+
+  const sData = { app_id: appId, app_key: appKey, command, data: input, timestamp };
+
+  const keys = Object.keys(sData);
+  keys.sort();
+
+  let result = "";
+  for (let i = 0; i < keys.length; i++) {
+    result += keys[i] + "=" + sData[keys[i]];
+    if (i < keys.length - 1) result += ",";
+  }
+
+  const hash = CryptoJS.MD5(result);
+  const signature = hash.toString(CryptoJS.enc.Hex).toLowerCase();
+
+  return { app_id: appId, app_key: appKey, command, data: input, timestamp, signature };
+}
+```
+
+---
+
+## 使用範例
+
+### C# 簽名與驗證
+
+```csharp
+// 簽名
+var appId = "ca36cb2858ce3517df772ec34ce92f21";
+var appKey = "95e4a4f651c2d62679c4c150f2e39f4a";
+var command = "add.user";
+var data = JsonSerializer.Serialize(new { id = 1, name = "Furion" });
+
+KSortSignature sData = KSortEncryption.Encrypt(appId, appKey, command, data);
+
+// 驗證
+bool result = KSortEncryption.Compare(sData);       // KSortSignature 物件
+bool result2 = KSortEncryption.Compare(jsonString);  // JSON 字串
+```
+
+### TypeScript 前端簽名
+
+```typescript
+const sData = signatureByKSort(
+  "ca36cb2858ce3517df772ec34ce92f21",
+  "95e4a4f651c2d62679c4c150f2e39f4a",
+  "add.user",
+  { id: 1, name: "furion" }
+);
+
+fetch("http://furion.net/api/endpoint", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify(sData),
+}).then(res => res.json()).then(data => {});
+```
+
+### 後端接收（最佳實踐）
+
+```csharp
+[HttpPost]
+public async Task AddUser([Required] KSortSignature sData)
+{
+    // 驗證簽名
+    if (!KSortEncryption.Compare(sData))
+        throw new Exception("非法資料");
+
+    // 反序列化取得原始資料
+    var data = JsonSerializer.Deserialize<YourDataType>(sData.data);
+}
+```
+
+---
+
+## 注意事項
+
+- `appId` 和 `appKey` 應從伺服器動態取得，**切勿明文寫在客戶端程式碼中**
+- 可實作中介軟體統一驗證簽名
+- 簽名格式固定為：`app_id=xxx,app_key=xxx,command=xxx,data=xxx,timestamp=xxx` → MD5 32 位小寫

package/knowledge/Furion_Teaching_Manual/21-/345/205/250/347/220/203/345/214/226/345/222/214/346/234/254/345/234/260/345/214/226.md

@@ -0,0 +1,342 @@
+# 21. 全球化和本地化（多語言）
+
+---
+
+## 21.1 概述
+
+全球化是設計支援不同區域性的應用程式的過程；本地化是將全球化應用調整為特定區域設定的過程。Furion 框架提供了完整的多語言處理服務。
+
+---
+
+## 21.2 註冊服務
+
+```csharp
+public void ConfigureServices(IServiceCollection services)
+{
+    services.AddControllersWithViews()
+            .AddAppLocalization();  // 註冊多語言
+}
+
+public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
+{
+    // 必須在 app.UseRouting() 之前
+    app.UseAppLocalization();
+
+    app.UseStaticFiles();
+    app.UseRouting();
+}
+```
+
+> ⚠️ `app.UseAppLocalization()` 必須在 `app.UseRouting()` **之前**註冊。
+
+---
+
+## 21.3 基本設定
+
+### 21.3.1 LocalizationSettings 設定
+
+```json
+{
+  "LocalizationSettings": {
+    "SupportedCultures": ["zh-CN", "en-US"],
+    "DefaultCulture": "zh-CN"
+  }
+}
+```
+
+### 21.3.2 建立 Resources 資料夾
+
+在 **Web 啟動專案層**新增 `Resources` 資料夾。
+
+---
+
+## 21.4 L 靜態類
+
+| 屬性 / 方法 | 說明 |
+|-------------|------|
+| `L.Text[文字]` | 轉換文字多語言 |
+| `L.Html[HTML, 格式化]` | 轉換 HTML 多語言 |
+| `L.TextOf<T>()[文字]` | 使用完整型別限定名轉換（4.8.6+） |
+| `L.HtmlOf<T>()[HTML, 格式化]` | 使用完整型別限定名轉換（4.8.6+） |
+| `L.SetCulture(區域碼)` | 設定語言（下次請求生效）；第二個參數 `true` 立即生效 |
+| `L.GetSelectCulture()` | 取得目前語言區域 |
+| `L.GetCultures()` | 取得系統支援的多語言列表 |
+| `L.SetCurrentUICulture(區域碼)` | 執行階段設定目前執行緒語言，**立即生效**（4.8.3.10+） |
+| `L.GetCurrentUICulture()` | 取得目前執行緒 UI 區域性（4.8.3.10+） |
+| `L.GetString<T>(u => u.屬性)` | 根據表達式取得翻譯（4.8.3.10+） |
+| `L.GetString(name, culture)` | 取得指定區域翻譯（4.8.8.41+） |
+| `L.GetDefaultCulture()` | 取得本地設定預設語言（4.8.8.49+） |
+
+> `L.SetCulture` 實際上是寫入客戶端 Cookie，對**下次請求**生效。若需**立即生效**，可用 `L.SetCulture(區域碼, true)` 或搭配 `L.SetCurrentUICulture`。
+
+---
+
+## 21.5 使用範例
+
+### 在類別中使用
+
+```csharp
+var apiInterface = L.Text["API 接口"];
+var sourceCode = L.Text["源碼地址"];
+var other = L.Text["其他{0}", "的"];
+var name = L.Html["<b>Hello</b><i> {0}</i>", name];
+```
+
+### 在檢視中使用
+
+```razor
+@using Furion.Localization
+
+<a href="/api">@L.Text["API 接口"]</a>
+<a href="https://gitee.com/dotnetchina/Furion">@L.Text["源碼地址"]</a>
+```
+
+### 在驗證特性中使用
+
+```csharp
+[Required(ErrorMessage = "必填訊息")]
+```
+
+> 所有驗證特性已自動支援多語言，無需透過 `L.Text[]` 呼叫。
+
+### 在例外訊息中使用
+
+```csharp
+[ErrorCodeType]
+public enum ErrorCodes
+{
+    [ErrorCodeItemMetadata("使用者名稱不能為空")]
+    z1000
+}
+
+throw Oops.Oh(ErrorCodes.z1000); // 自動套用多語言
+```
+
+### SharedResource 模式（4.3.7+）
+
+建立 `SharedResource.cs`，定義屬性避免硬編碼字串散落各處：
+
+```csharp
+public class SharedResource
+{
+    public string Hello { get; set; }
+    public string Name { get; set; }
+}
+
+// 使用
+var hello = L.GetString<SharedResource>(u => u.Hello);
+var name = L.GetString<SharedResource>(u => u.Name);
+
+// 或使用 nameof
+var hello = L.Text[nameof(SharedResource.Hello)];
+```
+
+---
+
+## 21.6 建立語言翻譯檔案
+
+在 `Resources` 資料夾中新增 `.resx` 資源檔案，命名規則：`Lang.區域碼.resx`（如 `Lang.en-US.resx`），填入對應語言的鍵值對。
+
+> 若未找到對應翻譯，自動顯示原始字串：`L.Text["沒找到"]` → 直接輸出 `"沒找到"`。
+
+自訂資源檔名或存放程式集：
+
+```json
+{
+  "LocalizationSettings": {
+    "LanguageFilePrefix": "MyLang",
+    "AssemblyName": "你的其他層程式集名稱"
+  }
+}
+```
+
+---
+
+## 21.7 切換語言
+
+### 21.7.1 URL 參數方式（優先級最高）
+
+```
+?culture=en-US
+```
+
+自訂參數名稱（4.9.3.14+）：
+
+```csharp
+app.UseAppLocalization(options =>
+{
+    options.AddInitialRequestCultureProvider(new CustomizeQueryStringRequestCultureProvider("my-culture"));
+});
+```
+
+### 21.7.2 Cookies 方式
+
+```csharp
+L.SetCulture("en-US");
+```
+
+自訂 Cookie 名稱：
+
+```csharp
+app.UseAppLocalization(options =>
+{
+    options.AddInitialRequestCultureProvider(new CookieRequestCultureProvider { CookieName = "custom-cookie-name" });
+});
+```
+
+### 21.7.3 客戶端瀏覽器語言自動切換
+
+自動根據瀏覽器語言設定配置（推薦）。
+
+### 21.7.4 請求標頭方式
+
+```
+Accept-Language: en-US
+```
+
+### 21.7.5 Cookie 請求標頭方式
+
+```
+Cookie: c%3Den-US%7Cuic%3Den-US
+```
+
+明文格式：`c=en-US|uic=en-US`（必須使用 URL 編碼格式，`c` 和 `uic` 值通常一致）。
+
+---
+
+## 21.8 相依性注入方式
+
+```csharp
+public class TestController : Controller
+{
+    private readonly IStringLocalizer _localizer;
+
+    public TestController(IStringLocalizerFactory factory)
+    {
+        _localizer = factory.Create();
+    }
+
+    public IActionResult About()
+    {
+        ViewData["Message"] = _localizer["Your application description page."];
+    }
+}
+```
+
+---
+
+## 21.9 LocalizationSettings 完整設定
+
+| 屬性 | 型別 | 預設值 | 說明 |
+|------|------|--------|------|
+| `ResourcesPath` | `string` | `"Resources"` | 資源目錄 |
+| `SupportedCultures` | `string[]` | — | 支援的語言區域碼列表 |
+| `DefaultCulture` | `string` | 取 `SupportedCultures` 第一項 | 預設語言區域碼 |
+| `LanguageFilePrefix` | `string` | `"Lang"` | 資源檔案前綴 |
+| `AssemblyName` | `string` | 啟動層名稱 | 資源檔案存放程式集 |
+| `DateTimeFormatCulture` | `string` | — | DateTime 時間格式化區域（4.8.7.31+） |
+
+---
+
+## 21.10 中文無法切換問題
+
+透過 `dotnet build` 編譯發佈後可能無法生成 `zh-CN` 資源檔案。解決方式：將 `Lang.zh-CN.resx` 改為 `Lang.zh-Hans.resx` 或 `Lang.zh-Hant.resx` 或 `Lang.zh.resx`。
+
+---
+
+## 21.11 基於 JSON 檔案多語言（4.8.6+）
+
+`.resx` 無法在執行階段修改，推薦使用 `.json` 格式（可動態修改）。
+
+```bash
+dotnet add package My.Extensions.Localization.Json
+```
+
+```csharp
+public void ConfigureServices(IServiceCollection services)
+{
+    services.AddControllersWithViews()
+            .AddAppLocalization(settings =>
+            {
+                services.AddJsonLocalization(options => options.ResourcesPath = [settings.ResourcesPath]);
+            });
+}
+```
+
+在 `Resources` 資料夾中新增 `Lang.區域碼.json`（如 `Lang.en-US.json`），其餘用法與 `.resx` 完全相同。
+
+---
+
+## 21.13 在 WinForm / WPF 中使用
+
+### WinForm
+
+```csharp
+internal static class Program
+{
+    [STAThread]
+    static void Main()
+    {
+        Serve.RunNative(services => services.AddAppLocalization());
+        ApplicationConfiguration.Initialize();
+        Application.Run(new Form1());
+    }
+}
+
+// 使用
+L.SetCurrentUICulture("en-US");
+label1.Text = L.Text["API 接口"];
+```
+
+### WPF
+
+```csharp
+public partial class App : Application
+{
+    public App()
+    {
+        Serve.RunNative(services => services.AddAppLocalization());
+    }
+}
+
+// 使用
+L.SetCurrentUICulture("en-US");
+label1.Name = L.Text["API 接口"];
+```
+
+> 兩者都需添加 `appsettings.json`（設定為「如果較新則複製」）和 `Resources` 資料夾。
+
+---
+
+## 21.14 DateTime.Now 問題（4.8.7.31+）
+
+啟用多語言後 `DateTime.Now` 可能受時區影響。建議使用 `DateTime.UtcNow` 或 `DateTimeOffset.UtcNow`，或固定時間區域：
+
+```json
+{
+  "LocalizationSettings": {
+    "DateTimeFormatCulture": "zh-CN"
+  }
+}
+```
+
+---
+
+## 21.15 Blazor 專案注意事項
+
+`.razor` 元件僅支援 `Accept-Language` 請求標頭和 Cookie 方式切換語言。
+
+---
+
+## 更新日誌摘要
+
+| 版本 | 日期 | 內容 |
+|------|------|------|
+| 4.9.7.23 | 2025.03.10 | `L` 靜態屬性返回值改為非空 |
+| 4.9.6.19 | 2024.12.27 | 修復無法自訂 CookieName 問題 |
+| 4.9.3.14 | 2024.05.30 | 多語言支援自訂 Url/Cookie/Header 參數 |
+| 4.8.8.49 | 2023.10.25 | 新增 `L.GetDefaultCulture()` |
+| 4.8.8.41 | 2023.08.04 | 新增 `L.GetString(name, culture)` |
+| 4.8.7.31 | 2023.03.31 | 新增 `DateTimeFormatCulture` 設定 |
+| 4.8.6 | 2023.02.08 | 支援 `.json` 檔案設定方式 |
+| 4.8.3.10 | 2022.12.23 | 新增 `SetCurrentUICulture` / `GetCurrentUICulture` |