技術棧建議 Kiro 建議
基於需求規格分析後提出的技術選型建議，供設計文件參考。最終技術決策由團隊確認。
選型考量因素
- 架構需求：11 個獨立模組，各自獨立部署為 Container（微服務架構）
- 目標平台：Azure Container Apps（ACA）或 Azure Kubernetes Service（AKS）
- 國際化：繁體中文為主、英文為輔
- 團隊規模：小型團隊，需最大化開發效率
- 迭代節奏：Prototype → Staging → Production 快速迭代
- 整合需求：Microsoft Entra ID（SSO）、Microsoft Graph API（M365 行事曆）、WordPress REST API
推薦技術棧總覽
| 層級 | 技術選型 |
|---|---|
| 後端框架 | NestJS (TypeScript) |
| ORM / Migration | Prisma (multi-schema, 各模組獨立 migration) |
| 資料庫 | PostgreSQL 17 |
| 快取 / 佇列 | Redis 7 + BullMQ |
| 前端 (Admin UI) | React + Vite + shadcn/ui + Tailwind CSS |
| 前端 (Portal) | React + Vite（Prototype 階段） |
| 共用型別層 | TypeScript 型別定義 (native/shared/) |
| 容器化 | Docker multi-stage build (Alpine-based) |
| 容器編排 | Docker Compose (proto) → Azure Container Apps (production) |
| CI/CD | GitHub Actions |
| 認證 (SSO) | MSAL.js + @azure/identity + passport-azure-ad |
| M365 整合 | @microsoft/microsoft-graph-client |
| PDF 產生 | Puppeteer 或 @react-pdf/renderer（證書、發票、報表） |
| 國際化 | react-i18next (前端) + nestjs-i18n (後端) |
| API 文件 | Swagger / OpenAPI 3.0（NestJS 內建支援） |
後端：Node.js + TypeScript（NestJS 框架）
選擇理由
| 優勢 | 說明 |
|---|---|
| 前後端共用型別 | shared/ 目錄可放 DTO、enum、常數，前後端零成本共享，減少 API 合約不一致風險 |
| 模組系統對應 | NestJS 的 Module 系統天然對應 11 個業務模組，每個模組可獨立打包為 Container |
| ORM 型別安全 | Prisma ORM 提供型別安全的 DB 存取 + 獨立 migration per schema |
| Azure SDK 完整 | @azure/identity（Entra ID）、@microsoft/microsoft-graph-client（M365）支援完整 |
| 台灣人才市場 | TypeScript / Node.js 人才充足，降低未來維護風險 |
| Container 精簡 | Docker multi-stage build 可產出 ~100MB 的 Alpine-based image |
未選方案比較
| 語言 | 未選原因 |
|---|---|
| Go | Container image 最小（~20MB）、效能最好，但 11 個模組的 CRUD + 複雜業務邏輯會產生大量 boilerplate，小團隊開發速度受影響 |
| Python (FastAPI) | 開發速度快，但動態語言在大型專案的長期維護成本較高，型別安全不如 TypeScript |
| C# (.NET 8) | Azure 原生整合最好，但台灣 .NET 人才偏向企業內部系統，image 較大（~200MB），對小型訓練中心維運成本較高 |
前端（Admin UI）：React + TypeScript + Vite
| 優勢 | 說明 |
|---|---|
| 元件生態最豐富 | shadcn/ui + Radix UI 可快速建構符合 Cisco Momentum 風格的高資料密度介面 |
| 資料表格 | TanStack Table 處理大量資料（報名名單、稽核紀錄、報表） |
| 行事曆排程 | FullCalendar 完整支援月/週/日視圖、拖曳排程 |
| Tailwind CSS | 快速客製品牌色彩系統（Design Token），支援 Dark Mode |
| 建置速度 | Vite 開發伺服器啟動 < 1 秒，HMR 即時反映 |
| 不需 SSR | Admin UI 為純 SPA，不需 Next.js 的 SSR 開銷 |
前端（學員入口 Portal）：Prototype 階段先以 SPA 實作。若未來需要 SEO（公開課程頁面），可獨立升級為 Next.js，不影響 Admin UI。
資料庫：PostgreSQL 17 + Redis 7
| 元件 | 用途 |
|---|---|
| PostgreSQL 17 | 主要資料儲存，搭配 Prisma multi-schema 支援各模組獨立 schema |
| Redis 7 | Session 快取、候補名額分散式鎖（Optimistic Locking 輔助）、背景任務佇列（BullMQ） |
部署架構對應
native/
├── proto/ → Docker Compose（本地開發 / Prototype）
├── stage/ → Azure Container Apps（Staging）
├── production/ → Azure Container Apps（Production）
├── api/ → NestJS monorepo，各模組為獨立 NestJS Module
│ ├── src/
│ │ ├── modules/
│ │ │ ├── course/ → 模組 A
│ │ │ ├── registration/ → 模組 B
│ │ │ ├── finance/ → 模組 C
│ │ │ ├── crm/ → 模組 D
│ │ │ ├── academic/ → 模組 E
│ │ │ ├── notification/ → 模組 F
│ │ │ ├── resource/ → 模組 G
│ │ │ ├── sales/ → 模組 H
│ │ │ ├── portal/ → 模組 I
│ │ │ ├── admin/ → 模組 J
│ │ │ └── integration/ → 模組 K
│ │ └── common/ → 共用 middleware（RBAC、Audit、CustomField、Tag）
│ └── prisma/
│ ├── schema-course.prisma
│ ├── schema-registration.prisma
│ └── ... → 各模組獨立 schema
├── web/ → React Admin UI (Vite)
├── portal/ → React Learner Portal (Vite)
├── shared/ → 共用 TypeScript 型別、常數、工具函式
└── docs/ → 開發文件、API 文件
與需求的對應關係
| 需求 | 技術棧如何滿足 |
|---|---|
| 需求 22（Container 部署） | NestJS + Docker multi-stage build，每模組獨立 image |
| 需求 23（模組獨立部署） | NestJS Module 系統 + Prisma multi-schema + 版本化 API |
| 需求 21（Entra ID SSO） | MSAL.js + passport-azure-ad + @azure/identity |
| 需求 19（M365 行事曆） | @microsoft/microsoft-graph-client |
| 需求 24（UI/UX 品牌） | shadcn/ui + Tailwind CSS Design Token |
| 需求 13（行事曆排程） | FullCalendar React 元件 |
| 需求 25（全域搜尋） | PostgreSQL Full-Text Search + Redis 快取 |
| 需求 32（動態欄位） | Prisma JSON 欄位 + 動態 schema 驗證 |
| 需求 34（UUID v7 Master Key） | uuid v7 npm package，PostgreSQL UUID 欄位 |