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. 啟用虛擬環境
啟用後，終端機提示字元前會出現 (.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)
服務啟動後，可直接在瀏覽器造訪：
Google 登入
業務 API 需要已選門市的 session。GET /api/v1/health 與根路徑除外。設定與前端契約見 prompts/auth/01-fe-contract.md。
正式環境至少要：
DEBUG=falseGOOGLE_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://。
