# memberapi.ose.tw backend

## Quick start

```bash
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env
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`

### 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`