# 智慧城市後端架構設計 - AWS 部署方案

## 📋 **專案概覽**

智慧城市洞察系統(Smart City Insights)是一個基於 Go 語言開發的企業級 BIM+專案管理平台，整合了 3D 模型查看、進度追蹤、團隊協作等核心功能。本文檔詳細說明了系統的雲端架構設計和 AWS 部署方案。

---

## 🏗️ **系統架構圖**

graph TB
    %% ============ 客戶端層 ============
    subgraph "客戶端層 Client Layer"
        FE[前端應用<br/>Next.js/React]
        MOBILE[移動應用<br/>Mobile App]
        WEB[Web瀏覽器<br/>3D Viewer]
        API_CLIENT[第三方API客戶端<br/>External API Clients]
    end

    %% ============ 負載均衡與CDN ============
    subgraph "網路層 Network Layer"
        CDN[AWS CloudFront CDN<br/>靜態資源分發]
        ALB[AWS Application Load Balancer<br/>負載均衡]
        WAF[AWS WAF<br/>Web應用防火牆]
    end

    %% ============ API Gateway ============
    subgraph "API閘道層 API Gateway"
        APIGW[AWS API Gateway<br/>API管理與限流]
        CORS[CORS處理<br/>跨域請求]
        AUTH_MW[JWT認證中間件<br/>Bearer Token驗證]
    end

    %% ============ 應用服務層 ============
    subgraph "應用服務層 Application Services"
        direction TB

        subgraph "核心API服務 Core API Service"
            MAIN_APP[Go Gin Server<br/>主應用程序<br/>Port: 10000]
            SWAGGER[Swagger UI<br/>API文檔<br/>/swagger/index.html]
        end

        subgraph "業務邏輯模組 Business Logic Modules"
            AUTH_SVC[認證服務<br/>Authentication Service]
            USER_SVC[用戶管理<br/>User Management]
            PROJECT_SVC[專案管理<br/>Project Management]
            TASK_SVC[任務管理<br/>Task Management]
            BIM_SVC[BIM服務<br/>Building Information Modeling]
            CALENDAR_SVC[日曆服務<br/>Calendar Service]
            NOTIFICATION_SVC[通知服務<br/>Notification Service]
            PROGRESS_SVC[進度追蹤<br/>Progress Tracking]
        end

        subgraph "外部服務整合 External Integrations"
            APS_SVC[Autodesk Platform Services<br/>3D模型處理與查看]
            GOOGLE_SVC[Google Services<br/>OAuth & Calendar & Meet]
            LINE_SVC[LINE OAuth<br/>第三方登入]
            WEBHOOK_SVC[Webhook服務<br/>回調處理]
        end
    end

    %% ============ 資料存儲層 ============
    subgraph "資料存儲層 Data Storage Layer"
        subgraph "主資料庫 Primary Database"
            DB[AWS RDS PostgreSQL<br/>主資料庫<br/>Multi-AZ部署]
        end

        subgraph "文件存儲 File Storage"
            S3[AWS S3<br/>BIM模型文件<br/>附件存儲]
            APS_BUCKET[Autodesk雲端儲存<br/>3D模型處理]
        end

        subgraph "快取層 Caching Layer"
            REDIS[AWS ElastiCache Redis<br/>會話快取<br/>API響應快取]
        end
    end

    %% ============ 監控與日誌 ============
    subgraph "監控與日誌 Monitoring & Logging"
        CLOUDWATCH[AWS CloudWatch<br/>系統監控]
        LOGS[AWS CloudWatch Logs<br/>應用日誌]
        METRICS[AWS CloudWatch Metrics<br/>效能指標]
        ALERTS[AWS SNS<br/>告警通知]
    end

    %% ============ 部署基礎設施 ============
    subgraph "部署基礎設施 Deployment Infrastructure"
        ECS[AWS ECS Fargate<br/>容器化部署]
        ECR[AWS ECR<br/>Docker映像儲存庫]
        VPC[AWS VPC<br/>私有網路]
        SECRETS[AWS Secrets Manager<br/>密鑰管理]
    end

    %% ============ 連接關係 ============
    FE --> CDN
    MOBILE --> CDN
    WEB --> CDN
    API_CLIENT --> CDN

    CDN --> WAF
    WAF --> ALB
    ALB --> APIGW

    APIGW --> CORS
    CORS --> AUTH_MW
    AUTH_MW --> MAIN_APP

    MAIN_APP --> SWAGGER
    MAIN_APP --> AUTH_SVC
    MAIN_APP --> USER_SVC
    MAIN_APP --> PROJECT_SVC
    MAIN_APP --> TASK_SVC
    MAIN_APP --> BIM_SVC
    MAIN_APP --> CALENDAR_SVC
    MAIN_APP --> NOTIFICATION_SVC
    MAIN_APP --> PROGRESS_SVC

    BIM_SVC --> APS_SVC
    CALENDAR_SVC --> GOOGLE_SVC
    AUTH_SVC --> GOOGLE_SVC
    AUTH_SVC --> LINE_SVC
    MAIN_APP --> WEBHOOK_SVC

    %% 資料庫連接
    AUTH_SVC --> DB
    USER_SVC --> DB
    PROJECT_SVC --> DB
    TASK_SVC --> DB
    BIM_SVC --> DB
    CALENDAR_SVC --> DB
    NOTIFICATION_SVC --> DB
    PROGRESS_SVC --> DB

    %% 文件存儲連接
    BIM_SVC --> S3
    BIM_SVC --> APS_BUCKET
    USER_SVC --> S3

    %% 快取連接
    AUTH_SVC --> REDIS
    USER_SVC --> REDIS

    %% 監控連接
    MAIN_APP --> CLOUDWATCH
    MAIN_APP --> LOGS
    DB --> METRICS
    REDIS --> METRICS
    METRICS --> ALERTS

    %% 部署連接
    ECS --> MAIN_APP
    ECR --> ECS
    SECRETS --> MAIN_APP
    VPC --> DB
    VPC --> REDIS

---

## 🗃️ **數據庫 Schema 設計**

### **核心數據結構 (65 張表)**

erDiagram
    %% ============ 核心用戶與認證 Core Users & Authentication ============
    users {
        bigint id PK
        varchar username UK
        varchar email UK
        varchar password_hash
        varchar full_name
        varchar phone
        varchar role
        varchar status
        varchar account_id
        text picture
        timestamp created_at
        timestamp updated_at
        timestamp deleted_at
    }

    roles {
        bigint id PK
        varchar name UK
        varchar description
        boolean is_active
        timestamp created_at
        timestamp updated_at
        timestamp deleted_at
    }

    permissions {
        bigint id PK
        varchar name UK
        varchar resource
        varchar action
        varchar description
        timestamp created_at
        timestamp updated_at
        timestamp deleted_at
    }

    user_roles {
        bigint id PK
        bigint user_id FK
        bigint role_id FK
        timestamp assigned_at
        timestamp created_at
        timestamp updated_at
    }

    role_permissions {
        bigint id PK
        bigint role_id FK
        bigint permission_id FK
        timestamp created_at
        timestamp updated_at
    }

    %% ============ 專案與任務管理 Project & Task Management ============
    projects {
        bigint id PK
        varchar name
        text description
        varchar status
        varchar priority
        date start_date
        date end_date
        bigint created_by FK
        jsonb metadata
        timestamp created_at
        timestamp updated_at
        timestamp deleted_at
    }

    tasks {
        bigint id PK
        varchar title
        text description
        varchar status
        varchar priority
        bigint project_id FK
        bigint assigned_to FK
        bigint created_by FK
        datetime due_date
        integer estimated_hours
        varchar delay_reason
        integer delay_days
        boolean is_critical_delay
        jsonb metadata
        timestamp created_at
        timestamp updated_at
        timestamp deleted_at
    }

    task_participants {
        bigint id PK
        bigint task_id FK
        bigint user_id FK
        varchar role
        varchar status
        timestamp created_at
        timestamp updated_at
        timestamp deleted_at
    }

    progress_reports {
        bigint id PK
        bigint project_id FK
        bigint task_id FK
        text content
        varchar status
        decimal progress_percentage
        bigint created_by FK
        timestamp created_at
        timestamp updated_at
        timestamp deleted_at
    }

    %% ============ BIM與3D模型 BIM & 3D Models ============
    bims {
        bigint id PK
        varchar name
        text description
        varchar version
        varchar file_url
        varchar file_type
        bigint file_size
        varchar status
        bigint project_id FK
        bigint uploaded_by FK
        jsonb metadata
        timestamp created_at
        timestamp updated_at
        timestamp deleted_at
    }

    bim_simulations {
        bigint id PK
        jsonb schedule_json
        varchar status
        varchar created_by
        timestamp created_at
        timestamp updated_at
    }

    viewer_events {
        bigint id PK
        bigint user_id FK
        bigint model_id FK
        varchar event_type
        jsonb event_data
        jsonb client_info
        timestamp created_at
    }

    viewer_map_locations {
        bigint id PK
        bigint model_id FK
        decimal latitude
        decimal longitude
        decimal elevation
        decimal rotation
        decimal scale
        text description
        bigint created_by FK
        timestamp created_at
        timestamp updated_at
    }

    %% ============ 團隊與協作 Teams & Collaboration ============
    teams {
        bigint id PK
        varchar name
        text description
        varchar photo_url
        boolean is_active
        bigint created_by FK
        timestamp created_at
        timestamp updated_at
        timestamp deleted_at
    }

    team_members {
        bigint id PK
        bigint team_id FK
        bigint user_id FK
        varchar role
        boolean is_admin
        timestamp joined_at
        timestamp created_at
        timestamp updated_at
        timestamp deleted_at
    }

    %% ============ 通知與訊息 Notifications & Messages ============
    notifications {
        bigint id PK
        varchar type
        varchar title
        text content
        bigint user_id FK
        bigint sender_id FK
        bigint related_id FK
        varchar related_type
        boolean is_read
        jsonb data
        timestamp created_at
        timestamp updated_at
        timestamp deleted_at
    }

    calendar_events {
        bigint id PK
        varchar title
        text description
        timestamp start_time
        timestamp end_time
        boolean all_day
        bigint user_id FK
        varchar location
        jsonb attendees
        varchar google_calendar_id
        varchar google_event_id
        boolean is_synced_to_google
        varchar google_meet_link
        integer reminder_minutes
        timestamp created_at
        timestamp updated_at
        timestamp deleted_at
    }

    %% ============ 文件與附件 Files & Attachments ============
    attachments {
        bigint id PK
        varchar filename
        varchar original_name
        varchar file_type
        bigint file_size
        varchar file_path
        varchar file_url
        bigint related_id FK
        varchar related_type
        bigint uploaded_by FK
        timestamp created_at
        timestamp updated_at
        timestamp deleted_at
    }

    file_versions {
        bigint id PK
        varchar filename
        varchar version
        bigint file_size
        varchar file_path
        bigint created_by FK
        timestamp created_at
        timestamp updated_at
    }

    %% ============ 業務模組 Business Modules ============
    contracts {
        bigint id PK
        bigint project_id FK
        varchar vendor
        date start_date
        date end_date
        text scope
        varchar created_by
        timestamp created_at
    }

    clarifications {
        bigint id PK
        bigint project_id FK
        text question
        text reply
        varchar status
        varchar created_by
        timestamp created_at
        timestamp updated_at
    }

    performance_metrics {
        bigint id PK
        varchar category
        decimal value
        varchar unit
        timestamp timestamp
        varchar created_by
        timestamp created_at
        timestamp updated_at
    }

    manuals {
        bigint id PK
        varchar equipment_ref
        varchar file_path
        varchar created_by
        timestamp created_at
        timestamp updated_at
    }

    handover_logs {
        bigint id PK
        varchar phase
        timestamp handover_time
        varchar receiver
        varchar created_by
        timestamp created_at
        timestamp updated_at
    }

    %% ============ 外部服務整合 External Service Integrations ============
    aps_webhooks {
        bigint id PK
        varchar event_type
        varchar resource_urn
        varchar callback_url
        varchar secret_token
        boolean is_active
        jsonb headers
        jsonb metadata
        bigint created_by FK
        timestamp created_at
        timestamp updated_at
        timestamp deleted_at
    }

    error_logs {
        bigint id PK
        varchar level
        varchar message
        text stack_trace
        varchar user_id
        varchar request_id
        varchar endpoint
        varchar method
        timestamp created_at
    }

    %% ============ 關係定義 Relationships ============
    users ||--o{ user_roles : "has"
    roles ||--o{ user_roles : "assigned_to"
    roles ||--o{ role_permissions : "has"
    permissions ||--o{ role_permissions : "granted_to"

    users ||--o{ projects : "creates"
    users ||--o{ tasks : "assigned_to"
    users ||--o{ tasks : "creates"
    projects ||--o{ tasks : "contains"
    tasks ||--o{ task_participants : "has"
    users ||--o{ task_participants : "participates_in"
    projects ||--o{ progress_reports : "tracks"
    tasks ||--o{ progress_reports : "reports"

    projects ||--o{ bims : "contains"
    users ||--o{ bims : "uploads"
    bims ||--o{ viewer_events : "generates"
    users ||--o{ viewer_events : "performs"
    bims ||--o{ viewer_map_locations : "positioned_at"

    users ||--o{ teams : "creates"
    teams ||--o{ team_members : "has"
    users ||--o{ team_members : "member_of"

    users ||--o{ notifications : "receives"
    users ||--o{ notifications : "sends"
    users ||--o{ calendar_events : "owns"

    users ||--o{ attachments : "uploads"
    users ||--o{ file_versions : "creates"

    projects ||--o{ contracts : "has"
    projects ||--o{ clarifications : "has"

    users ||--o{ aps_webhooks : "creates"

---

## 💻 **核心技術棧**

### **後端技術**

- **語言**: Go 1.21+
- **框架**: Gin Web Framework v1.9+
- **ORM**: GORM v1.25+
- **認證**: JWT + OAuth2 (Google, LINE)
- **API 文檔**: Swagger/OpenAPI 3.0
- **容器化**: Docker + Docker Compose

### **資料庫**

- **主資料庫**: PostgreSQL 15+
- **快取**: Redis 7.0+
- **搜尋引擎**: (可選) Amazon OpenSearch

### **外部服務整合**

- **3D 模型處理**: Autodesk Platform Services (APS)
- **認證服務**: Google OAuth2, LINE Login
- **會議服務**: Google Meet, Google Calendar
- **文件存儲**: AWS S3

---

## ☁️ **AWS 服務架構**

### **計算服務**

| 服務 | 用途 | 規格建議 |
| ----------------------------- | -------------- | ---------------- |
| **ECS Fargate** | 容器化應用部署 | 2 vCPU, 4GB RAM |
| **Application Load Balancer** | 負載均衡 | 跨多 AZ 部署 |
| **Auto Scaling** | 自動擴展 | CPU > 70% 時擴展 |

### **存儲服務**

| 服務 | 用途 | 規格建議 |
| --------------------- | -------- | --------------------------- |
| **RDS PostgreSQL** | 主資料庫 | db.t3.medium, Multi-AZ |
| **ElastiCache Redis** | 快取層 | cache.t3.micro |
| **S3** | 文件存儲 | Standard IA, Lifecycle 管理 |
| **EBS** | 容器存儲 | gp3, 20GB |

### **網路與安全**

| 服務 | 用途 | 配置 |
| ------------------- | -------------- | ---------------- |
| **VPC** | 私有網路 | 10.0.0.0/16 |
| **Security Groups** | 防火牆規則 | 最小權限原則 |
| **WAF** | Web 應用防火牆 | 防 SQL 注入、XSS |
| **Secrets Manager** | 密鑰管理 | 資料庫連接字串 |

### **監控與日誌**

| 服務 | 用途 | 配置 |
| ------------------- | ---------- | ----------- |
| **CloudWatch** | 系統監控 | 自定義指標 |
| **CloudWatch Logs** | 應用日誌 | 7 天保留期 |
| **SNS** | 告警通知 | Email + SMS |
| **X-Ray** | 分散式追蹤 | 效能分析 |

---

## 📊 **API 端點統計**

### **核心 API 模組**

🔐 認證相關: 8個端點
   - /api/v1/auth/login
   - /api/v1/auth/logout
   - /api/v1/auth/register
   - /api/v1/auth/profile
   - /api/v1/auth/change-password

👥 用戶管理: 12個端點
   - /api/v1/users/*
   - /api/v1/teams/*
   - /api/v1/roles/*
   - /api/v1/permissions/*

🏗️ 專案管理: 15個端點
   - /api/v1/projects/*
   - /api/v1/tasks/*
   - /api/v1/progress-reports/*

🏢 BIM系統: 20個端點
   - /api/v1/aps/models/*
   - /api/v1/bim-simulations/*
   - /api/v1/viewer/*

📅 協作功能: 18個端點
   - /api/v1/calendar/*
   - /api/v1/notifications/*
   - /api/v1/messages/*

📎 文件管理: 8個端點
   - /api/v1/attachments/*
   - /api/v1/file-versions/*

總計: 81個活躍API端點

---

_文檔版本: v1.0_
_最後更新: 2025 年 1 月 21 日_
_聯絡人: [e-mail]_