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

package/knowledge/Furion_Teaching_Manual/35-1-Docker/347/222/260/345/242/203/346/214/201/347/272/214/351/203/250/347/275/262Jenkins.md

@@ -0,0 +1,169 @@
+# 35.1 Docker 環境持續部署（Jenkins）
+
+---
+
+## 35.1.1 概述
+
+利用包含 .NET 環境的 Jenkins Docker 映像檔，實現持續化部署。
+
+---
+
+## 35.1.2 安裝 Docker 版 Jenkins
+
+標準 `jenkins:lts` 映像檔無法執行 `dotnet` 命令，需自行建置包含 .NET SDK 的映像檔。
+
+### Dockerfile
+
+```dockerfile
+FROM jenkins/jenkins:lts
+USER root
+WORKDIR /dotnet
+RUN apt-get update && apt-get install -y wget && rm -rf /var/lib/apt/lists/*
+RUN wget -O dotnet.tar.gz https://download.visualstudio.microsoft.com/download/pr/.../dotnet-sdk-5.0.100-linux-x64.tar.gz
+RUN tar zxf dotnet.tar.gz -C ./ && rm -rf dotnet.tar.gz
+ENV PATH="${PATH}:/dotnet:/var/jenkins_home/.dotnet/tools"
+ENV DOTNET_ROOT="/dotnet"
+RUN apt update -y && apt install icu-devtools vim zip unzip -y
+RUN usermod -a -G root jenkins
+USER jenkins
+```
+
+> SDK 下載連結請至微軟官網取得對應版本：https://dotnet.microsoft.com/download
+
+### 建置與執行
+
+```bash
+# 建置映像檔
+docker build -t jenkins:dotnet .
+
+# 執行容器
+docker run -d -p 8080:8080 -p 50000:50000 --name mjenkins \
+  --privileged=true --restart always -u root \
+  -e TZ="Asia/Shanghai" \
+  -v /mudata/jenkins:/var/jenkins_home \
+  -v /usr/bin/docker:/usr/bin/docker \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  -v /mudata/webroot/:/mudata/webroot \
+  jenkins:dotnet
+```
+
+---
+
+## 35.1.3 自動化部署（本地）
+
+### Shell 腳本
+
+```bash
+#!/bin/bash
+# Jenkins 建置腳本（測試服）
+
+solutionName=YourProject.Web.Entry
+containerName=yourcontainer
+port=9994
+csprojDir=${solutionName}/${solutionName}.csproj
+webDir=/mudata/webroot/jenkins/publish/webapp
+
+dotnet restore
+
+# 清空並發佈
+rm -rf ${webDir}/${JOB_NAME}/*
+dotnet publish ${JENKINS_HOME}/workspace/${JOB_NAME}/${csprojDir} \
+  -c Release -o ${webDir}/${JOB_NAME} /p:Version=1.0.${BUILD_NUMBER}
+
+# 停止並移除舊容器
+CID=$(docker ps -a | grep "${containerName}" | awk '{print $1}')
+if [ "$CID" != "" ]; then
+  docker stop ${containerName}
+  docker rm ${containerName}
+  docker rmi ${containerName}
+fi
+
+# 重新建置並執行
+docker build -t ${containerName} ${webDir}/${JOB_NAME}/.
+docker run --name ${containerName} --restart=always -d \
+  -p ${port}:${port} -v /etc/localtime:/etc/localtime:ro ${containerName}
+
+echo "success!"
+```
+
+> 流程：拉取原始碼 → `dotnet publish` → `docker build` → `docker run`。可設定分支合併後自動觸發建置。
+
+---
+
+## 35.1.4 自動化遠端部署
+
+### 前置條件
+
+安裝 Jenkins 外掛：**Publish Over SSH**，並在「系統管理 → Publish over SSH」設定 SSH 伺服器。
+
+### 建置腳本（Jenkins 端）
+
+```bash
+#!/bin/bash
+# 發佈並打包
+
+solutionName=YourProject.Web.Entry
+csprojDir=/${solutionName}/${solutionName}.csproj
+webDir=/mudata/webroot/jenkins/publish/webapp
+
+dotnet restore
+
+rm -rf ${webDir}/${JOB_NAME}/*
+dotnet publish ${JENKINS_HOME}/workspace/${JOB_NAME}/${csprojDir} \
+  -c Release -o ${webDir}/${JOB_NAME} /p:Version=1.0.${BUILD_NUMBER}
+
+# 打包
+rm -rf ${JENKINS_HOME}/workspace/${JOB_NAME}/publish
+mkdir ${JENKINS_HOME}/workspace/${JOB_NAME}/publish
+tar -czvf ${JENKINS_HOME}/workspace/${JOB_NAME}/publish/${JOB_NAME}.${BUILD_NUMBER}.tar.gz \
+  -C ${webDir}/${JOB_NAME} .
+
+echo "success!"
+```
+
+### 建置後操作（Send Build artifacts over SSH）
+
+| 設定 | 值 |
+|------|------|
+| Source files | `publish/` |
+| Remote directory | `/mudata/webroot/publish/` |
+| Exec command | `bash /mudata/shell/publish.sh ${JOB_NAME} yourcontainer ${JOB_NAME}.${BUILD_NUMBER} 9994` |
+
+> Source files 必須是 workspace 下的路徑。Jenkins 環境變數都可使用。
+
+### 遠端執行腳本（publish.sh）
+
+```bash
+#!/bin/bash
+# 遠端伺服器部署腳本
+
+solutionName=$1
+containerName=$2
+filename=$3
+port=$4
+baseDir=/mudata/webroot/publish
+webDir=${baseDir}/publish/${filename}
+
+# 解壓
+rm -rf ${webDir} && mkdir ${webDir}
+tar -zxvf ${baseDir}/publish/${filename}.tar.gz -C ${webDir}/
+
+# 替換正式環境設定
+rm -f ${webDir}/appsettings.json
+mv ${webDir}/appsettings.Prod.json ${webDir}/appsettings.json
+
+# 停止並移除舊容器
+CID=$(docker ps -a | grep "${containerName}" | awk '{print $1}')
+if [ "$CID" != "" ]; then
+  docker stop ${containerName}
+  docker rm ${containerName}
+  docker rmi ${containerName}
+fi
+
+# 建置並執行
+cd ${webDir}/ && docker build -t ${containerName} .
+docker run --name ${containerName} --restart=always -d \
+  -p ${port}:${port} -v /etc/localtime:/etc/localtime:ro ${containerName}
+```
+
+> 流程：Jenkins 發佈打包 → SSH 傳送到遠端 → 解壓 → 替換設定檔 → `docker build` → `docker run`。每次建置都帶版本號。

package/knowledge/Furion_Teaching_Manual/36-1-/345/226/256/345/205/203/346/270/254/350/251/246/346/225/264/345/220/210/346/270/254/350/251/246.md

@@ -0,0 +1,275 @@
+# 36.1 單元測試 / 整合測試
+
+---
+
+## 36.1.1 概述
+
+單元測試是對軟體中最小可測試單元進行檢查和驗證的過程。好處包括：消滅低級錯誤、找出潛在 bug、上線前保證、重構機會、重新 review 程式碼。
+
+測試類型：基於 API 介面測試（白盒 + 淺度黑盒）、基於專案程式碼測試（深度白盒）。
+
+> Furion 框架使用 **xUnit** 進行單元測試。
+
+---
+
+## 36.1.5 第一個範例
+
+### 建立 xUnit 專案並編寫測試
+
+```csharp
+using Xunit;
+
+public class UnitTest1
+{
+    [Fact]
+    public void Test1()
+    {
+        Assert.Equal(2, 1 + 1);
+    }
+}
+```
+
+> 標記 `[Fact]` 的方法為測試方法，使用 `Assert` 類進行斷言。
+
+### 帶參數的測試
+
+```csharp
+[Theory]
+[InlineData(1, 2)]
+[InlineData(3, 4)]
+[InlineData(5, 7)]
+public void 帶參數測試(int i, int j)
+{
+    Assert.NotEqual(0, (i + j) % 2);
+}
+```
+
+---
+
+## 36.1.6 整合 Furion
+
+### 安裝套件
+
+```bash
+# 完整版
+dotnet add package Furion.Xunit
+
+# 純淨版
+dotnet add package Furion.Pure.Xunit
+```
+
+> `Furion.Xunit` 已包含 `Furion`，無需重複安裝。請確保已安裝 `xunit` 套件。
+
+### 新增初始設定類 TestProgram.cs
+
+```csharp
+using Furion.Xunit;
+using Xunit.Abstractions;
+using Xunit.Sdk;
+
+[assembly: TestFramework("TestProject1.TestProgram", "TestProject1")]
+
+namespace TestProject1;
+
+public class TestProgram : TestStartup
+{
+    public TestProgram(IMessageSink messageSink) : base(messageSink)
+    {
+        Serve.RunNative(services =>
+        {
+            services.AddHttpRemote(); // 註冊所需服務
+        });
+    }
+}
+```
+
+> 若出現 `did not have matching fixture data` 錯誤，可設定 `urls: Serve.IdleHost.Urls`。
+
+### 編寫測試方法
+
+```csharp
+[Fact]
+public async Task 測試請求百度()
+{
+    var res = await _httpRemoteService.GetAsync("https://www.baidu.com");
+    Assert.True(res.IsSuccessStatusCode);
+}
+```
+
+---
+
+## 36.1.8 相依性注入
+
+### 建構子注入
+
+```csharp
+public class UnitTest1
+{
+    private readonly ICalcService _calcService;
+
+    public UnitTest1(ICalcService calcService)
+    {
+        _calcService = calcService;
+    }
+
+    [Fact]
+    public void 測試加法()
+    {
+        Assert.Equal(3, _calcService.Plus(1, 2));
+    }
+}
+```
+
+> Furion 會在建立測試實例時建立 `IServiceScope`，所有測試案例完成後自動 `Dispose`。
+
+### 輸出日誌
+
+```csharp
+public class UnitTest1
+{
+    private readonly ITestOutputHelper Output;
+
+    public UnitTest1(ITestOutputHelper tempOutput) => Output = tempOutput;
+
+    [Fact]
+    public void Test()
+    {
+        Output.WriteLine("我是 Furion");
+        Assert.NotEqual("Furion", "Fur");
+    }
+}
+```
+
+### 三種 Fixture 注入方式
+
+| 方式 | 有效範圍 | 用法 |
+|------|---------|------|
+| `[AssemblyFixture(typeof(T))]` | 全域所有測試類 | 在 `TestProgram.cs` 頂部標記 |
+| `IClassFixture<T>` | 單個測試類 | 測試類實作該介面 |
+| `ICollectionFixture<T>` + `[Collection]` | 多個測試類 | 定義 Collection 配置器 |
+
+**AssemblyFixture 範例：**
+
+```csharp
+[assembly: AssemblyFixture(typeof(MyAssemblyFixture))]
+
+public class MyAssemblyFixture : IDisposable
+{
+    public MyAssemblyFixture() { }
+    public void Dispose() { }
+}
+```
+
+**IClassFixture 範例：**
+
+```csharp
+public class UnitTest1 : IClassFixture<MyClassFixture>
+{
+    public UnitTest1(ICalcService calcService, MyClassFixture fixture) { }
+}
+```
+
+**ICollectionFixture 範例：**
+
+```csharp
+[CollectionDefinition("MyCollection")]
+public class MyCollection : ICollectionFixture<MyCollectionFixture> { }
+
+[Collection("MyCollection")]
+public class UnitTest1
+{
+    public UnitTest1(MyCollectionFixture collectionFixture) { }
+}
+```
+
+---
+
+## 36.1.9 Web 整合測試
+
+### 方式一：對現有專案進行整合測試
+
+1. 安裝 `Microsoft.AspNetCore.Mvc.Testing`
+2. 設定 Web 專案：
+
+**.NET 5**：新增 `FakeStartup.cs`（空類別）
+
+**.NET 6+**：編輯 `.csproj` 新增 `<InternalsVisibleTo Include="測試專案名" />`，並在 `Program.cs` 加入 `public partial class Program { }`
+
+3. 編寫測試：
+
+```csharp
+// .NET 5
+public class UnitTest1 : IClassFixture<WebApplicationFactory<WebApplication1.FakeStartup>>
+{
+    private readonly WebApplicationFactory<WebApplication1.FakeStartup> _factory;
+
+    public UnitTest1(WebApplicationFactory<WebApplication1.FakeStartup> factory)
+    {
+        _factory = factory;
+    }
+
+    [Theory]
+    [InlineData("/default")]
+    public async Task TestEnsureSuccessStatusCode(string url)
+    {
+        using var client = _factory.CreateClient();
+        using var response = await client.GetAsync(url);
+        response.EnsureSuccessStatusCode();
+    }
+}
+
+// .NET 6+：將泛型參數改為 WebApplicationFactory<Program>
+```
+
+主機額外設定（如環境變數）：
+
+```csharp
+_factory = factory.WithWebHostBuilder(builder =>
+{
+    builder.UseEnvironment("Stage");
+});
+```
+
+### 方式二：獨立主機方式
+
+```csharp
+[Fact]
+public void Test1()
+{
+    var builder = WebApplication.CreateBuilder();
+    builder.Services.AddScoped<IYourService, YourService>();
+
+    using var app = builder.Build();
+    app.Services.GetRequiredService<IYourService>();
+}
+```
+
+### 方式三：系統整合 / 環境 / 設定部署測試
+
+安裝 `Microsoft.AspNetCore.TestHost`，使用 `[assembly: HostingStartup(...)]` 特性。參考微軟官方範例。
+
+---
+
+## 36.1.10 Assert 斷言速查
+
+常用方法（第一個參數為期望值，第二個為實際值）：
+
+| 方法 | 說明 |
+|------|------|
+| `Assert.Equal(expected, actual)` | 相等 |
+| `Assert.NotEqual(expected, actual)` | 不相等 |
+| `Assert.True(condition)` | 為 true |
+| `Assert.False(condition)` | 為 false |
+| `Assert.Null(object)` | 為 null |
+| `Assert.NotNull(object)` | 不為 null |
+| `Assert.Contains(expected, collection)` | 集合包含 |
+| `Assert.Throws<T>(action)` | 拋出指定例外 |
+| `Assert.IsType<T>(object)` | 型別檢查 |
+
+> 完整 Assert 方法請查閱 xUnit 官方文件。
+
+---
+
+## 36.1.11 單元測試覆蓋率
+
+Visual Studio 提供內建的測試覆蓋率分析工具，可在「測試」選單中啟用。

package/knowledge/Furion_Teaching_Manual/36-3-/345/237/272/346/272/226/346/270/254/350/251/246Benchmarking.md

@@ -0,0 +1,80 @@
+# 36.3 基準測試（Benchmarking）
+
+---
+
+## 36.3.1 概述
+
+基準測試是一種測量和評估軟體效能指標的活動。透過建立已知的效能水準（基準線），在系統軟硬體環境變更後重新測試，以確定變更對效能的影響。其他用途包括：測定負載極限、管理環境變化、發現潛在效能問題等。
+
+### 特質
+
+- **可重複性**：可進行重複測試，比較結果取得長期變化趨勢
+- **可觀測性**：全方位監控（執行機、伺服器、資料庫）
+- **可展示性**：直觀呈現結果（儀表板、圖表）
+- **真實性**：反映客戶真實體驗
+- **可執行性**：可快速定位、分析、調優
+
+### 意義
+
+確定系統極限、提供設定參考依據、驗收系統能力、建立效能基線。
+
+---
+
+## 36.3.3 BenchmarkDotNet
+
+.NET 平台的基準測試工具，可將方法轉換為基準測試，追蹤效能並產生可重複的測量結果。
+
+### 使用方式
+
+1. 建立**主控台應用程式**
+2. 安裝 `BenchmarkDotNet` NuGet 套件
+3. 編寫測試：
+
+```csharp
+using System;
+using System.Security.Cryptography;
+using BenchmarkDotNet.Attributes;
+using BenchmarkDotNet.Running;
+
+namespace MyBenchmarks
+{
+    public class Md5VsSha256
+    {
+        private const int N = 10000;
+        private readonly byte[] data;
+        private readonly SHA256 sha256 = SHA256.Create();
+        private readonly MD5 md5 = MD5.Create();
+
+        public Md5VsSha256()
+        {
+            data = new byte[N];
+            new Random(42).NextBytes(data);
+        }
+
+        [Benchmark]
+        public byte[] Sha256() => sha256.ComputeHash(data);
+
+        [Benchmark]
+        public byte[] Md5() => md5.ComputeHash(data);
+    }
+
+    public class Program
+    {
+        public static void Main(string[] args)
+        {
+            var summary = BenchmarkRunner.Run<Md5VsSha256>();
+        }
+    }
+}
+```
+
+### 結果範例
+
+| Method | Runtime | N | Mean | Ratio |
+|--------|---------|-------|----------|-------|
+| Sha256 | .NET 4.7.2 | 10000 | 74.509 μs | 1.00 |
+| Sha256 | .NET Core 3.0 | 10000 | 36.049 μs | 0.49 |
+| Md5 | .NET 4.7.2 | 10000 | 17.308 μs | 1.00 |
+| Md5 | .NET Core 3.0 | 10000 | 15.726 μs | 0.90 |
+
+> BenchmarkDotNet 還支援匯出各種圖表報表。

package/knowledge/attributes.md

@@ -0,0 +1,153 @@
+# Admin.NET 自訂 Attribute 參考
+
+## 業務邏輯 Attribute
+
+### [IdempotentAttribute] — 冪等請求防重複
+```csharp
+[IdempotentAttribute(IntervalTime = 5, Message = "請勿重複提交", ThrowBah = false)]
+public async Task<Result> CreateOrder(OrderInput input)
+{
+    // 5 秒內重複呼叫會返回第一次的結果（或拋出例外）
+}
+```
+| 參數 | 說明 |
+|------|------|
+| IntervalTime | 防重複間隔秒數（預設 5） |
+| Message | 重複時的錯誤訊息 |
+| ThrowBah | true=拋出例外，false=返回快取結果 |
+
+**原理**：組合 路由+UserId+參數 產生 Hash，用分散式快取鎖防重複。
+
+---
+
+### [DataMask] — 資料遮罩
+```csharp
+// 手機號碼：134****1234
+[DataMask(3, 4)]  // 從第3位開始，遮罩4個字元
+public string PhoneNumber { get; set; }
+
+// 身分證：110***********1234
+[DataMask(3, 11)]
+public string IdCard { get; set; }
+```
+JSON 序列化時自動套用遮罩，不影響資料庫中的原始資料。
+
+---
+
+### [Dict] — 字典值驗證
+```csharp
+// 使用 Enum 驗證
+[Dict(SmsProviderEnum.Aliyun)]
+public SmsProviderEnum? Provider { get; set; }
+
+// 使用字典代碼驗證
+[Dict("user_status", AllowNullValue = true)]
+public string Status { get; set; }
+```
+| 參數 | 說明 |
+|------|------|
+| AllowNullValue | 是否允許 null（預設 false） |
+| AllowEmptyStrings | 是否允許空字串（預設 false） |
+
+---
+
+### [OwnerUser] — 資料擁有者標記
+```csharp
+[OwnerUser]
+public long? CreateUserId { get; set; }
+```
+標記此欄位為資料擁有者 ID，用於資料權限過濾。EntityBase 的 CreateUserId 已套用此 Attribute。
+
+---
+
+## 資料表初始化 Attribute
+
+### 資料庫路由 Attribute
+| Attribute | 用途 |
+|-----------|------|
+| `[SysTableAttribute]` | 強制使用主資料庫（不受多租戶影響） |
+| `[TenantAttribute]` | 路由至租戶專屬資料庫 |
+| `[LogTableAttribute]` | 路由至獨立 Log 資料庫 |
+| `[IgnoreTableAttribute]` | SqlSugar 不建立此資料表 |
+
+### 初始化行為 Attribute
+| Attribute | 用途 |
+|-----------|------|
+| `[SeedDataAttribute]` | 此實體有對應的種子資料類別 |
+| `[IncreTableAttribute]` | 允許增量更新資料表結構（新增欄位） |
+| `[IncreSeedAttribute]` | 允許增量更新種子資料（新增記錄） |
+| `[IgnoreUpdateSeedAttribute]` | 即使有 IncreTableAttribute 也跳過種子更新 |
+| `[IgnoreUpdateSeedColumnAttribute]` | 種子更新時忽略此欄位的比對 |
+
+---
+
+## 匯入/匯出 Attribute
+
+### [ImportDictAttribute] — 匯入時字典轉換
+```csharp
+[ImportDictAttribute("gender")]  // Excel 匯入時，將"男/女"轉換為對應的字典 Key
+public string Gender { get; set; }
+```
+
+### [IgnoreEnumToDictAttribute] — 跳過 Enum 字典轉換
+```csharp
+[IgnoreEnumToDictAttribute]
+public SomeEnum InternalStatus { get; set; }  // 不加入字典轉換
+```
+
+---
+
+## API/回應 Attribute
+
+### [CustomUnifyResultAttribute] — 自訂回應格式
+```csharp
+[CustomUnifyResultAttribute(typeof(MyResultProvider))]
+public class SpecialApiService : IDynamicApiController, ITransient
+{
+    // 此服務使用自訂回應格式（不使用預設的統一回應）
+}
+```
+
+### [CustomJsonPropertyAttribute] — 自訂 JSON 屬性名
+```csharp
+[CustomJsonPropertyAttribute("order_no")]
+public string OrderNo { get; set; }  // JSON 序列化為 "order_no"
+```
+
+---
+
+## 常數分組 Attribute
+
+### [ConstAttribute] — 常數分組
+```csharp
+[ConstAttribute("SMS供應商")]
+public class SmsProviderConst
+{
+    public const string Aliyun = "aliyun";
+    public const string Tencent = "tencent";
+}
+```
+
+### [EnumAttribute] — Enum 標記
+```csharp
+[EnumAttribute]
+public enum OrderStatusEnum
+{
+    [Description("待付款")] Pending = 0,
+    [Description("已付款")] Paid = 1,
+    [Description("已完成")] Completed = 2
+}
+```
+
+---
+
+## Attribute 目錄
+所有自訂 Attribute 位於：`Admin.NET.Core/Attribute/`
+
+常用 Attribute 快速查找：
+- 防重複提交 → IdempotentAttribute
+- 手機/身分證遮罩 → DataMaskAttribute
+- 欄位字典驗證 → DictAttribute
+- 路由至主DB → SysTableAttribute
+- 有種子資料 → SeedDataAttribute
+- 增量更新表結構 → IncreTableAttribute