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

package/knowledge/Furion_Teaching_Manual/10-1-SqlSugar/346/225/264/345/220/210.md

@@ -0,0 +1,336 @@
+# 10.1 SqlSugar 整合
+
+> **關於 SqlSugar**：如果選擇使用 SqlSugar 作為 ORM 資料庫操作，可直接安裝 `Furion.Pure` 和 `SqlSugarCore` 套件即可，之後根據 SqlSugar 官方文件教學使用。
+
+---
+
+## 10.1.1 SqlSugar ORM
+
+SqlSugar 是 .NET/C# 平台非常優秀的 ORM 框架，目前 NuGet 總下載突破 1000K，Github 關注量也高達 3.7K，是目前當之無愧的國產優秀 ORM 框架之一。SqlSugar 高效能，具有百萬級插入、更新大數據分表等特色功能。
+
+---
+
+## 10.1.2 功能介紹
+
+- 支援 SqlServer、MySql、PgSql、Oracle 百萬級插入和更新
+- 支援全自動分表
+- 支援多庫交易
+- 支援 CodeFirst
+- 支援聯表查詢、巢狀查詢、導航查詢、子查詢和動態 JSON 查詢等查詢操作
+- 支援設定查詢
+- 支援工具產生實體和程式碼產生實體
+- 支援資料庫 MySql、SqlServer、Sqlite、Oracle、PostgreSQL、達夢、人大金倉、神通資料庫
+
+---
+
+## 10.1.3 官網文件
+
+| 入門 | 查詢 | 插入 | 更新 | 刪除 |
+|------|------|------|------|------|
+| [安裝](https://www.donet5.com/Home/Doc) | [簡單查詢](https://www.donet5.com/Home/Doc) | 增 | 改 | 刪 |
+| [入門](https://www.donet5.com/Home/Doc) | [聯表](https://www.donet5.com/Home/Doc) | | | |
+
+---
+
+## 10.1.4 Furion 整合
+
+### 建立一個擴充類別
+
+```csharp
+public static class SqlsugarSetup
+{
+    public static void AddSqlsugarSetup(this IServiceCollection services, IConfiguration configuration, string dbName = "db_master")
+    {
+        var configConnection = new ConnectionConfig()
+        {
+            DbType = SqlSugar.DbType.MySql,
+            ConnectionString = configuration.GetConnectionString(dbName),
+            IsAutoCloseConnection = true,
+        };
+
+        SqlSugarScope sqlSugar = new SqlSugarScope(configConnection,
+        db =>
+        {
+            // 單例參數設定，所有上下文生效
+            db.Aop.OnLogExecuting = (sql, pars) =>
+            {
+                // Console.WriteLine(sql); // 輸出 SQL
+            };
+        });
+
+        services.AddSingleton<ISqlSugarClient>(sqlSugar); // SqlSugarScope 用 AddSingleton
+    }
+}
+```
+
+### 使用注入
+
+```csharp
+// 1. 建構函式注入
+SqlSugar.ISqlSugarClient db;
+public WeatherForecastController(ISqlSugarClient db)
+{
+    this.db = db;
+}
+
+// 2. 手動取得
+App.GetService<ISqlSugarClient>();
+```
+
+### 在 Startup.cs 中註冊
+
+```csharp
+services.AddSqlsugarSetup(App.Configuration);
+```
+
+> **小知識**：如果需要多庫設定，可查看 https://www.donet5.com/home/Doc?typeId=2246
+
+---
+
+## 10.1.5 特色功能
+
+### 10.1.5.1 聯表查詢
+
+```csharp
+var query5 = db.Queryable<Order>()
+    .LeftJoin<Custom>((o, cus) => o.CustomId == cus.Id)
+    .LeftJoin<OrderItem>((o, cus, oritem) => o.Id == oritem.OrderId)
+    .Where(o => o.Id == 1)
+    .Select((o, cus) => new ViewOrder { Id = o.Id, CustomName = cus.Name })
+    .ToList();
+```
+
+產生的 SQL：
+
+```sql
+SELECT [o].[Id] AS [Id], [cus].[Name] AS [CustomName]
+FROM [Order] o
+Left JOIN [Custom] cus ON ([o].[CustomId] = [cus].[Id])
+Left JOIN [OrderDetail] oritem ON ([o].[Id] = [oritem].[OrderId])
+WHERE ([o].[Id] = @Id0)
+```
+
+### 10.1.5.2 分頁查詢
+
+```csharp
+int pageIndex = 1;
+int pageSize = 20;
+int totalCount = 0;
+var page = db.Queryable<Student>().ToPageList(pageIndex, pageSize, ref totalCount);
+```
+
+### 10.1.5.3 動態運算式
+
+```csharp
+var names = new string[] { "a", "b" };
+Expressionable<Order> exp = new Expressionable<Order>();
+
+foreach (var item in names)
+{
+    exp.Or(it => it.Name.Contains(item.ToString()));
+}
+
+var list = db.Queryable<Order>().Where(exp.ToExpression()).ToList();
+```
+
+產生的 SQL：
+
+```sql
+SELECT [Id],[Name],[Price],[CreateTime],[CustomId]
+FROM [Order]
+WHERE (
+  ([Name] like '%'+ CAST(@MethodConst0 AS NVARCHAR(MAX))+'%') OR
+  ([Name] like '%'+ CAST(@MethodConst1 AS NVARCHAR(MAX))+'%')
+)
+```
+
+### 10.1.5.4 倉儲方法
+
+新建一個倉儲類別，如果想擴充方法寫到倉儲類別中：
+
+```csharp
+public class Repository<T> : SimpleClient<T> where T : class, new()
+{
+    public Repository(ISqlSugarClient context = null) : base(context)
+    {
+        base.Context = App.GetService<ISqlSugarClient>(); // 用手動取得方式支援切換倉儲
+    }
+}
+```
+
+繼承倉儲類別就可以使用倉儲 API 了：
+
+```csharp
+// 查詢
+var data1 = base.GetById(1);                          // 根據 id 查詢
+var data4 = base.GetSingle(it => it.Id == 1);         // 查詢單條記錄
+var data = base.GetFirst(it => it.Id == 1);            // 查詢第一條記錄
+var data2 = base.GetList();                            // 查詢所有
+var data3 = base.GetList(it => it.Id == 1);            // 根據條件查詢
+
+var p = new PageModel() { PageIndex = 1, PageSize = 2 };
+var data5 = base.GetPageList(it => it.Name == "xx", p);
+var data6 = base.GetPageList(it => it.Name == "xx", p, it => it.Name, OrderByType.Asc);
+
+List<IConditionalModel> conModels = new List<IConditionalModel>();
+conModels.Add(new ConditionalModel() { FieldName = "id", ConditionalType = ConditionalType.Equal, FieldValue = "1" });
+var data7 = base.GetPageList(conModels, p, it => it.Name, OrderByType.Asc);
+
+base.AsQueryable().Where(x => x.Id == 1).ToList();
+
+// 插入
+base.Insert(insertObj);
+base.InsertRange(InsertObjs);
+var id = base.InsertReturnIdentity(insertObj);
+base.AsInsertable(insertObj).ExecuteCommand();
+
+// 刪除
+base.Delete(insertObj);
+base.DeleteById(1);
+base.DeleteByIds(new object[] { 1, 2 });
+base.Delete(it => it.Id == 1);
+base.AsDeleteable().Where(it => it.Id == 1).ExecuteCommand();
+
+// 更新
+base.Update(insertObj);
+base.UpdateRange(InsertObjs);
+base.Update(it => new Order() { Name = "a" }, it => it.Id == 1);
+base.AsUpdateable(insertObj).UpdateColumns(it => new { it.Name }).ExecuteCommand();
+
+// 進階操作
+base.AsSugarClient   // 取得完整的 db 物件
+base.AsTenant        // 取得多庫相關操作
+
+// 切換倉儲
+base.ChangeRepository<Repository<OrderItem>>()  // 支援多租戶和擴充方法
+base.Change<OrderItem>()                         // 只支援自帶方法和單庫
+```
+
+### 10.1.5.5 多庫交易
+
+```csharp
+SqlSugarClient db = new SqlSugarClient(new List<ConnectionConfig>()
+{
+    new ConnectionConfig() { ConfigId = "0", DbType = DbType.SqlServer, ConnectionString = Config.ConnectionString, IsAutoCloseConnection = true },
+    new ConnectionConfig() { ConfigId = "1", DbType = DbType.MySql, ConnectionString = Config.ConnectionString4, IsAutoCloseConnection = true }
+});
+
+var mysqldb = db.GetConnection("1");     // MySQL db
+var sqlServerdb = db.GetConnection("0"); // SQL Server db
+
+db.BeginTran();
+
+mysqldb.Insertable(new Order()
+{
+    CreateTime = DateTime.Now,
+    CustomId = 1,
+    Name = "a",
+    Price = 1
+}).ExecuteCommand();
+
+mysqldb.Queryable<Order>().ToList();
+sqlServerdb.Queryable<Order>().ToList();
+
+db.CommitTran();
+```
+
+### 10.1.5.6 單例模式
+
+```csharp
+public static SqlSugarScope Db = new SqlSugarScope(new ConnectionConfig()
+{
+    DbType = SqlSugar.DbType.SqlServer,
+    ConnectionString = Config.ConnectionString,
+    IsAutoCloseConnection = true
+},
+db =>
+{
+    db.Aop.OnLogExecuting = (s, p) =>
+    {
+        Console.WriteLine(s);
+    };
+});
+
+using (var tran = Db.UseTran())
+{
+    new Test2().Insert(XX);
+    new Test1().Insert(XX);
+
+    tran.CommitTran();
+}
+```
+
+### 10.1.5.7 全域過濾器
+
+```csharp
+db.QueryFilter.Add(new TableFilterItem<Order>(it => it.Name.Contains("a")));
+
+db.Queryable<Order>().ToList();
+// SELECT [Id],[Name],[Price],[CreateTime],[CustomId] FROM [Order]
+// WHERE ([Name] like '%'+@MethodConst0+'%')
+
+db.Queryable<OrderItem, Order>((i, o) => i.OrderId == o.Id)
+    .Where(i => i.OrderId != 0)
+    .Select("i.*").ToList();
+// SELECT i.* FROM [OrderDetail] i, [Order] o
+// WHERE ([i].[OrderId] = [o].[Id]) AND ([i].[OrderId] <> @OrderId0)
+// AND ([o].[Name] like '%'+@MethodConst1+'%')
+```
+
+### 10.1.5.8 新增或更新
+
+```csharp
+var x = Db.Storageable(list2).ToStorage();
+x.AsInsertable.ExecuteCommand();
+x.AsUpdateable.ExecuteCommand();
+
+var x = Db.Storageable(list).SplitInsert(it => !it.Any()).ToStorage();
+x.AsInsertable.ExecuteCommand();
+```
+
+### 10.1.5.9 自動分表
+
+```csharp
+[SplitTable(SplitType.Year)]
+[SugarTable("SplitTestTable_{year}{month}{day}")]
+public class SplitTestTable
+{
+    [SugarColumn(IsPrimaryKey = true)]
+    public long Id { get; set; }
+
+    public string Name { get; set; }
+
+    [SplitField]
+    public DateTime CreateTime { get; set; }
+}
+
+var list = db.Queryable<OrderSpliteTest>()
+    .SplitTable(DateTime.Now.Date.AddYears(-1), DateTime.Now)
+    .ToPageList(1, 2);
+```
+
+### 10.1.5.10 大數據插入、更新、插入或更新
+
+```csharp
+// 插入百萬筆只需幾秒
+db.Fastest<RealmAuctionDatum>().BulkCopy(GetList());
+
+// 更新百萬筆只需幾秒
+db.Fastest<RealmAuctionDatum>().BulkUpdate(GetList());
+db.Fastest<RealmAuctionDatum>().BulkUpdate(GetList(), new string[] { "id" }, new string[] { "name", "time" }); // 無主鍵
+
+// 存在則更新，不存在則插入
+var x = db.Storageable<Order>(data).ToStorage();
+x.BulkCopy();
+x.BulkUpdate();
+
+// 設定表名
+db.Fastest<RealmAuctionDatum>().AS("tableName").BulkCopy(GetList());
+
+// 設定分頁
+db.Fastest<Order>().PageSize(300000).BulkCopy(insertObjs);
+```
+
+### 10.1.5.11 更多功能
+
+可查閱 [SqlSugar 官網](https://www.donet5.com/Home/Doc)。

package/knowledge/Furion_Teaching_Manual/11-SaaS /345/244/232/347/247/237/346/210/266/347/255/206/350/250/230.md"

@@ -0,0 +1,271 @@
+# Furion SaaS 多租戶筆記
+
+---
+
+## 1. 概念說明
+
+### SaaS
+透過 Internet 提供軟體服務的模式，廠商統一部署應用，客戶按需租用，無需自行維護基礎設施。
+
+### 多租戶
+單一應用實例服務多個租戶（客戶），**重點在於同一套程式下實現多用戶資料隔離**。
+
+---
+
+## 2. 三種隔離方案比較
+
+| 方案 | 說明 | 隔離級別 | 成本 | 適用場景 |
+|------|------|----------|------|----------|
+| **Database** | 一租戶一資料庫 | 最高 | 高 | 銀行、醫院等高安全需求 |
+| **Schema** | 共享 DB，每租戶獨立 Schema | 中 | 中 | 中小型企業 |
+| **TenantId** | 共享 DB + Schema，以欄位區分 | 最低 | 最低 | 中小型企業（最常用） |
+
+> ⚠️ 一旦 DbContext 繼承租戶任意介面，即自動啟用多租戶功能。
+
+---
+
+## 3. 方案一：基於 TenantId（最常用）
+
+### 步驟概覽
+1. 建立租戶 DbContext
+2. 注冊租戶 DbContext
+3. 新增 Tenant 種子資料（Code First 才需要）
+4. 執行 Migration 建立 Tenant 表
+5. 實作 `IMultiTenantOnTable`
+6. 實作 `IModelBuilderFilter`（查詢過濾）
+7. 覆寫 `SavingChangesEvent`（新增/更新處理）
+
+### 3.1 建立租戶 DbContext
+
+```csharp
+[AppDbContext("Sqlite3ConnectionString", DbProvider.Sqlite)]
+public class MultiTenantDbContext : AppDbContext<MultiTenantDbContext, MultiTenantDbContextLocator>
+{
+    public MultiTenantDbContext(DbContextOptions<MultiTenantDbContext> options) : base(options) { }
+}
+```
+
+> ⚠️ 多租戶 DbContext 必須指定 `MultiTenantDbContextLocator`。
+
+### 3.2 注冊服務
+
+```csharp
+services.AddDatabaseAccessor(options =>
+{
+    options.AddDbPool<FurionDbContext>();
+    options.AddDbPool<MultiTenantDbContext, MultiTenantDbContextLocator>();
+});
+```
+
+### 3.3 種子資料（Code First）
+
+```csharp
+public class TenantSeedData : IEntitySeedData<Tenant, MultiTenantDbContextLocator>
+{
+    public IEnumerable<Tenant> HasData(DbContext dbContext, Type dbContextLocator)
+    {
+        return new List<Tenant>
+        {
+            new Tenant
+            {
+                TenantId = Guid.Parse("383AFB88-F519-FFF8-B364-6D563BF3687F"),
+                Name = "預設租戶",
+                Host = "localhost:44313",
+                CreatedTime = DateTime.Parse("2020-10-06 20:19:07")
+            }
+        };
+    }
+}
+```
+
+### 3.4 Migration
+
+```bash
+Add-Migration add_tenant_table -Context MultiTenantDbContext
+Update-Database -Context MultiTenantDbContext
+```
+
+### 3.5 實作 `IMultiTenantOnTable` + `IModelBuilderFilter`
+
+```csharp
+[AppDbContext("Sqlite3ConnectionString", DbProvider.Sqlite)]
+public class FurionDbContext : AppDbContext<FurionDbContext>, IMultiTenantOnTable, IModelBuilderFilter
+{
+    public FurionDbContext(DbContextOptions<FurionDbContext> options) : base(options) { }
+
+    // 取得目前租戶 TenantId
+    public object GetTenantId()
+    {
+        return base.Tenant?.TenantId ?? Guid.Empty;
+        // 自訂邏輯：直接 return 你的 TenantId;
+    }
+
+    // 設定全域查詢過濾
+    public void OnCreating(ModelBuilder modelBuilder, EntityTypeBuilder entityBuilder,
+        DbContext dbContext, Type dbContextLocator)
+    {
+        entityBuilder.HasQueryFilter(BuildTenantQueryFilter(entityBuilder, dbContext));
+    }
+}
+```
+
+### 3.6 覆寫 `SavingChangesEvent`（新增自動帶入、更新排除 TenantId）
+
+```csharp
+protected override void SavingChangesEvent(DbContextEventData eventData, InterceptionResult<int> result)
+{
+    var dbContext = eventData.Context;
+    var entities = dbContext.ChangeTracker.Entries()
+        .Where(u => u.State == EntityState.Added
+                 || u.State == EntityState.Modified
+                 || u.State == EntityState.Deleted);
+
+    foreach (var entity in entities)
+    {
+        switch (entity.State)
+        {
+            case EntityState.Added:
+                // 新增時自動設定 TenantId
+                entity.Property(nameof(Entity.TenantId)).CurrentValue = GetTenantId();
+                break;
+            case EntityState.Modified:
+                // 更新時排除 TenantId 被修改
+                entity.Property(nameof(Entity.TenantId)).IsModified = false;
+                break;
+        }
+    }
+}
+```
+
+---
+
+## 4. 方案二：基於 Database（獨立資料庫）
+
+### 步驟概覽
+1~4 同 TenantId 方案，但種子資料需多設 `ConnectionString`
+5. 實作 `IMultiTenantOnDatabase`
+6. 覆寫 `OnConfiguring` 套用連線字串
+
+### 4.1 種子資料差異（需含 ConnectionString）
+
+```csharp
+new Tenant
+{
+    TenantId = Guid.Parse("..."),
+    Name = "預設租戶",
+    Host = "localhost:44313",
+    ConnectionString = "Data Source=./Furion.db"  // 重點
+}
+```
+
+### 4.2 實作 `IMultiTenantOnDatabase` + 覆寫 `OnConfiguring`
+
+```csharp
+public class FurionDbContext : AppDbContext<FurionDbContext>, IMultiTenantOnDatabase
+{
+    public FurionDbContext(DbContextOptions<FurionDbContext> options) : base(options) { }
+
+    public string GetDatabaseConnectionString()
+    {
+        return base.Tenant?.ConnectionString ?? "預設連線字串";
+        // 自訂邏輯：直接 return 你的連線字串;
+    }
+
+    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
+    {
+        optionsBuilder.UseSqlite(GetDatabaseConnectionString());
+        base.OnConfiguring(optionsBuilder);
+    }
+}
+```
+
+> ⚠️ Code First 時需手動指定 Migration 程式集名稱：
+> ```csharp
+> optionsBuilder.UseSqlite(GetDatabaseConnectionString(), options =>
+> {
+>     options.MigrationsAssembly("My.Migrations");
+> });
+> ```
+
+---
+
+## 5. 方案三：基於 Schema
+
+### 步驟概覽
+1~4 同前，種子資料需多設 `Schema`
+5. 實作 `IMultiTenantOnSchema`
+
+### 5.1 種子資料差異（需含 Schema）
+
+```csharp
+new Tenant { ..., Schema = "dbo" }
+new Tenant { ..., Schema = "furion" }
+```
+
+### 5.2 實作 `IMultiTenantOnSchema`
+
+```csharp
+[AppDbContext("Sqlite3ConnectionString", DbProvider.Sqlite)]
+public class FurionDbContext : AppDbContext<FurionDbContext>, IMultiTenantOnSchema
+{
+    public FurionDbContext(DbContextOptions<FurionDbContext> options) : base(options) { }
+
+    public string GetSchemaName()
+    {
+        return base.Tenant?.Schema ?? "dbo";
+        // 自訂邏輯：直接 return 你的 Schema;
+    }
+}
+```
+
+> 💡 Code First Migration 時需分批執行，每次切換預設 Schema 後再跑一次 Migration。
+
+---
+
+## 6. 自訂 Tenant 類型
+
+```csharp
+// 啟用自訂
+services.AddDatabaseAccessor(options =>
+{
+    options.CustomizeMultiTenants(); // 可傳入自訂 TenantId 欄位名
+    options.AddDbPool<FurionDbContext>();
+});
+
+// 自訂租戶類
+public class MyTenant : IEntity<MultiTenantDbContextLocator>
+{
+    [Key]
+    public Guid TenantId { get; set; }
+    public string Name { get; set; }
+    public string Host { get; set; }
+}
+
+// 查詢自訂租戶
+var tenantDbContext = Db.GetDbContext<MultiTenantDbContextLocator>();
+var myTenant = tenantDbContext.Set<MyTenant>();
+```
+
+---
+
+## 7. 刷新租戶快取
+
+Furion 首次查詢時會將租戶資料快取，**更新租戶資料後需手動刷新**：
+
+```csharp
+using Furion.DatabaseAccessor.Extensions;
+
+// 在更新租戶資訊後呼叫刷新方法
+```
+
+---
+
+## 快速選型
+
+```
+需要最高資料隔離？
+  ├─ 是 → Database 方案（獨立 DB）
+  └─ 否 → 成本優先？
+            ├─ 是 → TenantId 方案（最省、最常用）
+            └─ 否 → Schema 方案（邏輯隔離）
+```