Backend

後端專案服務與相關工具說明。

功能開發流程 (Feature Planning)

新功能（例如產品目錄、訂單）請先對齊前端契約、寫計畫文件並經人工確認，再交給 AI 實作。流程如下。

1. 對齊 OpenAPI 契約

從前端專案複製最新的 openapi.yaml，刪掉尚未開始實作的 API（只留下本階段要做的 paths / schemas），合併進本專案的 prompts/openapi.yaml（已實作功能的契約都留在這一份）。

此檔是後端的契約來源：之後的計畫與實作都以它為準。不要在各功能資料夾再放一份 openapi.yaml。

2. 與 AI 討論並寫入獨立計畫資料夾

與 AI 討論本階段的實作計畫與所有細節（範圍、資料模型、搜尋規則、前後端差異、未決問題等），產出的文件放在 prompts/ 底下新建的獨立資料夾（例如 prompts/products/），不要混進其他功能的計畫裡。

建議至少包含：

• 總覽與範圍（in / out of scope）
• API 契約對照
• 資料模型
• 業務規則
• 前端需配合的變更
• 未決問題

可參考現有的 prompts/products/。

3. 先上傳計畫供人討論

計畫文件可以先 commit / 上傳，讓其他人 review 範圍與細節。此時不必實作程式。

4. 確認後再交給 AI 實作

實作計畫確定後，再把該資料夾內的文件（以及已合併的 prompts/openapi.yaml）交給 AI 開始寫程式、migration 與測試。

---

靜態網頁伺服器 (Static Web Server)

專案提供 serve_frontend.py，使用 Python 內建的 http.server 託管已編譯的前端靜態資源（支援 Vue/React 等 SPA 前端路由 Fallback 機制，避免頁面重整出現 404）。

啟動方式

# 預設託管 ../freds-pos-fe/dist，監聽 port 3000
python3 serve_frontend.py

常用參數（透過環境變數）

# 自訂靜態檔案路徑
STATIC_DIR=../freds-pos-fe/dist python3 serve_frontend.py

# 自訂 Port
PORT=8080 python3 serve_frontend.py

---

Python 開發環境設定 (venv)

為了避免套件衝突並確保使用正確的版本，建議使用 Python 內建的 venv 建立獨立虛擬環境：

1. 建立虛擬環境

# 在 be 目錄下建立 .venv 虛擬環境
python3 -m venv .venv

2. 啟用虛擬環境

• Linux / macOS / WSL：

  source .venv/bin/activate
  

• Windows (Command Prompt / PowerShell)：

  .venv\Scripts\activate
  

啟用後，終端機提示字元前會出現 (.venv)，此時所有的 pip install 都會安裝於此隔離環境內。

3. 安裝與管理套件

# 確保 pip 為最新版
pip install --upgrade pip

# 依據 requirements.txt 安裝指定版本的套件
pip install -r requirements.txt

若有新增或更新套件，記得將版本鎖定寫入設定檔：

# 將當前環境安裝的套件版本輸出到 requirements.txt
pip freeze > requirements.txt

4. 退出虛擬環境

deactivate

---

FastAPI 後端服務 (FastAPI Service)

後端主要 API 服務位於 src/ 目錄，基於 FastAPI 框架打造，支援自動 OpenAPI 文件產生、Pydantic 資料驗證以及模組化路由。

目錄結構

src/
├── main.py                 # 應用程式入口點 (FastAPI App, CORS, Root 端點)
├── core/                   # 核心配置 (環境變數設定 Settings, 資料庫連線介面)
│   ├── config.py
│   └── database.py
├── api/                    # 路由層
│   ├── deps.py             # 依賴注入 (Dependencies)
│   └── v1/                 # API v1 版本路由
│       ├── api.py          # 路由彙整
│       └── endpoints/      # 端點邏輯 (health, products, orders 等)
├── schemas/                # Pydantic 資料驗證模型 (Request/Response DTO)
│   ├── common.py
│   ├── product.py
│   └── order.py
├── models/                 # ORM / 資料實體模型 (保留未來資料庫擴充)
└── services/               # 業務邏輯層
    └── product_service.py

啟動 FastAPI 服務

在啟動虛擬環境並安裝 requirements.txt 後，可透過以下方式啟動：

# 方式一：使用本地輔助腳本（自動啟用 .venv 並啟動熱重載）
./run_backend.sh

# 方式二：直接使用 uvicorn 標準指令
uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

互動式 API 文件 (Swagger & ReDoc)

服務啟動後，可直接在瀏覽器造訪：

• Swagger UI：http://localhost:8000/docs
• ReDoc：http://localhost:8000/redoc
• 健康檢查：http://localhost:8000/api/v1/health

---

Google 登入

業務 API 需要已選門市的 session。GET /api/v1/health 與根路徑除外。設定與前端契約見 prompts/auth/01-fe-contract.md。

正式環境至少要：

• DEBUG=false
• GOOGLE_CLIENT_ID：Google Cloud 的 OAuth 用戶端 ID，可逗號分隔多個。不要把 client secret 放到前端。
• AUTH_BOOTSTRAP_ADMIN_EMAIL：只在 oauth_account 還是空的時寫入一位管理員。不要填前端示範信箱。寫入後這個變數不再賦權，刪掉它也不會刪帳號。
• AUTH_BOOTSTRAP_ADMIN_NAME：選填。空白時顯示名稱用 email。
• 套用 migration：alembic upgrade head
• 與前端同一輪上線。這次之後未帶 session 的業務請求會回 401。

Google 用戶端只用 OpenID 的 email（ID token），不要加 Gmail 範圍。

資料庫遷移 (Alembic)

資料庫 schema 變更請透過 Alembic migration，不要直接改資料庫。連線字串由 .env 的 SQLALCHEMY_DATABASE_URI 注入（見 alembic/env.py），預設為本地 SQLite sqlite:///./freds_pos.db。請在專案根目錄、已啟用虛擬環境後執行下列指令。

套用 migration（更新資料庫）

# 查看目前資料庫版本
alembic current

# 套用所有尚未執行的 migration
alembic upgrade head

成功後 alembic current 會顯示最新 revision（例如 9fea24686b8f）。Git commit 只保存 alembic/versions/ 裡的檔案；真正改資料庫的是 alembic upgrade head。

新增 schema 變更

先改 src/models/ 的 ORM，再產生 migration 並套用：

# 依模型差異自動產生 migration 檔
alembic revision --autogenerate -m "describe the change"

# 檢查產生的檔案後套用
alembic upgrade head

Migration 檔會寫入 alembic/versions/，請一併提交到版控。

其他常用指令

# 遷移歷史
alembic history

# 預覽即將執行的 SQL（不寫入資料庫）
alembic upgrade head --sql

# 回退一個版本
alembic downgrade -1

測試

預設使用一個暫存的 SQLite 檔，不需要另外準備資料庫。沒有設定 TEST_DATABASE_URI 時就是這個預設，既有的 CI 不用改：

pytest

庫存地點的外鍵在 PostgreSQL 上會一直生效。SQLite 只在個別測試打開 PRAGMA foreign_keys 時才檢查。要用 PostgreSQL 跑同一套測試，準備一個可丟棄的資料庫，再設定 TEST_DATABASE_URI。不要把正式資料庫的連線字串放在這裡。

TEST_DATABASE_URI=postgresql://USER:[email protected]:5432/freds_test pytest

postgres:// 與 postgresql:// 都會轉成 postgresql+psycopg2://。