96 lines
2.3 KiB
Markdown
96 lines
2.3 KiB
Markdown
# memberapi.ose.tw backend
|
||
|
||
## Quick start
|
||
|
||
```bash
|
||
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:
|
||
```bash
|
||
cd backend
|
||
docker build -t memberapi-backend:latest .
|
||
```
|
||
|
||
Run container:
|
||
```bash
|
||
docker run -d \
|
||
--name memberapi-backend \
|
||
--restart unless-stopped \
|
||
-p 127.0.0.1:8000:8000 \
|
||
--env-file .env \
|
||
memberapi-backend:latest
|
||
```
|
||
|
||
Health check:
|
||
```bash
|
||
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`）：
|
||
```bash
|
||
psql "$DATABASE_URL" -f scripts/migrate_add_role_code.sql
|
||
```
|