From 0e9ce1cd325ae101cdb625875b94a079a631d23f Mon Sep 17 00:00:00 2001
From: Chris <wtc.justin82@gmail.com>
Date: Sun, 29 Mar 2026 23:34:34 +0800
Subject: [PATCH] chore: add local development env files and startup script

---
 backend/.env.development      | 19 +++++++++++++++++++
 backend/README.md             |  2 +-
 backend/scripts/start_dev.sh  |  6 ++++++
 docs/BACKEND_BOOTSTRAP.md     |  6 ++++--
 docs/FRONTEND_ARCHITECTURE.md |  5 +++++
 frontend/.env.development     |  2 ++
 6 files changed, 37 insertions(+), 3 deletions(-)
 create mode 100644 backend/.env.development
 create mode 100755 backend/scripts/start_dev.sh
 create mode 100644 frontend/.env.development

diff --git a/backend/.env.development b/backend/.env.development
new file mode 100644
index 0000000..c164589
--- /dev/null
+++ b/backend/.env.development
@@ -0,0 +1,19 @@
+# memberapi.ose.tw backend env (local development)
+APP_ENV=development
+PORT=8000
+
+DB_HOST=127.0.0.1
+DB_PORT=54321
+DB_NAME=member_center
+DB_USER=member_ose
+DB_PASSWORD=CHANGE_ME
+
+AUTHENTIK_BASE_URL=
+AUTHENTIK_ADMIN_TOKEN=
+AUTHENTIK_VERIFY_TLS=false
+AUTHENTIK_ISSUER=
+AUTHENTIK_JWKS_URL=
+AUTHENTIK_AUDIENCE=
+
+PUBLIC_FRONTEND_ORIGINS=http://127.0.0.1:5173,http://localhost:5173
+INTERNAL_SHARED_SECRET=CHANGE_ME
diff --git a/backend/README.md b/backend/README.md
index b587e39..c26e16b 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -8,7 +8,7 @@ python -m venv .venv
 source .venv/bin/activate
 pip install -e .
 cp .env.example .env
-uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
+./scripts/start_dev.sh
 ```
 
 ## Required DB setup
diff --git a/backend/scripts/start_dev.sh b/backend/scripts/start_dev.sh
new file mode 100755
index 0000000..7fa39aa
--- /dev/null
+++ b/backend/scripts/start_dev.sh
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+source .venv/bin/activate
+exec uvicorn app.main:app --env-file .env.development --host 127.0.0.1 --port 8000 --reload
diff --git a/docs/BACKEND_BOOTSTRAP.md b/docs/BACKEND_BOOTSTRAP.md
index afbd2b9..370b07f 100644
--- a/docs/BACKEND_BOOTSTRAP.md
+++ b/docs/BACKEND_BOOTSTRAP.md
@@ -17,10 +17,12 @@ cp .env.example .env
 ## 3. 啟動服務
 ```bash
 cd member.ose.tw/backend
-source .venv/bin/activate
-uvicorn app.main:app --host 127.0.0.1 --port 8000 --reload
+./scripts/start_dev.sh
 ```
 
+說明：
+- `start_dev.sh` 會用 `--env-file .env.development` 啟動，不需要每次手改 `.env`
+
 ## 4. Authentik JWT 最小設定
 `.env` 至少填一種：
 - `AUTHENTIK_JWKS_URL=<jwks endpoint>`
diff --git a/docs/FRONTEND_ARCHITECTURE.md b/docs/FRONTEND_ARCHITECTURE.md
index fcfb76a..c889c9d 100644
--- a/docs/FRONTEND_ARCHITECTURE.md
+++ b/docs/FRONTEND_ARCHITECTURE.md
@@ -79,3 +79,8 @@
 4. 補通知、loading、錯誤提示
 
 詳細 request/response 契約請看 `docs/FRONTEND_API_CONTRACT.md`。
+
+## 9. 本地開發環境
+- Vite 會自動讀取 `frontend/.env.development`
+- 已預設：
+  - `VITE_API_BASE_URL=http://127.0.0.1:8000`
diff --git a/frontend/.env.development b/frontend/.env.development
new file mode 100644
index 0000000..dd13e1d
--- /dev/null
+++ b/frontend/.env.development
@@ -0,0 +1,2 @@
+VITE_APP_TITLE=member.ose.tw (dev)
+VITE_API_BASE_URL=http://127.0.0.1:8000