feat(user-display): KeycloakAdminUserResolver — Phase 2 on-demand lookup

Implements the Phase 2 hook from the previous commit. With this in
place, UserDisplayService.find chains:

  hot cache → DB (user_display_cache) → Keycloak Admin API

so any realm user resolves on first display, even if they never made
an authenticated request to ordinis. The resolved entry is persisted
via UserDisplayService.upsert with source=KEYCLOAK_ON_DEMAND, so the
next render of the same sub hits the DB tier (~ms) instead of going
back to Keycloak.

Implementation notes:

- Spring RestClient (modern blocking HTTP, replaces RestTemplate).
- client_credentials grant against
  {issuer}/realms/{realm}/protocol/openid-connect/token. Token cached
  in-memory minus a 30s safety margin from `expires_in`.
- 401 on user lookup wipes the cached token and surfaces a
  RuntimeException, so the next resolve refetches.
- 404 on user lookup → Optional.empty (definitive miss, sub not in
  realm). UserDisplayService logs and the caller falls back to short
  UUID. Negative cache TTL not implemented — added complexity not
  justified for the current realm size (~50 users).
- Bean activated only when ordinis.keycloak.admin.enabled=true AND
  the env vars are set. Default disabled — UserDisplayService treats
  KeycloakUserResolver as @Autowired(required = false), so a
  deployment without Keycloak admin creds keeps the previous behavior
  (DB cache only) instead of crashing on startup.

Application config:
- ORDINIS_KEYCLOAK_ADMIN_ENABLED      (false by default)
- ORDINIS_KEYCLOAK_ADMIN_URL          e.g. https://auth.nstart.space
- ORDINIS_KEYCLOAK_ADMIN_REALM        defaults to nstart
- ORDINIS_KEYCLOAK_ADMIN_CLIENT_ID    via vault (see docs-internal/keycloak-admin-setup.md)
- ORDINIS_KEYCLOAK_ADMIN_CLIENT_SECRET via vault

Setup runbook (docs-internal/keycloak-admin-setup.md) covers:
- creating the Keycloak service-account client + assigning view-users
- writing the secret into both vault instances (different per env)
- wiring vault.hashicorp.com agent-inject annotations into the chart
- verification steps + common failure modes

Phase 3 (scheduled bulk sync) is documented at the end of the runbook
but deferred — depends on observed cache miss rate after this lands.

docs-internal/keycloak-admin-setup.md

@@ -0,0 +1,136 @@
+# Keycloak Admin client setup for UserDisplayService Phase 2
+
+`KeycloakAdminUserResolver` resolves a JWT `sub` against the Keycloak Admin
+REST API on cache miss, so users that never hit ordinis still get a
+display name in audit / reviews / changelog / events / history. Without
+this, only users who personally made an authenticated request show up
+with a real name (the "ток мой UUID отображается" pain).
+
+This is a per-environment one-time setup. Disabled by default — flip on
+once the Keycloak client + vault secret exist.
+
+## Step 1: Create service-account client in Keycloak
+
+Realm: `nstart`. Path: Clients → Create client.
+
+| Field | Value |
+|---|---|
+| Client type | OpenID Connect |
+| Client ID | `ordinis-admin-client` |
+| Client authentication | **On** (confidential) |
+| Authorization | Off |
+| Standard flow | Off |
+| Direct access grants | Off |
+| Service accounts roles | **On** |
+
+Save. On the created client → **Service accounts roles** tab → **Assign
+role** → Filter by clients → `realm-management` → check **`view-users`**
+→ Assign.
+
+(`view-users` is the minimum scope needed for `GET /admin/realms/{realm}/users/{id}`.
+Don't assign `manage-users` — read-only is enough.)
+
+Then **Credentials** tab → copy the `Client secret` (long random string).
+
+## Step 2: Store secret in Vault
+
+The cluster-domain matters here — staging is `265.local`, prod is
+`altum.local`. Both have separate Vault instances.
+
+Staging (cluster.265, namespace `config`):
+```bash
+kubectl -n config exec -it vault-0 -- sh -c '
+  vault login <root-or-admin-token>
+  vault kv put secret/ordinis/cuod/keycloak-admin \
+    client_id=ordinis-admin-client \
+    client_secret=<paste-from-keycloak>
+'
+```
+
+Prod (altum, namespace `vault`):
+```bash
+ssh root@192.168.100.142 'kubectl -n vault exec -it vault-0 -- sh -c "
+  vault login <prod-root-token>
+  vault kv put secret/ordinis/cuod/keycloak-admin \
+    client_id=ordinis-admin-client \
+    client_secret=<paste-from-keycloak>
+"'
+```
+
+⚠️ Different secret per environment — staging and prod have separate
+Keycloak clients (and certainly separate secrets).
+
+## Step 3: Wire into ordinis-app deployment
+
+Add to `ordinis-app` helm chart annotations (vault agent injector
+template) — same pattern as `secret-postgres` / `secret-kafka` already
+present in the chart:
+
+```yaml
+vault.hashicorp.com/agent-inject-secret-keycloak-admin: secret/data/ordinis/cuod/keycloak-admin
+vault.hashicorp.com/agent-inject-template-keycloak-admin: |
+  {{- with secret "secret/data/ordinis/cuod/keycloak-admin" -}}
+  export ORDINIS_KEYCLOAK_ADMIN_CLIENT_ID="{{ .Data.data.client_id }}"
+  export ORDINIS_KEYCLOAK_ADMIN_CLIENT_SECRET="{{ .Data.data.client_secret }}"
+  {{- end }}
+```
+
+Add env vars to the deployment:
+
+```yaml
+env:
+  - name: ORDINIS_KEYCLOAK_ADMIN_ENABLED
+    value: "true"
+  - name: ORDINIS_KEYCLOAK_ADMIN_URL
+    value: "https://auth.nstart.space"   # both envs use the same Keycloak
+  - name: ORDINIS_KEYCLOAK_ADMIN_REALM
+    value: "nstart"
+  # CLIENT_ID + CLIENT_SECRET arrive via the vault-injected
+  # /vault/secrets/keycloak-admin file sourced before java starts.
+```
+
+## Step 4: Verify
+
+After redeploy, check the pod log on startup:
+
+```
+KeycloakAdminUserResolver active — base=https://auth.nstart.space realm=nstart client=ordinis-admin-client
+```
+
+End-to-end:
+
+```bash
+# Find a sub that's NOT in the JVM cache (e.g. a user who never logged in).
+# Hit the display endpoint as an admin user:
+curl -s -H "Authorization: Bearer $TOKEN" \
+  https://ordinis.k8s.265.nstart.cloud/api/v1/admin/users/<uuid>/display | jq
+# Expect 200 with username/name/email even on cold cache, instead of 404.
+```
+
+Then check the DB — the row was persisted from the on-demand resolve:
+
+```sql
+SELECT sub, preferred_username, source, synced_at
+  FROM user_display_cache
+ WHERE sub = '<uuid>';
+-- source = KEYCLOAK_ON_DEMAND
+```
+
+## Step 5: Phase 3 (later — scheduled bulk sync)
+
+When ready to refill the table proactively (avoids the per-user
+on-demand latency for fresh subs), add a Spring `@Scheduled` task that
+calls `GET /admin/realms/{realm}/users` paginated and writes via
+`UserDisplayService.upsertFromKeycloak`. Recommended every 6h. Not
+included in this MR — depends on observed cache miss rate.
+
+## Failure modes
+
+- **Service-account client missing `view-users`** → 403 on lookup,
+  resolver throws RuntimeException, UserDisplayService logs warn,
+  caller falls back to short UUID. No outage, just no resolve.
+- **Keycloak unreachable** → connect timeout / 502. Same fallback as
+  above. Cached entries (DB tier) keep working.
+- **client_secret rotated in Keycloak but vault not updated** → 401 on
+  token request → resolver wipes cached token and surfaces
+  RuntimeException. Update vault secret and the next attempt succeeds.