CoreMiddleware.Analyzers 1.3.0

Core Middleware 核心中介框架 (Core Middleware Framework)

提供 B2B SaaS 平台一致、安全且高度擴展的底層架構 SDK。 以 NuGet 套件形式發佈，由各業務服務（WebApi / Worker）引用。

🚀 專案導覽

本專案採用 Clean Architecture 與 Domain-Driven Design (DDD) 模式，分層發佈為四個 NuGet 套件，業務服務只需 dotnet add package 即可取得整套中介能力。

目錄結構

.
├── CoreMiddleware.Core/           # 領域層（Entities, Interfaces, Options）          → NuGet
├── CoreMiddleware.Application/    # 應用層（Services 契約, DTOs）                    → NuGet
├── CoreMiddleware.Infrastructure/ # 基礎設施層（EF Core / PostgreSQL, Redis, Cognito）→ NuGet
├── CoreMiddleware.Analyzers/      # Roslyn 編譯期分析器（架構守門）                   → NuGet
├── CoreMiddleware.Tests/          # 自動化測試（xUnit）
├── docs/                          # 本地技術文檔（架構、遷移、setup、範例）
├── nupkgs/                        # 本地 pack 輸出
├── .husky/                        # Git Hooks 品質管理配置
├── Directory.Build.props          # 共用 NuGet metadata（Version / Authors）
├── publish-nuget.ps1              # NuGet 發佈腳本
└── USER_MANUAL.md                 # 消費端完整使用手冊（推薦先看這份）

本專案沒有 WebApi 專案。框架由 NuGet 套件形式提供，由下游服務（人資、財務等模組）的 WebApi 引用。

🏗️ 技術架構

本框架收斂以下企業級關鍵能力：

1. 全域冪等性 (Idempotency) — Redis 鎖 + 響應快取，確保 API 不因重試而重複執行。
2. 交易訊息保證 (Transactional Outbox) — 解決分散式環境下的最終一致性。
3. 動態個資遮蔽 (PII Masking) — 符合 GDPR 的自動化欄位遮蔽。
4. 多租戶分流 (Multi-Tenancy) — Zero-Trust 租戶解析 + 動態資料庫路由。
5. 韌性通訊 (Resilience) — 內建 Polly 重試與熔斷。
6. 多語系 (i18n) — 6 來源 chain（QueryString → Cookie → JWT → Profile → Accept-Language → Default）。
7. 分散式限流 (Rate Limiting) — Redis Lua ZSET sliding window + FailOpen 降級。
8. AWS Cognito 整合 — 非同步 federation + zero-trust tenant lookup。

🛠️ 快速開始 (Quick Start)

1. 環境需求

• .NET 10 SDK
• PostgreSQL 15+（已自 MySQL 遷移，詳見 docs/migrations/2026-04-mysql-to-postgresql.md）
• Redis 7.0+（冪等性、限流、快取）
• AWS Cognito（驗證與多租戶 federation；本地測試可用 stub）

2. 初始化開發環境

# 1. 還原套件
dotnet restore

# 2. 安裝 Git Hooks（Husky.NET）
dotnet tool restore
dotnet husky install

# 3. （選用）建立測試環境
powershell ./docs/scripts/setup-tests.ps1

3. 建置與測試

dotnet build CoreMiddleware.sln -c Release
dotnet test  CoreMiddleware.sln -c Release

4. 發佈 NuGet 套件

# 只打包不推送（產出在 ./nupkgs/）
./publish-nuget.ps1 -Version 1.1.3 -PackOnly

# 推送到預設 feed（nuget.org）
./publish-nuget.ps1 -Version 1.1.3 -ApiKey <YOUR_KEY>

# 推送到內部 NuGet Server（自訂 -Source）
./publish-nuget.ps1 -Version 1.1.3 -ApiKey <YOUR_KEY> -Source <INTERNAL_FEED_URL>

詳細的消費端整合步驟請見 USER_MANUAL.md。

📚 技術文檔

本地文件（隨 repo，連結指向內部 GitLab develop 分支）

• 🎯 USER_MANUAL.md — 消費端完整使用手冊（新人從這裡開始）
• 🏗️ docs/architecture/ARCHITECTURE.md — 架構總覽
• 🔍 docs/architecture/ARCHITECTURE_AUDIT.md — 架構稽核
• 👨‍💻 docs/DEVELOPER_GUIDE.md — 開發者指南
• 📦 docs/examples/FULL_EXAMPLE.md — 從 Entity → Controller 完整範例
• 🔧 docs/setup/SETUP.md / docs/setup/GIT_HOOKS.md — 環境與 Git Hooks
• 🔄 docs/migrations/ — 重大遷移紀錄（MySQL → PostgreSQL 等）

架構規格文件（外部 TaleningDocument repo）

位於 D:\saas\TaleningDocument\docs\01_Core_Services\12_Core_Middleware\：

• 01_core_middleware_prd.md — 產品需求
• 02_core_middleware_sa_schema.md — 系統分析（資料 Schema）
• 03_core_middleware_sd_logic.md — 系統設計（邏輯）
• 04_core_middleware_sd_impl.md — 系統設計（實作）
• 04_core_middleware_test_cases.md — 測試案例

AI 協作配置

• CLAUDE.md — Claude Code 專案層指引
• AGENTS.md — 指向 CLAUDE.md 的指標（single source of truth 為 CLAUDE.md）

📦 NuGet 套件清單

當前版本：見 Directory.Build.props 的 <Version>。

最後更新時間：2026-05-20（連結改用絕對 URL，確保 NuGet feed 上可點擊）