# Account Service Admin Settings API

This document summarizes the new `/api/auth/admin/settings` endpoints for managing the permission matrix used by the account service.

## Endpoints

- `GET /api/auth/admin/settings`
  - Requires the caller to present `X-User-Role` or `X-Role` headers with value `admin` or `operator`.
  - Returns the latest permission matrix and associated version. The handler responds with `503 Service Unavailable` when the admin settings database has not been initialised.

- `POST /api/auth/admin/settings`
  - Accepts a JSON payload containing a `version` and `matrix`. The matrix is validated to ensure module keys are non-empty and roles are within the supported set (`admin`, `operator`, `user`).
  - Uses optimistic locking on the `version` field. When the provided version does not match the stored version the handler responds with `409 Conflict` and includes the authoritative matrix.

## Storage Model

- The permission matrix is stored in the `admin_settings` table. GORM manages the model via `internal/model/admin_setting.go` and a dedicated migration script (`sql/20250305-admin-settings.sql`).
- Each cell records `module_key`, `role`, `enabled`, and a monotonically increasing `version` value. Updates occur inside a single transaction that replaces the existing matrix to guarantee consistency across modules and roles.
- The service layer (`internal/service/admin_settings.go`) caches the most recent matrix in-memory and invalidates the cache whenever a write occurs or fails due to a version conflict.

## Test Coverage

Integration tests are provided in `api/admin_settings_test.go`:

- `TestAdminSettingsReadWrite` exercises a full write followed by a read using the operator role.
- `TestAdminSettingsUnauthorized` verifies that callers without an admin/operator role receive `403 Forbidden` responses for both GET and POST.
- `TestAdminSettingsVersionConflict` validates the optimistic locking path by replaying a stale version and asserting a `409 Conflict` response that echoes the authoritative version.

Run the suite with:

```bash
go test ./api -run AdminSettings
```