member-backend/README.md

memberapi.ose.tw backend

Quick start

cd backend
python -m venv .venv
source .venv/bin/activate
pip install -e .
# local development uses .env.development directly
psql "$DATABASE_URL" -f scripts/init_schema.sql
./scripts/start_dev.sh

Docker (VPS / Production)

目前 Dockerfile 為 Alpine 多階段建置（較小體積）。

Build image:

cd backend
docker build -t memberapi-backend:latest .

Run container:

docker run -d \
  --name memberapi-backend \
  --restart unless-stopped \
  -p 127.0.0.1:8000:8000 \
  --env-file .env \
  memberapi-backend:latest

Health check:

curl http://127.0.0.1:8000/healthz

Keycloak env

• Required:
  • KEYCLOAK_BASE_URL
  • KEYCLOAK_REALM
  • KEYCLOAK_CLIENT_ID
  • KEYCLOAK_CLIENT_SECRET
  • KEYCLOAK_ADMIN_CLIENT_ID
  • KEYCLOAK_ADMIN_CLIENT_SECRET
• Optional:
  • KEYCLOAK_ADMIN_REALM (default = KEYCLOAK_REALM)
  • KEYCLOAK_ISSUER
  • KEYCLOAK_JWKS_URL
  • KEYCLOAK_TOKEN_ENDPOINT
  • KEYCLOAK_USERINFO_ENDPOINT
  • KEYCLOAK_AUDIENCE
  • KEYCLOAK_VERIFY_TLS
  • MEMBER_REQUIRED_REALM_ROLES (default: admin,manager)
  • ADMIN_REQUIRED_REALM_ROLES (default: admin,manager)

Main APIs

• GET /healthz
• GET /auth/oidc/url
• POST /auth/oidc/exchange
• GET /me (Bearer token required)
• GET /me/permissions/snapshot (Bearer token required)

Admin APIs (Bearer + admin realm role required)

• GET/POST/PATCH/DELETE /admin/companies
• GET/POST/PATCH/DELETE /admin/sites
• GET/POST/PATCH/DELETE /admin/systems
• GET/POST/PATCH/DELETE /admin/roles
• GET/POST/PATCH/DELETE /admin/members
• PUT /admin/sites/{site_key}/roles
• PUT /admin/members/{user_sub}/sites
• GET /admin/members/{user_sub}/roles
• GET/POST/PATCH/DELETE /admin/api-clients

roles 現在包含 role_code 欄位（建議用於跨系統權限語意解析）；role_key 保留為唯一識別鍵。

Internal APIs (X-Client-Key + X-API-Key)

• GET /internal/companies
• GET /internal/sites
• GET /internal/systems
• GET /internal/roles
• GET /internal/members
• POST /internal/users/upsert-by-sub
• GET /internal/users/{user_sub}/roles
• POST /internal/provider/users/ensure

DB Migration

• 既有 DB 升級（新增 roles.role_code）：

psql "$DATABASE_URL" -f scripts/migrate_add_role_code.sql