ROLAC/docs/UI_ARCHITECTURE.md

# 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** 是最接近的免費替代品，如授權談不攏可考慮改用。