Initial commit: monorepo scaffold for ROLAC

- Add .gitignore covering C#/.NET and Angular/Node - Add placeholder structure for API (C#) and APP (Angular) - Add project docs Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-24 20:54:10 -07:00
commit 9b28fbcfb6
11 changed files with 4215 additions and 0 deletions
@@ -0,0 +1,464 @@
+# ROLAC — UI 架構設計
+
+**文件版本:** v0.1 (2026-05-24)
+
+---
+
+## 目錄
+
+1. [前端整體架構](#1-前端整體架構)
+2. [Angular 專案結構](#2-angular-專案結構)
+3. [Landing Page — 公開網站設計](#3-landing-page--公開網站設計)
+4. [Admin / User Portal — 後台設計](#4-admin--user-portal--後台設計)
+5. [Kendo UI 元件對應清單](#5-kendo-ui-元件對應清單)
+6. [Angular Material 使用範圍](#6-angular-material-使用範圍)
+7. [設計系統 (Design Tokens)](#7-設計系統-design-tokens)
+8. [Responsive / Mobile 規範](#8-responsive--mobile-規範)
+9. [Kendo UI 授權注意事項](#9-kendo-ui-授權注意事項)
+
+---
+
+## 1. 前端整體架構
+
+```
+單一 Angular 專案 (Monorepo — Angular Workspace)
+│
+├── 公開路由 /  →  Landing Page
+│   src/app/public/
+│   技術: Tailwind CSS + 自訂元件 + Angular Animations
+│   對象: 訪客、潛在新教友
+│
+├── 教友入口 /portal/  →  User Portal
+│   src/app/portal/
+│   技術: Angular Material + Kendo UI
+│   對象: 一般教友（查看服事、奉獻歷史、個人資料）
+│
+└── 後台管理 /admin/  →  Admin Dashboard
+    src/app/admin/
+    技術: Angular Material + Kendo UI
+    對象: 管理員、牧師、財務、秘書等
+
+↓ Capacitor 打包
+iOS App  /  Android App
+└── 打包 /portal/ 為主入口（App 不含 Landing Page）
+```
+
+**為什麼用單一 Angular 專案？**
+- Capacitor 只能打包一個 Web App
+- 共用 Auth service、API service、ngx-translate
+- 共用 Design Token（顏色、字型）保持品牌一致性
+- 一個 Jenkins pipeline 搞定所有 build
+
+---
+
+## 2. Angular 專案結構
+
+```
+src/
+├── app/
+│   ├── core/                    ← 全域服務 (Auth, API, i18n, Error)
+│   │   ├── services/
+│   │   ├── guards/
+│   │   ├── interceptors/
+│   │   └── models/
+│   │
+│   ├── shared/                  ← 跨模組共用元件
+│   │   ├── components/          (語言切換器、頁頭、頁腳、Loading)
+│   │   └── pipes/               (雙語 pipe: {{ item | localizedName }})
+│   │
+│   ├── public/                  ← Landing Page（Tailwind）
+│   │   ├── home/
+│   │   ├── about/
+│   │   ├── events/
+│   │   ├── media/
+│   │   ├── giving/
+│   │   └── contact/
+│   │
+│   ├── portal/                  ← 教友 User Portal（Material + Kendo）
+│   │   ├── dashboard/
+│   │   ├── my-roster/
+│   │   ├── my-giving/
+│   │   └── my-profile/
+│   │
+│   └── admin/                   ← 後台管理（Material + Kendo）
+│       ├── dashboard/
+│       ├── members/
+│       ├── attendance/
+│       ├── groups/
+│       ├── roster/
+│       ├── giving/
+│       ├── cms/
+│       ├── reports/
+│       ├── audit-log/
+│       └── settings/
+│
+├── assets/
+│   ├── i18n/
+│   │   ├── en.json
+│   │   └── zh-TW.json
+│   └── images/
+│
+└── styles/
+    ├── _tokens.scss             ← Design Tokens（色彩、字型、間距）
+    ├── _material-theme.scss     ← Angular Material 主題
+    ├── _kendo-theme.scss        ← Kendo UI 主題覆寫
+    └── tailwind.css             ← Tailwind（public/ 使用）
+```
+
+---
+
+## 3. Landing Page — 公開網站設計
+
+### 設計方向
+
+**目標：** 有設計感、溫暖、現代，反映教會的歡迎文化  
+**技術：** Tailwind CSS + 自訂 Angular 元件 + Angular Animations  
+**不使用** Angular Material 或 Kendo UI（避免 Material Design 的企業感）
+
+### 視覺風格建議
+
+| 元素 | 建議 |
+|------|------|
+| 色調 | 以教會品牌色為主（深藍/金或暖色系），建議 2 主色 + 1 強調色 |
+| 字型 | Google Fonts：標題用 serif（如 Playfair Display），內文用 sans-serif（Inter） |
+| 圖像 | 真實教會照片優先；輔以 abstract/light 背景插圖 |
+| 動畫 | 入場淡入（Angular Animations）、滾動觸發（Intersection Observer）|
+| 圖示 | Heroicons 或 Phosphor Icons（免費，SVG） |
+
+### 各區塊設計
+
+```
+rolac.org
+│
+├── [Navbar]
+│   Logo | 導覽連結 | EN/中 切換 | [Visit Us] CTA 按鈕
+│
+├── [Hero Section]
+│   全版背景圖（教會聚會照片）
+│   主標題 + 副標題（雙語動態切換）
+│   兩個 CTA：[Join Us] [Watch Online]
+│   滾動指示箭頭
+│
+├── [Welcome / About Section]
+│   左側：短文介紹教會異象
+│   右側：牧師照片 + 名字
+│   底部：[Learn More] 連結
+│
+├── [Service Times]
+│   卡片式：主日崇拜時間 / 地點 / 停車資訊
+│   嵌入 Google Maps
+│
+├── [Announcements / Events]
+│   最新 3 則公告卡片（從 CMS 動態取得）
+│   [View All] 連結
+│
+├── [Media — Latest Sermon]
+│   YouTube Embed 最新一篇講道
+│   標題 + 日期 + 講員
+│   [Sermon Archive] 連結
+│
+├── [Giving Section]
+│   感召文字 + 奉獻方式說明（現金/支票/Zelle/PayPal）
+│   簡潔卡片排版，非強迫式
+│
+├── [Connect / Cell Groups]
+│   鼓勵加入小組的呼召
+│   [Contact Us] 或 [填寫訪客卡] 按鈕
+│
+├── [Contact Section]
+│   地址、電話、Email
+│   聯絡表單
+│
+└── [Footer]
+    Logo | 快速連結 | 社群媒體 | © | 隱私政策
+```
+
+### Tailwind 使用策略
+
+```html
+<!-- 範例：Hero Section -->
+<section class="relative h-screen flex items-center justify-center overflow-hidden">
+  <div class="absolute inset-0 bg-cover bg-center"
+       [style.backgroundImage]="'url(' + heroImage + ')'">
+    <div class="absolute inset-0 bg-black/50"></div>
+  </div>
+  <div class="relative z-10 text-center text-white px-4 max-w-4xl mx-auto">
+    <h1 class="text-5xl md:text-7xl font-serif mb-6 animate-fade-in">
+      {{ 'home.hero.title' | translate }}
+    </h1>
+    <p class="text-xl md:text-2xl mb-10 text-white/90">
+      {{ 'home.hero.subtitle' | translate }}
+    </p>
+    <div class="flex gap-4 justify-center flex-wrap">
+      <a routerLink="/about"
+         class="btn-primary px-8 py-4 rounded-full text-lg font-semibold">
+        {{ 'home.hero.joinUs' | translate }}
+      </a>
+    </div>
+  </div>
+</section>
+```
+
+### Landing Page 在 Mobile App 中的處理
+
+> Landing Page 僅存在於 **rolac.org 網站**，**不** 納入 Capacitor App  
+> App 啟動後直接跳到 Login 畫面或 Portal Dashboard
+
+---
+
+## 4. Admin / User Portal — 後台設計
+
+### 整體 Layout
+
+```
+┌──────────────────────────────────────────────────┐
+│ [ROLAC Logo]  [模組標題]    [EN|中]  [通知] [頭像] │  ← Top Toolbar (Angular Material MatToolbar)
+├──────────┬───────────────────────────────────────┤
+│          │                                       │
+│  [側邊   │         Main Content Area             │
+│   導覽]  │                                       │
+│          │   (Kendo Grid / Form / Chart 等)      │
+│  Desktop │                                       │
+│  only    │                                       │
+│          │                                       │
+└──────────┴───────────────────────────────────────┘
+           ┌──────────────────────────────────────┐
+           │ [首頁] [服事] [教友] [奉獻] [我的]   │  ← Bottom Tab Bar (Mobile only)
+           └──────────────────────────────────────┘
+```
+
+**導覽策略**
+- **Desktop (≥ 1024px):** 左側 Side Nav（Angular Material `MatSidenav`），可折疊
+- **Mobile (< 1024px):** 底部 Tab Bar（最多 5 個主要分頁），Side Nav 改為漢堡選單
+
+### 色彩主題（Admin / Portal）
+
+使用 Angular Material Custom Theme，與 Tailwind Landing Page 共用 Design Token：
+
+```scss
+// _material-theme.scss
+@use '@angular/material' as mat;
+
+$rolac-primary: mat.define-palette(mat.$indigo-palette, 700);
+$rolac-accent:  mat.define-palette(mat.$amber-palette, 600);
+$rolac-warn:    mat.define-palette(mat.$red-palette);
+
+$rolac-theme: mat.define-light-theme((
+  color: (
+    primary: $rolac-primary,
+    accent:  $rolac-accent,
+    warn:    $rolac-warn,
+  ),
+  typography: mat.define-typography-config(
+    $font-family: 'Inter, sans-serif'
+  ),
+));
+
+@include mat.all-component-themes($rolac-theme);
+```
+
+---
+
+## 5. Kendo UI 元件對應清單
+
+### 核心模組 → Kendo 元件 對應
+
+| 模組 | Kendo 元件 | 用途 |
+|------|-----------|------|
+| **教友管理** | `kendo-grid` | 教友列表（排序、篩選、分頁、匯出） |
+| **教友管理** | `kendo-upload` | 教友照片上傳 |
+| **奉獻記錄** | `kendo-grid` | 奉獻列表（批次輸入、inline edit）|
+| **服事表** | `kendo-scheduler` | 排班日曆（月/週/日 視圖） |
+| **服事表** | `kendo-grid` | 服事同工列表 |
+| **出席報表** | `kendo-chart` `(LineChart)` | 主日出席趨勢折線圖 |
+| **奉獻報表** | `kendo-chart` `(BarChart)` | 月度奉獻長條圖 |
+| **奉獻報表** | `kendo-chart` `(DonutChart)` | 奉獻類型比例 |
+| **教友統計** | `kendo-chart` `(PieChart)` | 教友分佈（年齡/性別） |
+| **所有篩選** | `kendo-datepicker` `kendo-daterangepicker` | 日期範圍篩選 |
+| **所有列表** | `kendo-dropdownlist` | 下拉選單 |
+| **通知** | `kendo-notification` | 操作成功/失敗提示 |
+| **Audit Log** | `kendo-grid` | 稽核記錄（大量資料、虛擬捲動） |
+| **報表匯出** | Kendo Grid 內建 Excel/PDF 匯出 | 一鍵匯出 |
+
+### Kendo Grid 重點設定（教友列表範例）
+
+```typescript
+// members-list.component.html
+<kendo-grid
+  [data]="gridData"
+  [pageSize]="20"
+  [pageable]="{ buttonCount: 5 }"
+  [sortable]="true"
+  [filterable]="'menu'"
+  [reorderable]="true"
+  [resizable]="true"
+  (excelExport)="onExcelExport($event)">
+
+  <ng-template kendoGridToolbarTemplate>
+    <button kendoGridExcelCommand>
+      {{ 'common.exportExcel' | translate }}
+    </button>
+    <button kendoGridPDFCommand>
+      {{ 'common.exportPDF' | translate }}
+    </button>
+  </ng-template>
+
+  <kendo-grid-column field="displayName"
+    [title]="'member.name' | translate" [width]="180">
+  </kendo-grid-column>
+  <kendo-grid-column field="email"
+    [title]="'member.email' | translate" [width]="220">
+  </kendo-grid-column>
+  <!-- ... -->
+
+  <kendo-grid-excel fileName="members.xlsx"></kendo-grid-excel>
+  <kendo-grid-pdf fileName="members.pdf"></kendo-grid-pdf>
+</kendo-grid>
+```
+
+### Kendo Scheduler（服事排班）
+
+```typescript
+// service-roster.component.html
+<kendo-scheduler
+  [kendoSchedulerBinding]="events"
+  [selectedDate]="selectedDate"
+  [views]="['month', 'week', 'day']"
+  (slotClick)="onSlotClick($event)"
+  (eventClick)="onEventClick($event)">
+
+  <kendo-scheduler-month-view></kendo-scheduler-month-view>
+  <kendo-scheduler-week-view></kendo-scheduler-week-view>
+  <kendo-scheduler-day-view></kendo-scheduler-day-view>
+</kendo-scheduler>
+```
+
+---
+
+## 6. Angular Material 使用範圍
+
+Angular Material 負責**基礎 UI 骨架**，Kendo UI 負責**複雜資料元件**。
+
+| Angular Material 元件 | 用途 |
+|----------------------|------|
+| `MatToolbar` | 頂部 Header |
+| `MatSidenav` / `MatDrawer` | 側邊導覽（Desktop） |
+| `MatTabGroup` | Portal 底部分頁（Mobile） |
+| `MatCard` | Dashboard 統計卡片、表單卡片 |
+| `MatDialog` | 確認對話框、新增/編輯 Modal |
+| `MatFormField` + `MatInput` | 所有一般表單欄位 |
+| `MatSelect` | 小型下拉（非大量資料） |
+| `MatButton` / `MatIconButton` | 所有按鈕 |
+| `MatSnackBar` | 輕量操作回饋（儲存成功等） |
+| `MatProgressSpinner` | 載入中動畫 |
+| `MatBadge` | 通知數量角標 |
+| `MatChip` | 標籤（教友分類、服事類型） |
+| `MatIcon` | 系統圖示（搭配 Material Icons） |
+| `MatDivider` | 分隔線 |
+
+---
+
+## 7. 設計系統 (Design Tokens)
+
+共用 Token 確保 Landing Page 與 Admin 視覺一致：
+
+```scss
+// styles/_tokens.scss
+
+// ── 品牌主色 ──
+$color-primary-600: #3B3F8C;   // 深藍靛（主色）
+$color-primary-400: #6366F1;   // 亮藍靛（Hover）
+$color-accent-500:  #D97706;   // 金黃（強調色）
+$color-accent-300:  #FCD34D;   // 淺金（Hover）
+
+// ── 語意色 ──
+$color-success: #16A34A;
+$color-warning: #D97706;
+$color-error:   #DC2626;
+$color-info:    #2563EB;
+
+// ── 中性色 ──
+$color-gray-50:  #F9FAFB;
+$color-gray-100: #F3F4F6;
+$color-gray-700: #374151;
+$color-gray-900: #111827;
+
+// ── 字型 ──
+$font-display: 'Playfair Display', Georgia, serif;   // Landing Page 標題
+$font-body:    'Inter', -apple-system, sans-serif;   // 全域內文
+
+// ── 間距 ──
+$spacing-unit: 8px;
+
+// ── 圓角 ──
+$radius-sm: 4px;
+$radius-md: 8px;
+$radius-lg: 16px;
+$radius-full: 9999px;
+```
+
+> 實際品牌色在開始前與教會確認（教會 Logo 的主色）。
+
+---
+
+## 8. Responsive / Mobile 規範
+
+### Breakpoints
+
+| 名稱 | 寬度 | 描述 |
+|------|------|------|
+| `xs` | < 480px | 小螢幕手機 |
+| `sm` | 480–767px | 一般手機 |
+| `md` | 768–1023px | 平板 |
+| `lg` | ≥ 1024px | 桌機 |
+
+### 各頁面 Mobile 適配規則
+
+| 元件 | Desktop | Mobile |
+|------|---------|--------|
+| 導覽 | 左側 Sidenav（固定展開） | Bottom Tab Bar + 漢堡 |
+| Kendo Grid | 全欄顯示 | 隱藏次要欄，固定姓名欄 |
+| Kendo Scheduler | 月 / 週 視圖 | 僅「Day / Agenda」視圖 |
+| 表單 | 雙欄排版 | 單欄，全寬輸入框 |
+| Chart | 正常尺寸 | 可橫向捲動容器 |
+| Dialog | 置中 Modal | 底部 Sheet（全寬滑上） |
+
+### Capacitor App 專屬考量
+
+```typescript
+// 偵測是否在原生 App 中執行
+import { Capacitor } from '@capacitor/core';
+
+const isNativeApp = Capacitor.isNativePlatform();
+
+// 在 App 中隱藏 Landing Page 導覽
+// 在 App 中使用原生 Back Button 處理 Android
+```
+
+---
+
+## 9. Kendo UI 授權注意事項
+
+> **Kendo UI for Angular 是商業授權產品（Progress/Telerik）。**
+
+| 方案 | 費用 | 適用 |
+|------|------|------|
+| Developer License | ~$999/開發者/年 | 標準商業授權 |
+| **Kendo UI 30-day Trial** | 免費 | 開發評估用 |
+| DevCraft Complete | ~$1,999/年 | 含全套 Telerik 產品 |
+
+**Nonprofit 折扣**
+- Progress/Telerik **沒有標準 Nonprofit 免費方案**
+- 但可以直接寄信至 `sales@telerik.com` 說明是 501(c)(3) 教會，**詢問 Nonprofit Discount**，有時可獲 40–60% 折扣
+- 建議在 Phase 0 確認授權再開始使用
+
+**替代方案（若 Kendo 費用過高）**
+
+| 替代品 | 費用 | Grid | Chart | Scheduler |
+|--------|------|------|-------|-----------|
+| **AG Grid Community** | 免費 | ✅ 強大 | ❌ | ❌ |
+| **ngx-charts** | 免費 | ❌ | ✅ | ❌ |
+| **FullCalendar** | 免費/付費 | ❌ | ❌ | ✅ |
+| **PrimeNG** | 免費 (MIT) | ✅ | ✅ | ✅ 基本 |
+
+> **PrimeNG** 是最接近的免費替代品，如授權談不攏可考慮改用。