安安,我是 ChiYu!
前兩天,我們完成了專案的「出生證明」(專案章程) 和「使用者地圖」(使用者故事)。我們現在非常清楚「為誰而做」以及「他們想做什麼」。
今天,我們要戴上「工程安全帽」,從使用者的世界暫時抽離,化身為擘劃未來的 「系統架構師」。我們要進行一次視角切換,從關注「人」,轉向關注「系統」,回答一個核心問題:「為了滿足這些使用者故事,我們的系統內部應該長什麼樣子?」
我們今天要畫的,不僅是建築的藍圖,更是未來系統穩定、高效、可擴展的基石。
在我們深入探討具體的架構之前,你必須先理解現代網頁開發中最核心的一個思想——前後端分離 (Frontend-Backend Separation)。
讓我們再次回到「經營一家餐廳」的比喻。一家餐廳,最基本的劃分就是「外場」與「內場」。
HTML
, CSS
, JavaScript
這三劍客負責打造。Python
+ Flask
應用程式。「前後端分離」就是一個嚴格的規定:外場的人不准進内場,內場的人也不准跑去外場。他們之間唯一的溝通管道,就是透過「服務生」來傳遞標準化格式的「點餐單」與「餐點」。
這個至關重要的「服務生」,就是我們常說的 API (Application Programming Interface)
。
API 的本質,就是一份前端與後端之間,神聖不可侵犯的「溝通契約」。這份契約詳細地定義了:
有了這份契約,前端的「室內設計師」和後端的「大廚」就可以完全獨立、並行地工作,只要最後雙方都遵守契約,就能完美地將各自的成果組合起來。這份詳細的契約(Web API 規格書),將會是我們在 Day 10 的主題。
好了,理解了前後端的分工與 API 的角色後,現在我們可以聚焦在「如何設計我們的廚房 (後端)」了。
隨著我們的餐廳生意越來越好,菜色越來越多(功能越來越複雜)時,如果還把所有廚師都擠在一個廚房裡 (app.py
),肯定會天下大亂。
因此,我們需要升級成「中央廚房」模式。我們會把廚房細分成「冷盤區」、「熱炒區」、「甜點區」,每個區域有專門的師傅負責。這在我們的後端專案中,就是所謂的**「模組化 (Modularity)」**。
在 Flask
框架中,實現模組化的最佳實踐,就是使用**「藍圖 (Blueprints)」**。你可以把一個 Blueprint
想像成一個獨立的「功能模組包」。例如,我們可以規劃一個 habits.py
檔案,裡面專門放所有跟「習慣」相關的 API 路由。
因此,在我們動手寫任何一行 Python
程式碼之前,我們就要先在這份架構文件中,規劃好我們未來的專案結構。
好了,觀念釐清,讓我們再次召喚 Gemini CLI,請它扮演我們的首席架構師。
打開 VS Code 終端機,詠唱我們的第三個「文件生成咒語」:
# 角色 (Role)
你是一位資深的軟體架構師,精通 Python Flask 與模組化設計,特別擅長使用 Blueprints 來組織可擴展、可維護的 Web 應用程式。你的設計決策總是兼顧當前的 MVP 需求與未來的擴展性。
# 目標 (Objective)
我的目標是讓你根據專案的初始文件,設計一份專業的「高階設計文檔 (High-Level Design, HLD)」,這份文件將作為開發團隊的技術核心指南。
# 上下文 (Context)
- **核心依據**: 你的所有設計都必須嚴格基於以下兩份文件:
1. `@docs/PROJECT_CHARTER.md` (定義了業務目標與範圍)
2. `@docs/USER_STORIES.md` (定義了核心功能與使用者流程)
---
## 你的任務與產出要求 (Your Task & Output Requirements)
你的產出物是一份正式的技術文檔。請嚴格遵循以下大綱結構,確保內容的專業性與完整性。
### 1. 文件元數據 (Document Metadata)
- **文件標題**: `高階設計文檔 (High-Level Design)`
- **文件版本**: `v1.0.0`
- **作者**: `Gemini (軟體架構師)`
### 2. 架構總覽 (Architecture Overview)
- **核心架構**: 說明我們將採用「**前後端分離 (Headless)**」架構。
- **設計原則**: 解釋此架構選擇背後的 **3 個主要優點** (例如:獨立開發與部署、技術棧靈活性、更好的擴展性)。
- **溝通方式**: 強調前後端將透過 **RESTful API** 進行通訊,並以 **JSON** 作為數據交換格式。
### 3. 技術選型與理由 (Technology Stack & Justification)
- 以表格形式,條列出 MVP 階段後端開發所需的核心技術。
- 表格欄位需包含「**技術領域**」、「**選擇**」與「**選擇理由 (WHY)**」。
- 至少需包含以下領域:
- Web 框架 (Web Framework)
- 資料庫 (Database)
- ORM (Object-Relational Mapping)
- 資料驗證 (Data Validation)
### 4. 後端專案結構 (Backend Project Structure)
- 簡要說明採用 **Flask Blueprints** 進行模組化設計的核心目的(關注點分離)。
- 使用文字樹狀圖,清晰地展示推薦的後端專案結構。
- 在樹狀圖的關鍵目錄旁,**用註解簡要說明該目錄的職責** (例如:`blueprints/` 存放各功能模組)。
### 5. 高階架構圖 (High-Level Architecture Diagram)
- 使用 **Mermaid.js 的 `graph TD` 語法**,繪製一張清晰的系統架構圖。
- 圖中必須包含以下四個主要元件及其互動關係:「**使用者 (Client/Browser)**」、「**前端應用 (React/Vue)**」、「**後端 API (Flask)**」、「**資料庫 (PostgreSQL/SQLite)**」。
### 6. 最終產出指令 (Final Output Command)
- **執行動作**: 將以上所有產出合併到同一個 Markdown 檔案中,命名為 `ARCHITECTURE.md`,並放置於 `@docs` 資料夾內。
```
### 【預期成果與分析】
當你按下 Enter,稍待片刻,Gemini 就會化身為你的首席架構師,產出一份結構清晰、內容專業的軟體架構文件。請仔細審核這份由 AI 生成的草稿,特別是它對「後端專案結構」的規劃,這將是我們後續 Vibe Coding 的重要依據。
---
### 軟體架構文件:習慣養成與心情日誌
(原先想呈現markdown語法,但因為又內嵌了程式碼區塊,會導致版型整個跑掉,
``` markdown
### 架構文件
- **文件標題**: 高階設計文檔 (High-Level Design)
- **文件版本**: v1.0.0
- **作者**: Gemini (軟體架構師)
---
## 1. 架構總覽 (Architecture Overview)
為了實現最大的靈活性與可擴展性,`心境軌跡 (MindTrack)` 將採用**前後端分離 (Headless)** 的現代化架構。
#### 設計原則與優勢
此架構的選擇基於以下三個核心優點:
1. **獨立開發與部署**: 前端與後端團隊可以並行開發、測試及部署,互不阻塞。後端專注於業務邏輯與數據,前端專注於使用者體驗,大幅提升開發效率。
2. **技術棧靈活性**: 允許我們為工作的不同部分選擇最適合的技術(例如,前端使用 React/Vue,後端使用 Python/Flask)。未來若需升級或替換某一層的技術,對另一層的影響也降至最低。
3. **多平台擴展性**: 一套統一的後端 API 可以同時服務於目前的 Web 應用、未來的原生行動應用 (iOS/Android) 或其他第三方服務,實現一次開發、多端復用。
#### 溝通方式
- 前端與後端之間的所有通訊,將透過標準的 **RESTful API** 進行。
- 數據交換格式統一採用輕量級的 **JSON** 格式。
---
## 2. 技術選型與理由 (Technology Stack & Justification)
以下是 MVP 階段後端開發的核心技術選型:
| 技術領域 | 選擇 | 選擇理由 (WHY) |
| :----------- | :------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Web 框架** | **Flask** | 輕量、靈活,擁有龐大的擴充套件生態。非常適合從 MVP 快速啟動,並能隨著業務複雜度平滑擴展。 |
| **資料庫** | **SQLite (開發) / PostgreSQL (生產)** | **SQLite** 無需額外設定,極適合作為本地開發資料庫。**PostgreSQL** 功能強大、穩定可靠,是應對生產環境高併發與數據一致性需求的不二之選。 |
| **ORM** | **Flask-SQLAlchemy** | 作為 Flask 的官方 ORM 套件,它簡化了所有資料庫操作,能有效防止 SQL 注入攻擊,並讓我們能以 Pythonic 的方式與資料庫互動。 |
| **資料驗證** | **Flask-Marshmallow** | 提供強大的物件序列化 (Serialization) 與反序列化 (Deserialization) 功能,能輕鬆定義清晰的 API 資料結構 (Schema),並自動完成傳入數據的驗證,確保 API 的健壯性。 |
---
## 3. 後端專案結構 (Backend Project Structure)
我們將採用 **Flask Blueprints** 來組織專案,將不同功能的程式碼(如認證、習慣管理)封裝到獨立的模組中。這能有效實現「**關注點分離 (Separation of Concerns)**」,讓專案在擴展時依然保持清晰、可維護。
``` mermaid
/mindtrack-api
|-- app/ # 核心應用程式目錄
| |-- __init__.py # 應用程式工廠 (App Factory)
| |-- blueprints/ # 存放所有功能藍圖
| | |-- auth/ # 處理使用者認證 (註冊、登入)
| | | |-- __init__.py
| | | `-- routes.py
| | |-- habits/ # 處理習慣與心情的增刪改查
| | | |-- __init__.py
| | | `-- routes.py
| | `-- insights/ # 處理數據洞察相關邏輯
| | |-- __init__.py
| | `-- routes.py
| |-- models.py # SQLAlchemy 資料庫模型
| |-- schemas.py # Marshmallow 資料驗證結構
| `-- extensions.py # 集中管理 Flask 擴充套件實例
|-- migrations/ # 資料庫遷移腳本 (Alembic)
|-- tests/ # 單元測試與整合測試
|-- config.py # 環境設定檔 (開發、生產)
|-- run.py # 應用程式啟動入口
`-- .flaskenv # Flask 環境變數
```
---
## 4. 高階架構圖 (High-Level Architecture Diagram)
``` mermaid
graph TD
subgraph "使用者端"
Client["使用者 (瀏覽器)"]
end
subgraph "前端應用 (Frontend)"
FrontendApp["React / Vue.js App"]
end
subgraph "後端應用 (Backend API)"
BackendAPI["Flask API"]
end
subgraph "資料庫 (Database)"
DB[("Database (PostgreSQL / SQLite)")]
end
Client -- "請求 (Request)" --> FrontendApp
FrontendApp -- "API 請求" --> BackendAPI
BackendAPI -- "查詢 (Query)" --> DB
DB -- "回傳資料 (Data)" --> BackendAPI
BackendAPI -- "API 回應 (Response)" --> FrontendApp
FrontendApp -- "更新畫面 (UI Update)" --> Client
```
預覽架構圖:
在 VS Code 中,打開 ARCHITECTURE.md 的預覽模式 (Ctrl+Shift+V)。看到文字瞬間變成清晰的圖表,這就是**「文件即程式碼 (Docs-as-Code)」**的魅力!
提交變更:
ARCHITECTURE.md
按 +
(Stage Changes)。docs: Add software architecture document
太棒了!今天,我們為專案打下了最穩固的「地基」。我們不只知道要做什麼(使用者故事),更清楚整個系統將如何運作(軟體架構)。有了這份結構藍圖,我們的專案才真正從一個「點子」,進化成了一個「可執行的計畫」。
接下來的兩天,我們將會完成後端藍圖的最後兩塊拼圖。
完成這兩份文件後,我們整個後端的藍圖才算真正大功告成!