From 94cec746cb116078adfbd46760ced841c3e4e9de Mon Sep 17 00:00:00 2001
From: Chris <wtc.justin82@gmail.com>
Date: Fri, 3 Apr 2026 14:43:13 +0800
Subject: [PATCH] chore(env): split dev/prod env files and clarify keycloak
 settings

---
 .env.development     | 16 +++++++++++-----
 .env.example         | 35 -----------------------------------
 .env.production      | 41 +++++++++++++++++++++++++++++++++++++++++
 README.md            |  2 +-
 scripts/start_dev.sh |  9 +++------
 5 files changed, 56 insertions(+), 47 deletions(-)
 delete mode 100644 .env.example
 create mode 100644 .env.production

diff --git a/.env.development b/.env.development
index cfe2a44..66d26a0 100644
--- a/.env.development
+++ b/.env.development
@@ -8,17 +8,23 @@ DB_NAME=member_center
 DB_USER=member_ose
 DB_PASSWORD=Dmrax5bKDf
 
-# Keycloak (preferred when KEYCLOAK_BASE_URL + KEYCLOAK_REALM are set)
+# Keycloak 參數說明：
+# - KEYCLOAK_ISSUER 必須與 token 的 iss 完全一致（建議填公開網址）。
+# - KEYCLOAK_BASE_URL 是後端對 Keycloak 的基底網址（development 統一走公開入口）。
+# - KEYCLOAK_JWKS_URL / KEYCLOAK_TOKEN_ENDPOINT / KEYCLOAK_USERINFO_ENDPOINT 可明確覆寫端點。
+# - KEYCLOAK_AUDIENCE 可選，但建議設定以啟用 aud 驗證。
+# - KEYCLOAK_CLIENT_* 給 /auth/oidc/exchange 與 /auth/refresh 使用。
+# - KEYCLOAK_ADMIN_CLIENT_* 給 Keycloak Admin API 同步流程使用。
 KEYCLOAK_BASE_URL=https://auth.ose.tw/
 KEYCLOAK_REALM=master
 KEYCLOAK_VERIFY_TLS=true
-KEYCLOAK_ISSUER=
-KEYCLOAK_JWKS_URL=
+KEYCLOAK_ISSUER=https://auth.ose.tw/realms/master
+KEYCLOAK_JWKS_URL=https://auth.ose.tw/realms/master/protocol/openid-connect/certs
 KEYCLOAK_AUDIENCE=
 KEYCLOAK_CLIENT_ID=member-frontend
 KEYCLOAK_CLIENT_SECRET=bp2I0HWyz5cjcu5RGnBPXNC2vjCdckkv
-KEYCLOAK_TOKEN_ENDPOINT=
-KEYCLOAK_USERINFO_ENDPOINT=
+KEYCLOAK_TOKEN_ENDPOINT=https://auth.ose.tw/realms/master/protocol/openid-connect/token
+KEYCLOAK_USERINFO_ENDPOINT=https://auth.ose.tw/realms/master/protocol/openid-connect/userinfo
 KEYCLOAK_ADMIN_CLIENT_ID=member-backend
 KEYCLOAK_ADMIN_CLIENT_SECRET=hat8BmxlP0eZ7CXuKbV4HwQ3abLHzAJ9
 KEYCLOAK_ADMIN_REALM=master
diff --git a/.env.example b/.env.example
deleted file mode 100644
index f0cf1ec..0000000
--- a/.env.example
+++ /dev/null
@@ -1,35 +0,0 @@
-# memberapi.ose.tw backend env (development)
-APP_ENV=development
-PORT=8000
-
-DB_HOST=postgresql
-DB_PORT=5432
-DB_NAME=member.ose.tw
-DB_USER=member_ose
-DB_PASSWORD=Dmrax5bKDf
-
-# Keycloak (preferred when KEYCLOAK_BASE_URL + KEYCLOAK_REALM are set)
-KEYCLOAK_BASE_URL=https://auth.ose.tw/
-KEYCLOAK_REALM=master
-KEYCLOAK_VERIFY_TLS=true
-KEYCLOAK_ISSUER=
-KEYCLOAK_JWKS_URL=
-KEYCLOAK_AUDIENCE=
-KEYCLOAK_CLIENT_ID=member-frontend
-KEYCLOAK_CLIENT_SECRET=bp2I0HWyz5cjcu5RGnBPXNC2vjCdckkv
-KEYCLOAK_TOKEN_ENDPOINT=
-KEYCLOAK_USERINFO_ENDPOINT=
-KEYCLOAK_ADMIN_CLIENT_ID=member-backend
-KEYCLOAK_ADMIN_CLIENT_SECRET=hat8BmxlP0eZ7CXuKbV4HwQ3abLHzAJ9
-KEYCLOAK_ADMIN_REALM=master
-
-PUBLIC_FRONTEND_ORIGINS=https://member.ose.tw,https://mkt.ose.tw,https://admin.ose.tw
-INTERNAL_SHARED_SECRET=CHANGE_ME
-MEMBER_REQUIRED_REALM_ROLES=admin,manager
-ADMIN_REQUIRED_REALM_ROLES=admin,manager
-
-# Cache backend: memory | redis
-CACHE_BACKEND=redis
-CACHE_REDIS_URL=redis://cache/0
-CACHE_PREFIX=memberapi
-CACHE_DEFAULT_TTL_SECONDS=30
diff --git a/.env.production b/.env.production
new file mode 100644
index 0000000..12f1706
--- /dev/null
+++ b/.env.production
@@ -0,0 +1,41 @@
+# memberapi.ose.tw backend env (development)
+APP_ENV=development
+PORT=8000
+
+DB_HOST=postgresql
+DB_PORT=5432
+DB_NAME=member.ose.tw
+DB_USER=member_ose
+DB_PASSWORD=Dmrax5bKDf
+
+# Keycloak 參數說明：
+# - KEYCLOAK_ISSUER 必須與 token 的 iss 完全一致（建議填公開網址）。
+# - KEYCLOAK_BASE_URL 是後端對 Keycloak 的基底網址（development 統一走公開入口）。
+# - KEYCLOAK_JWKS_URL / KEYCLOAK_TOKEN_ENDPOINT / KEYCLOAK_USERINFO_ENDPOINT 可明確覆寫端點。
+# - KEYCLOAK_AUDIENCE 可選，但建議設定以啟用 aud 驗證。
+# - KEYCLOAK_CLIENT_* 給 /auth/oidc/exchange 與 /auth/refresh 使用。
+# - KEYCLOAK_ADMIN_CLIENT_* 給 Keycloak Admin API 同步流程使用。
+KEYCLOAK_BASE_URL=http://auth_ose_tw:8080
+KEYCLOAK_REALM=master
+KEYCLOAK_VERIFY_TLS=true
+KEYCLOAK_ISSUER=https://auth.ose.tw/realms/master
+KEYCLOAK_JWKS_URL=http://auth_ose_tw:8080/realms/master/protocol/openid-connect/certs
+KEYCLOAK_AUDIENCE=
+KEYCLOAK_CLIENT_ID=member-frontend
+KEYCLOAK_CLIENT_SECRET=bp2I0HWyz5cjcu5RGnBPXNC2vjCdckkv
+KEYCLOAK_TOKEN_ENDPOINT=http://auth_ose_tw:8080/realms/master/protocol/openid-connect/token
+KEYCLOAK_USERINFO_ENDPOINT=http://auth_ose_tw:8080/realms/master/protocol/openid-connect/userinfo
+KEYCLOAK_ADMIN_CLIENT_ID=member-backend
+KEYCLOAK_ADMIN_CLIENT_SECRET=hat8BmxlP0eZ7CXuKbV4HwQ3abLHzAJ9
+KEYCLOAK_ADMIN_REALM=master
+
+PUBLIC_FRONTEND_ORIGINS=https://member.ose.tw,https://mkt.ose.tw,https://admin.ose.tw
+INTERNAL_SHARED_SECRET=CHANGE_ME
+MEMBER_REQUIRED_REALM_ROLES=admin,manager
+ADMIN_REQUIRED_REALM_ROLES=admin,manager
+
+# Cache backend: memory | redis
+CACHE_BACKEND=redis
+CACHE_REDIS_URL=redis://cache/0
+CACHE_PREFIX=memberapi
+CACHE_DEFAULT_TTL_SECONDS=30
diff --git a/README.md b/README.md
index 7078956..15bb581 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ cd backend
 python -m venv .venv
 source .venv/bin/activate
 pip install -e .
-cp .env.example .env
+# local development uses .env.development directly
 psql "$DATABASE_URL" -f scripts/init_schema.sql
 ./scripts/start_dev.sh
 ```
diff --git a/scripts/start_dev.sh b/scripts/start_dev.sh
index 6b3e66b..b78e604 100755
--- a/scripts/start_dev.sh
+++ b/scripts/start_dev.sh
@@ -3,12 +3,9 @@ set -euo pipefail
 
 cd "$(dirname "$0")/.."
 source .venv/bin/activate
-if [ -f ".env.development" ]; then
-  ENV_FILE=".env.development"
-elif [ -f ".env" ]; then
-  ENV_FILE=".env"
-else
-  echo "missing .env.development or .env. copy .env.example first."
+ENV_FILE=".env.development"
+if [ ! -f "$ENV_FILE" ]; then
+  echo "missing $ENV_FILE."
   exit 1
 fi