本專案為一個花店商家後台，透過 LINE Bot 將顧客訊息利用 OpenAI API 整理成格式化的訂單資訊（例如顧客姓名、聯絡電話、花材種類、數量、取貨時間及特殊需求）回傳給使用者。商家確認無誤後，資料將會被寫入訂單資料庫中，並可透過 /orders 頁面查詢所有訂單；目前 CSV 匯出由前端在瀏覽器端直接產生下載、DOCX 工單則由後端提供下載，協助商家省下人工抄寫與反覆確認的時間成本。
-
✅ 支援 LINE Bot 接收訊息、自動儲存使用者對話內容
-
✅ 使用 GPT 模型將對話轉換為結構化訂單（透過關鍵字觸發）
-
✅ 以 PostgreSQL 為主資料庫（本機開發常用 Docker 提供；部署環境自備或雲端託管）
-
✅ 管理訂單、顧客資料與歷史訊息
-
✅ 提供
/orders頁面查詢訂單，並支援 CSV 匯出（前端產生下載）與 DOCX 工單匯出（後端下載） -
✅ 前端以 Vue 框架實作，可即時查看與操作訂單系統
-
✅ 使用 Alembic 作資料庫版本控制
-
作業系統：MacOS / Linux / Windows
-
Python：3.8 以上（建議 3.12）
-
Node.js：18+（前端執行需使用）
-
Docker Desktop（建議）：用於本機 PostgreSQL 容器；亦可用於一鍵啟動前後端
git clone <repository-url>
cd <repository-folder>
cd backend
python3 -m venv venv
source venv/bin/activate # Windows 用 venv\Scripts\activate
pip install -r requirements.txt
cd frontend
npm install
在 backend 目錄建立 .env，可複製並修改 backend/.env.example。
若需 LINE Bot 與 OpenAI 功能，金鑰來源如下：
後端會依 POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB、POSTGRES_HOST、POSTGRES_PORT 組出連線字串；若直接在 .env 設定 DATABASE_URL / DATABASE_ALEM_URL，則以該值為優先（見 app/core/settings.py）。
-
本機只跑 uvicorn：通常
POSTGRES_HOST=localhost，POSTGRES_PORT對應到 Docker 對外映射的埠（預設為5433，見下方 資料庫與連線）。 -
docker compose跑 backend 容器：Compose 會覆寫POSTGRES_HOST=db，容器內固定連 compose 服務名，埠為容器內5432。
本機若另外安裝了 Windows 版 PostgreSQL，常見服務名為 postgresql-x64-17，預設會聽 5432。本專案預設將 Docker db 對外映射改為 5433，用來避免衝突並降低連錯實例的風險。
建議擇一：
-
開發時只用 Docker 的 db：以系統管理員開啟 PowerShell，停止本機服務並可改為手動啟動，避免下次開機又佔埠：
Stop-Service -Name "postgresql-x64-17" -Force Set-Service -Name "postgresql-x64-17" -StartupType Manual
-
必須保留本機 PostgreSQL：請自行調整本機服務埠號，或改 Docker
db的ports映射與backend/.env的POSTGRES_PORT，使後端只連到目標那一顆。
docker compose 的 Postgres 資料在 volume db_data（專案內由 Compose 管理），與本機安裝的 PostgreSQL 資料目錄是兩套；只要連線 host／port 固定，就不會寫進兩個地方。
docker compose down -v # 會刪除 volume，資料清空，請謹慎使用
docker compose up -d db
專案支援兩種常見用法：本機分開跑（適合日常改程式） 與 Docker 一鍵跑（適合整包驗收或交作業展示）。
-
在專案根目錄啟動資料庫（對外預設使用 5433，避免與本機 Postgres 的 5432 衝突）：
docker compose up -d db
-
套用 schema（在
backend目錄、已啟用虛擬環境）：cd backend alembic upgrade head -
啟動後端（務必在
backend目錄，否則找不到app模組）：python -m uvicorn app.main:app --reload --port 8000
-
啟動前端：
cd frontend npm run dev -
網址：
-
前端：
http://localhost:5173 -
後端：
http://localhost:8000（Swagger UI 在根路徑/） -
Postgres（由主機連進容器）：
localhost:5433（預設帳號／密碼／資料庫名見backend/.env與docker-compose.yml的db服務）
-
修改過 backend/.env 後，請重啟 uvicorn，否則可能仍沿用舊連線設定。
cd backend
PYTHONPATH=. python app/seeds/seed_all.py
需先安裝 Docker Desktop（Windows／Mac）。
-
備妥
backend/.env（可參考backend/.env.example）。 -
在專案根目錄：
# 第一次或有套件/映像異動時使用 docker compose up --build # 日常開發（不需每次重建） docker compose up
-
開發模式說明（Compose Dev）：
backend與frontend都有掛載 volume，修改程式碼會即時反映- backend 使用
uvicorn --reload - frontend 使用
npm run dev（Vite HMR） - 不需要每次改 code 都
--build
-
服務位址：
-
前端：
http://localhost:5173 -
後端：
http://localhost:8000（Swagger UI 在/） -
Postgres：
localhost:5433（對外埠；容器內 backend 使用服務名db與埠5432）
-
-
關閉：
docker compose down
-
連資料一併刪除（volume）：
docker compose down -v
可使用 ngrok 將本機後端提供給 LINE Webhook：
ngrok http 8000
請至 LINE Developers Console 設定 Webhook URL。本機除錯時請配合 ngrok 或同等隧道；正式環境則改為你的網域，例如：
https://your-domain.example.com/callback
重構期間請以 docs/CONTRACT.md 作為 API 行為基線，並在每次改動後執行：
cd backend
make contract-check若環境可連到測試資料庫，建議再補跑：
cd backend
pytest tests/test_contract_smoke.py-
main.py：主應用與路由掛載 -
api/v1/：新版 API 路由入口（目前逐步轉接既有routes/） -
models/：資料表定義（User、Order、Message、Shipment 等） -
routes/：API 路由模組（linebot、orders、health 等） -
services：實作各種資料庫 CRUD 功能 -
repositories/：資料存取層（重構中，將逐步由 service 下沉查詢邏輯） -
schemas/：定義資料 Input 與 Output 格式 -
core/：設定（含資料庫連線字串組裝）與共用依賴 -
seeds/：測試／假資料產生程式
- Vue 專案：提供聊天室介面、訂單列表等操作頁面
本專案採用 MIT License，歡迎自由使用、修改與商業應用。